Single sign-on (SSO)

Single-sign on (SSO) settings used to configure the ability to sign in to the portal front end and portal backoffice with social network accounts. For signing in to the front end using SSO, you must also add the corresponding buttons on the sign-in page for each SSO provider you set up here.

SSO providers are configured separately for back end and front end.

To configure SSO settings

1. In the backoffice, go to Media > OAuth & SSO settings.
2. Select the SSO settings tab.
   
3. Next to Providers. select Add content to add a new SSO provider or select an existing one to edit.
4. Fill in the fields as described below:
   • Authentication provider – Specifies the authentication provider for which these settings will apply. Select one of the supported authentication providers:
     •  Facebook
     •  Google
     •  Microsoft
     •  X (former Twitter)
   • CMS provider - With this switch enables, the SSO provider settings will be applied to the portal CMS. If this switch is disabled, the SSO provider settings will be applied to the portal front end (in this case, also ensure you configure SSO settings for this provider on the sign-in page).
   • Client ID – Specifies the client ID that was registered for this SSO provider on the corresponding SSO provider site:
     • Facebook: for this SSO provider, the Xpand Portal app must be registered on this site. For more information on how to set up the Facebook app, refer to this guide or follow the steps below. For information on how to lock down your Facebook app settings, refer to this guide.
     • Google: for this SSO provider, the Xpand Portal app must be registered on this site. For more information on how to set up your Google app, refer to this guide or follow the steps below.
     • Microsoft: for this SSO provider, the Xpand Portal app must be registered on this site. For more information on how to configure your App Service app to use Microsoft Account login, see this guide or follow the steps below.
     • X: for this SSO provider, the Xpand Portal app must be registered on this site. For more information on how to set up your X app, refer to this guide or follow the steps below.
   • Client secret – Specifies the client secret that was registered for this SSO provider on the corresponding SSO provider site (see the Client ID setting above).
   • Icon – Specifies the image that will be used as the button to sign in with a social network that corresponds to this authentication provider. You can leave this setting empty to use the predefined icon. If this setting is also filled in on the login page, the setting on the login page will be used.
   • CSS class name – Specifies the name of the CSS (Cascading Style Sheets), which can be used to apply styles to the sign-in link of this authentication provider. This setting is optional. If this setting is also filled in on the login page, the setting on the login page will be used.
   • Other settings - Use this setting to specify additional provider settings, which might be required for your SSO provider.
     • External service name - Specifies the name of an external service, for which value needs to be specified in the Value field. The availability of additional settings available for selection depends on the additional features implemented on the portal.
     • Value - Specifies the value of the selected service. You may need to enter, for example, the app ID, the app key, etc., depending on the additional setting type.
     • Comment - Specifies a description of the external service. You can use this field to add a note about the setting if necessary.
5. Repeat steps 3 and 4 to add more providers. Ensure you add a pair of setting sets for each provider, one setting set for front end (the CMS provider switch is disabled) and one setting set for back end (the CMS provider switch is enabled)
6. In the backoffice, select Settings > More > Reload Application.

   Important You must reload application whenever you make changes in the Media section of the backoffice. Otherwise, your changes may not take effect.

Facebook app registration

To register your app on Facebook, follow these steps:

1. Go to https://developers.facebook.com/ and sign in using your Facebook account or create a new one.
2. Select My Apps. If you haven't registered yet, first select Get started and register with your Facebook account.

   

3. In the window that opens, select Create App.
   
   
    
4. In App details, specify the app name and app contact email, and then select Next.
   
5. In Use cases, select Authenticate and request data from users with Facebook Login, and then select Next.
   
6. In Business, select I don't want to connect a business portfolio yet, and then select Next.
   
7. In Requirements, you get an overview of requirements that you need to complete to get and maintain access to user and business data. Select Next.
   
8. In Overview, select Go to dashboard.
   
9. Go to App settings > Basic and copy the client ID from the App ID field and the client secret from the App secret field—you will need them for further configuration of the SSO settings on Xpand Portal.
   
10. Fill in the mandatory fields (Privacy Policy URL, User data deletion, Category) and upload the app icon, and then select Save changes.
    
11. Go to Use cases and select Customize next to the Authenticate and request data from users with Facebook Login use case. 
    
12. In the Settings section, under Valid OAuth Redirect URIs, add the following redirect URIs, and then select Save Changes:
    
    https://[yourportaldomain]/umbraco-facebook-signin
    https://[yourportaldomain]/umbraco/Surface/Member/externallogin-facebook
    
    where [yourportaldomain] is the domain where your Xpand Portal solution is deployed.
    

13. To get access to data from users, Meta requires business verification. Go to Review > Verification and select Start verification and then follow the prompts on the screen. Only people with full control of a Business Account can complete this process. Learn more about business verification.

