Introduction
On your platform, you can configure single sign-on (SSO), which allows users to log in using credentials from an external account—such as an institutional system, a corporate network, or another identity provider.
- When SSO is enabled, users do not need to enter a username and password created specifically for the platform.
- Instead, they can click a login button (or be automatically redirected) to authenticate through the external identity provider’s page, after which they are securely returned to the platform.
This article covers configuration details and troubleshooting guidance that apply across different SSO setups. The information here complements that provided in the article specific to your particular protocol or integration.
Types of SSO configurations
The learning platform supports multiple ways of configuring single sign-on, including standard protocols as well as direct integrations:
Standard protocols
- Open ID connect protocol: You can set up the Open ID connect app to configure single-sign on with your chosen identity provider, such as Okta, Salesforce, Onelogin, Microsoft Entra ID, etc.
- SAML protocol: You can similarly set up the SAML app to configure single sign-on using a variety of identity providers.
Please note: For each protocol you can set up only one identity provider on the same domain (root platform or extended enterprise). For example, if you set up OpenID Connect with Okta as the identity provider, you cannot configure another OpenID Connect instance with a different identity provider on the same domain. However, you can do this on a separate extended enterprise domain.
Direct integrations
The platform also supports a variety of direct SSO integrations with identity providers, including Auth0, Gmail and Google Apps.
External single sign-on
It is also possible to force unauthenticated users to a specified external SSO URL. In the SSO tab of the API and SSO app, flag the Force external SSO option and enter the required external SSO URL. With this setting, when users access the platform URL they will be automatically redirected to the specified external SSO URL.
Please note: The Force external SSO option, when enabled, overrides all other sign-in methods:
- The standard login page will not be shown, so users cannot sign in with platform credentials, nor use any SSO buttons on the standard login page.
- Also, the redirect to the external SSO URL takes precedence over any automatic redirects to identity provider that you configure for other SSO methods.
In practice, it means only the external SSO URL can be used for accessing the platform.
SSO behavior
→ You will see these settings when configuring SSO via the OpenID Connect or SAML protocols, or via the direct Auth0 integration.
The SSO behavior settings let you configure how users will log in to the platform through single sign-on. There are two options available: Show standard login page and Automatic redirect to identity provide
Show standard login page:
With this option, when users click Sign in on the platform header, they will see the normal Sign in form with fields for entering the platform credentials.
- If you also select Show SSO button on login page, underneath the username and password fields, users will see a button to Sign in with SSO. This button will have a logo corresponding to the particular SSO protocol or identity provider configured.
- When they click this SSO button they are redirected to a page for authenticating with the identity provider, and if the authentication is successful they are signed in to the platform.
Tip: In Navigation menu > Customization (shapes icon) > Branding and design > Sign in page you can set the option Show only SSO buttons and hide login form, in this case the Sign in form will show only the SSO buttons, but not the username and password fields.
Please note: If you do not choose to show the SSO button, users will be unable to initiate SSO login from the platform home page.
Automatic redirect to identity provider:
With this second option, users do not see the platform’s sign-in form and do not need to click any SSO login button. Instead, when they attempt to access the platform URL, they are automatically redirected to the page for authenticating with the identity provider. Then, if the authentication is successful, they are signed in to the platform.
Please note that with the automatic redirect option users cannot view the public page and they are unable to choose between alternative sign-in options. With this method, they are required to authenticate with the configured identity provider.
It is best practice to avoid enabling Automatic redirect to identity provider until you have confirmed that SSO is working correctly. Otherwise, you risk locking yourself out of the platform if the redirect is active and SSO is not functioning.
Notes on automatic redirect:
If some of your users are not managed by the identity provider (IdP), and need to access the platform with native credentials, do not enable Automatic redirect to identity provider, as this would prevent non-IdP users from logging in.
Instead, choose the option Show SSO button on login page:
- This allows users managed by the IdP to sign in via SSO, while users outside the IdP can continue to log in using the platform’s native login form.
- The Extended Enterprise app can also be used to configure different sign-in behaviors for specific user groups or audiences.
Logout landing page
With automatic redirect, when a user logs out of the platform they will be sent to a default “logout successful” landing page. There they can either close the page or or use the re-login button to authenticate again.
If desired, you can redirect users who log out to a different page, by entering its URL in the Logout landing page field.
Logout behavior
→ You will see these settings when configuring SSO via the OpenID Connect or SAML protocols, or via the direct Auth0 integration.
The Logout behavior option lets you set whether the user should also be automatically logged out of the identity provider when they log out of the platform.
- In some SSO configurations, when this option is selected, a Logout endpoint text field appears. Here you can define a URL where users will land upon logging out from the platform and from the identity provider.
Please note: To avoid conflicts, if you are using Automatic redirect to identity provider you should not enable the Logout behavior option.
Username attribute
→ You will see this setting when configuring SSO via the OpenID Connect or SAML protocols, or via the direct Auth0 integration
When you implement single sign-on (SSO) through an identity provider, the decision about whether a user logging in via SSO already exists within the platform typically depends on a unique identifier field received from the identity provider.
In the Username attribute field, you can set the field you want to use for this purpose:
- When making your selection, make sure that the selected field is populated for all your users in the identity provider.
- The selected field should also be unique. For example, if you select family_name, you must be sure that none of your users have the same family name in the identity provider.
- For example, you can use email as the Username attribute, provided all your users have distinct emails on the provider side.
The identity provider field you select in Username attribute will be matched (by default*) to the Username field on the platform. This means that:
- If the two fields match, the user authenticating via SSO is considered to already exist in the platform, and will be logged in to that account.
- If no matching Username is found in the platform, then the SSO user does not yet exist in the platform, but can be automatically created if you configure User provisioning.
*only in the SAML standard configuration, you can change this default to pick a different field.
User provisioning
→ You will see these settings when configuring SSO via the OpenID Connect or SAML protocols, or via the direct Auth0 integration
User provisioning allows you to automatically create a new user in the platform if the SSO authentication is valid but that user does not yet exist in the platform. It also allows you to automatically update the details of a user in the platform based on the corresponding information in the SSO identity provider.
Tip: By default, a user is considered to already exist in the platform if their Username matches the identity provider field you set as the Username attribute. See the chapter Username attribute.
Creation of provisioned users
When you Enable user provisioning, a user logging in via SSO who does not yet exist in the platform will be created on the fly, with platform Username = the provider field set in Username attribute.
Note on default branch placement: For SSO on the root platform, newly created users will be placed in the root branch. For SSO on an extended enterprise client, newly created users will be placed in the branch associated with the client.
Add more provisioned fields
In addition to the Username, you may want to populate other details of a provisioned user using the information retrieved from the identity provider.
You configure this in the Add fields section. This will appear slightly different depending on which SSO configuration you are using, but in all cases it allows you to match up other fields on the identity provider side with the corresponding platform fields.
Note that each platform field and identity provider field can be used only once. You cannot match multiple platform fields to the same IdP field, or vice versa.
Tip: If in the platform Advanced settings > Self-registration you flagged the option First and last name are required to register, ensure that you include these fields in the Add fields section, so that the provisioned users can be created.
Similarly, if you have set some user additional fields as mandatory in the platform, make sure these are mapped here so they can be populated, as otherwise the user cannot be correctly created.
Update the provisioned fields
Select the If user already exists, update the user information check box to automatically update, within the platform, the values of any provisioned fields that have been changed on the identity provider end. If you do not select this option, you will need to manually copy over any changes to keep the provisioned fields aligned.
Lock provisioned user fields
Select the Lock provisioned user fields check box to prevent users from editing, in My profile, any user fields that are provisioned. Those fields will appear grayed out and marked disabled, so that the user cannot change the value obtained from the identity provider.
→ Note, however, that a Superadmin or Power User can still edit the values of these locked provisioned fields in User management with the following limitation: Only the user information fields can be edited, whereas additional user fields, if locked, cannot be edited by anyone.
If you have more than one SSO method configured, you may encounter issues due interactions between locked fields. For details about this see the chapter Provisioning conflicts between multiple SSO configurations
Please note that all the provisioning settings described here apply only to users who log in via SSO (single-sign-on). For example, locked provisioned fields will not be disabled for users who log in using platform credentials.
Provisioning conflicts between multiple SSO configurations
It is recommended to avoid having multiple SSO methods active with provisioning on the same domain, as interference or conflicts may occur. These issues can arise even if some SSO providers are not fully configured.
Note that here we are referring to a situation where multiple SSO providers are active on the same root platform or the same extended enterprise client/domain. You can, however, employ different SSO methods on different domains.
Interaction between locked fields with multiple SSO providers
On platforms with more than one active SSO provider for the same domain, you may encounter inconsistent field locking behavior if both providers have Provisioning enabled but different settings for Lock provisioned fields (one set to ON, the other to OFF).
For example:
- Fields may remain locked even for the provider with locking set to OFF
- Conversely, fields may be unlocked for the provider with locking set to ON
→ Note that this behavior occurs only when multiple SSO providers are active on the same root platform or the same extended enterprise client/domain. However, locked field settings in one domain do not affect other domains.
SSOs with different provisioned fields and locking options
A related issue that can occur is when two SSO configurations have different provisioned additional fields, in particular where one SSO provisions and locks a mandatory field that the other SSO does not provision. For example:
- SSO 1: set up to provision the mandatory user additional field “myfield”, with Lock provisioned fields option flagged
- SSO 2: does NOT provision “myfield”
If a user signs in with SSO 2, the login may fail because “myfield” is mandatory but cannot be filled in because it is locked by SSO 1.
To resolve provisioning conflicts:
If you encounter a provisioning conflict such as the ones described above, you can resolve it in the following ways:
- If possible, consider having only one SSO method configured on any given domain (root platform or extended enterprise client).
- If you do require multiple SSO methods, keep provisioning enabled on only one of them, and disable provisioning from the other SSOs (the affected users should then be added to the SSO that has provisioning enabled, and updated with a login)
- If you have to keep multiple SSOs with provisioning, be sure to carefully align the user provisioning configurations of all SSOs so that they have the same additional fields and locking options. In particular make sure that mandatory user additional fields are provisioned.
- If a mandatory additional field is causing the problem, set it in the platform as not mandatory.