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
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,