14. After business verification, submit your app for review and approval: go to Review > App Review and select Edit, and then select Submit for Review. The previous steps must be completed. The app review process may take up to 5 days.
    
    
15. Once the app is reviewed and approved, publish the app: go to Publish, and select the Publish button.

Google app registration

To register your app on Google, follow these steps:

1. Go to Google Cloud Platform and sign in with your Google account or create a new one.
2. On the header, select the Select a project action.
3. In the Select a project window that opens, select New project.
   
4. In the New Project window, add the name of your app and select Create.
   
5. On the OAuth Overview page, select Get started and fill in the required fields. 
   
6. Select Create to finish the project creation.
   
7. On the OAuth Overview page, select Create OAuth client.
   
8. In the window that opens, on the navigation pane on the left, select OAuth consent screen.
9. In the Create OAuth client ID window, in the drop-down menu, select Web application.
   
10. In the Create OAuth client ID window that opens, enter the client name.
11. Under Authorised redirect URIs, select Add URI  and add the links given below, and then select Create.
    • https://[yourportaldomain]/umbraco-google-signin
    • https://[yourportaldomain]/umbraco/Surface/Member/externallogin-google
      
      where [yourportaldomain] is the domain where your Xpand Portal solution is deployed.
      
      

      Note Google Cloud only allows redirect URIs with public top level domain (such as .com or .org). To be able to use Google as a SSO provider, your portal domain must meet this requirement.

12. From the OAuth client created message that appears, copy the client ID from the Client ID field, and the client secret—from the Client secret field, as you will need them for further configuration of the SSO settings on Xpand Portal, and then select OK.
    

Microsoft app registration

To register your app in the Microsoft Azure portal, follow these steps:

1. Go to App registrations in the Azure portal. If needed, sign in with your Microsoft account (you will need an administrator Microsoft account).
2. Select New registration, then enter an application name.
   
   

   Note Only Microsoft accounts with administrator permissions can create new app registrations.

3. In the Register an application window, enter the name of the application (leave the Redirect URI section empty for now), and then select Register.
   
4. In the App registrations window, open the registered app by selecting its name in the app list.
   
5. In the Overview section, select Add a certificate or secret next to Client credentials.
    
6. In the Certificates & secrets window that opens, under Client secrets, select New client secret.
   
7. In the Add a client secret window, fill in the required fields, and then select Add.
   
8. Copy the client secret from the Value field as you will need it for further configuration of the SSO settings on Xpand Portal.
   

   Note Make sure to copy the client secret from the Value field as you will not be able to access it in future.

9. In the navigation pane on the left, select Overview and copy the client ID from the Application (Client) ID field as you will need it for further configuration of the SSO settings on Xpand Portal.
   
10. Select Add a Redirect URI next to Redirect URIs.
    
11. In the Authentication window that opens, under Platform configurations, select Add a platform.
    
12. In the Configure platforms window that appears, select Web. 
    
13. In the Configure Web window, fill in the Redirect URIs field with one of the the values given below, and then select Configure.
    

    https://[yourportaldomain]/umbraco-active-directory-signin
    https://[yourportaldomain]/umbraco/Surface/Member/externallogin-active-directory
    
    where [yourportaldomain] is the domain where your Xpand Portal solution is deployed.

    

14. Use the Add URI action that appears to add the second redirect URI, and then select Save.
    

X app registration

To register your app on X Developer Platform, follow these steps:

1. Go to X Developer Portal, and then sign in with your X Developer Portal account or create a new one.

   Note If you do not have a Developer Account on X yet and are planning to create a new one, it may take several days to register and approve it.

2. Select Create Project.
   
3. Specify the project name, and then select Next.
4. Choose the project use case, and then select Next.
5. On the project's Overview page, select +Add App.
   
6. Enter a name for the app, and then select Next.
7. Copy the client ID from the API Key field and the client secret from the API Secret Key field as you will need them for further configuration of the SSO settings on Xpand Portal, and then select App settings.
   

   Important Make sure you copy the  API Key (Client ID) and API Secret Key (Client Secret) field values as this will be the last time you have access to them.

8. Select Set up next to User authentication Settings.
   
9. Under Type of App, select Web App Automated App or Bot.
10. Under App Info, in the Callback URI / Redirect URL field, add the following two URLs:
    • https://[yourportaldomain]/umbraco-twitter-signin
    • https://[yourportaldomain]/umbraco/Surface/Member/externallogin-twitter
      
      where [yourportaldomain] is the domain where your Xpand Portal solution is deployed.
      
11. Copy the client ID and client secret (however, specifically for SSO settings on the portal side, you will need the API Key (Client ID) and API Secret Key (Client Secret) that you saved earlier), and then select Done.