External authentication providers

You can set up single sign-on (SSO) authentication using external providers.

Sitecore Content Hub is compatible with the following external authentication providers:

Azure AD
Google
Microsoft
OpenID Connect
SAML
Sitecore Identity
WS-Federation
Yandex

You configure the external authentication providers in the ExternalAuthenticationProviders property:

RequestResponse

"ExternalAuthenticationProviders": {
    "global_email_claim_type": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "global_username_claim_type": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
    "google": [],
    "microsoft": [],
    "open_id_connect": [],
    "saml": [],
    "sitecore": [],
    "ws_federation": [],
    "yandex": []
}

global_email_claim_type and global_username_claim_type set the claim types to resolve the email addresses and usernames for all providers. You can override these properties for a specific provider.

The base configuration is similar for all service providers, but some of them also have specific properties.

Note

The configuration example can help you configure the authentication provider you need.

Base configuration

The following code shows the base configuration for all providers:

RequestResponse

{
  "authentication_mode": "Passive",
  "email_claim_type": "<ClaimTypeOverride>",
  "external_user_creation_url": "https://www.registerme.com",
  "is_enabled": true,
  "messages": {
    "signIn": "translationKey",
    "signInDescription": "translationKey",
    "signInTitle": "translationKey"
  },
  "provider_name": "<name>",
  "username_claim_type": "<ClaimTypeOverride>",
  "user_linking": {
      "user_profile_property_name": "Email",
      "claim_type": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  }
}

Property	Description
`authentication_mode`	Can be `Active` or `Passive`. If a provider is set as `Active`, the system automatically redirects users to the login page of that provider if they are not yet authenticated. You must ensure that only one provider is set as `Active` at a time. Users can also log in through the local account page by navigating to: https://localhost/en-us/account?forcePassive=true, without you making changes to the authentication configuration.
`email_claim_type`	Overrides the `global_email_claim_type` property for this provider. You can configure claim types in the authentication setting so that a custom email claim can be set as the email address (for example, `"email_claim_type": "http://schemas.auth0.com/CustomEmailClaim"`).
`external_user_creation_url`	Overrides the `AutoCreateUsers` property and redirects to the provided URL.
`is_enabled`	Enables the provider. Only enabled providers are displayed and can be registered in the authentication pipeline.
`messages`	Modifies the default sign-in button display. `signIn` - button message. `signInTitle` - helptext shown when hovering the mouse over the button. `signInDescription` - description shown next to the button. The values must be existing translation keys.
`provider_name`	Name of the external provider. This name: Is mandatory Must be unique. Must be alphanumeric. Is case-insensitive. Can be no longer than 50 characters.
`username_claim_type`	Overrides the `global_username_claim_type` property for this provider.
`user_linking`	Lets you link different identity provider accounts to the same Content Hub user account. You can configure `user_linking` globally for all external authentication providers or you can override each specific external authentication provider. By default, users are linked together when they have the same email address. `user_profile_property_name` must point to a culture-insensitive (not multilanguage), scalar (not multivalue), and unique string property in the `M.UserProfile` entity definition. Only the `Email` property doesn't need to be unique. `claim_type` must point to a unique claim returned by the provider. The value of the claim must be a scalar property. Warning The login procedure will fail if: Multiple claims match the specified claim type. No claim matches the specified claim type. The value of the specified claim type is whitespace or empty. Multiple user profiles match the value read from the specified claim type. If no user profile matches the specified claim type, the system will proceed by considering this user as a new user.

Note

Properties that pass claims to the authentication setting, such as the email_claim_type and the user_claim_type, can use a custom email claim as the email address (for example, "email_claim_type": "http://schemas.auth0.com/CustomEmailClaim".

Important

The provider name is used to set up unique REST API callbacks to support multiple external authentication providers of the same type. Usually, this callback must be configured in the external authentication provider itself. Modifying the provider name requires changes to the external authentication provider as well. By default, the callback URL has the following format: /signin-{provider-name}.

Provider-specific properties

The following table describes the properties specific to each external provider.

Note

Full configuration examples are available for Azure AD and OpenID Connect.

Provider	Property	Description	Mandatory
Google	`client_id`	OAuth client ID.	Yes
	`client_secret`	OAuth client secret.	Yes
Microsoft	`client_id`	OAuth client ID.	Yes
	`client_secret`	OAuth client secret.	Yes
	`authorization_endpoint`	Overrides the authorization endpoint.	No
	`token_endpoint`	Overrides the token endpoint.	No
	`user_information_endpoint`	Overrides the user information endpoint.	No
OpenID Connect	`authentication_mode`	The authentication mode can be set to `Active` or `Passive`, but only one provider can be active at a time. In `Active` mode, users are automatically redirected to the provider’s login page if they are not authenticated. In `Passive` mode, users must manually click the provider's button on the login page.	No
	`client_id`	A unique identifier for the client application, used to authenticate your Content Hub application with the Identity Provider.	Yes
	`client_secret`	A secret known only to the application and the authorization server, used to authenticate the Content Hub application.	Yes
	`authority`	The URL of the OpenID Connect provider, used to discover the provider's configuration and endpoints.	No
	`get_claims_from_user_info_endpoint`	Whether to retrieve claims from the `UserInfo` endpoint. If set to false, an `id_token` with claims must be provided for each authentication.	No
	`metadata_address`	The URL for the OpenID Connect provider's metadata, which includes endpoint details and supported features. Avoid hosting a copy of this file, as provider certificate changes can break authentication.	No
	`signed_out_redirect_uri`	The URL where the user is redirected after signing out.	No
	`redirect_uri`	The URL where the authorization server redirects the user after authentication. This must be registered with the authorization server.	No
	`authentication_method`	The method used for authentication. The following values are whitelisted: `redirect_get`, `form_post`.	No
	`response_mode`	How the authentication response is returned. The following values are whitelisted: `query`, `form_post`, and `fragment`.	No
	`response_type`	The type of response expected from the authorization server. The following values are whitelisted: `code`, `code id_token`, `code id_token token`, `code token`, `id_token`, `id_token token`, `none`, and `token`.	No
	`prompt`	Whether the user should be prompted for re-authentication. The following values are whitelisted: `none`, `login`, `consent`, and `select_account`.	No
	`email_claim_type`	The claim type used for the user's email address.	No
	`external_user_creation_url`	The URL used for creating external users.	No
	`is_enabled`	Whether OpenID Connect is enabled. This allows temporarily disabling an identity provider without removing its configuration.	No
	`messages`	Custom messages for the sign-in process. The following values are whitelisted: `signIn`, `signInTitle`, and `signInDescription`.	No
	`provider_name`	The name of the OpenID Connect provider, also used as the redirect URI in the IdP, formatted as `{HOST}/signin-{PROVIDER_NAME}`.	No
	`username_claim_type`	The claim type that defines the user's username.	No
	`clear_default_scope`	Whether to clear the default scope.	No
	`scope`	The scopes requested during authentication. The following values are whitelisted: `openid`, `profile`, and `email`. The `openid` scope is always required for an OpenID Connect authentication.	No
SAML	`certificate`	Path to the certificate that the identity provider uses to sign its messages. Only required if `AuthnRequestsSigned` is `true` in the the service provider metadata file.	No
	`idp_entity_id`	Entity ID of the identity provider.	Yes
	`metadata_location`	URL of the source metadata endpoint for the identity provider (IdP). You can automatically generate the SP_metadata.xml file using the `/AuthServices-{providerNameInTheAuthenticationSettings}` endpoint. This file contains the IdP configuration information and is used for SSO authentication. Its contents remain unchanged unless the environment URL is modified. The `metadata_location` is accessed during every login, and the XML file containing the IdP configuration is not cached by Content Hub. Therefore, if your IdP endpoint is updated or modified, the configuration changes will apply immediately. Important Do not copy the IdP metadata file or host it on Content Hub.	Yes
	`password`	Password used to access the certificate.	No
	`sp_entity_id`	Entity ID of the service provider.	Yes
	`module_path`	Application root relative path for SAML endpoints. Defaults to `/AuthServices-` followed by the provider name in lowercase. It is case-sensitive and must be unique.	No
	`binding`	Binding type used when sending authentication requests to the identity provider. Accepted values are: `HttpRedirect` (default) and `HttpPost` Artifact.	No
	`authn_request_protocol_binding`	Binding type the identity provider is requested to use when responding. Included in the `ProtocolBinding` attribute of the authentication request. Accepted values are: `HttpPost` Artifact.	No
Sitecore	`identity_server_url`	URL of the Sitecore Identity server instance to which users are redirected during the sign-in process.	Yes
	`client_id`	OAuth client ID as known by the identity server.	Yes
	`client_secret`	OAuth client secret as known by the identity server.	Yes
WsFederation	`metadata_address`	URL exposing the XML metadata of a WsFederation service provider.	Yes
	`wtrealm`	URL of the requesting realm.	Yes
Yandex	`client_id`	OAuth client ID.	Yes
	`client_secret`	OAuth client secret.	Yes

Do you have some feedback for us?

If you have suggestions for improving this article,