SSO

Current version: 3.2

Introduction

SSO enables users to log in to Sitecore Content Hub using OAuth authentication providers. For accessing the page navigate to "Manage" > "Settings" > "Authentication," then change the formatting from "Tree" to "Text" on the toolbar of the JSON structure and proceed with modifying your configuration as required.

Configuration

Structure

The behaviour of SSO can be configured in the Authentication setting in the PortalConfiguration category.

The setting looks as follows:

RequestResponseshell
...
  "authentication": {
    "enableBasicAuthentication": true,
    "enableRegister": true,
    "showRegister": true,
    "enableExternalAuthentication": true,
    "enableConfirmationMail": false,
    "enableEmailWhiteList": false,
    "enableLockout": true,
    "registrationLink": "http://www.registerme.com",
    "minutesToLockout": 5,
    "attemptsBeforeLockout": 5,
    "autoRestrict": true,
    "enableCredentialless": true,
    "cookieName": "authCookie",
    "cookieDomain": "marketingcontenthub.com",
    "expireTimeSpan": 30,
    "tokenLifespan": 1440,
    "usernameClaimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "emailClaimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "postSignOutRedirectUrl": "/en-us/account",
    "defaultUserGroups": [
      "usergroup1",
      "usergroup2",
      "usergroup3"
    ],
    "whiteListedEmailPatterns": [
      "pattern1",
      "pattern2",
      "pattern3"
    ],
    "PasswordRules": {
      "RequiredLength": 6,
      "RequireLowercase": true,
      "RequireUppercase": true,
      "RequireDigit": true,
      "RequireNonLetterOrDigit": true
    },
    "PasswordExpiration": 129600,
    "ReCaptcha": {
      "Key": "<key>",
      "Secret": "<secret>"
    },
    "Providers": [
      {
        "$type": "Stylelabs.M.Portal.Authentication.GoogleAuthenticationProviderConfigurator, Stylelabs.M.Portal",
        "client_id": "",
        "client_secret": "",
        "is_enabled": false,
        "external_user_creation_url": "http://my-external-user-creation-url.com",
        "messages": {
          "signIn": "T_translationKey",
          "signInTitle": "T_translationKey",
          "signInDescription": "T_translationKey"
        }
      },
      {
        "$type": "Stylelabs.M.Portal.Authentication.MicrosoftAuthenticationProviderConfigurator, Stylelabs.M.Portal",
        "client_id": "",
        "client_secret": "",
        "authentication_mode": "Passive",
        "is_enabled": false,
        "external_user_creation_url": "http://my-external-user-creation-url.com",
        "messages": {
          "signIn": "T_translationKey",
          "signInTitle": "T_translationKey",
          "signInDescription": "T_translationKey"
        }
      },
      {
        "$type": "Stylelabs.M.Portal.Authentication.WsFederationAuthenticationMethodConfigurator, Stylelabs.M.Portal",
        "metadata_address": "",
        "authentication_type": "WsFederation",
        "wtrealm": "",
        "authentication_mode": "Passive",
        "is_enabled": false,
        "external_user_creation_url": "http://my-external-user-creation-url.com",
        "messages": {
          "signIn": "T_translationKey",
          "signInTitle": "T_translationKey",
          "signInDescription": "T_translationKey"
        }
      },
      {
        "$type": "Stylelabs.M.Portal.Authentication.SamlAuthenticationProviderConfigurator, Stylelabs.M.Portal",
        "metadata_location": "",
        "sp_entity_id": "",
        "idp_entity_id": "",
        "provider_name": "SAML",
        "authentication_mode": "Passive",
        "username_claim_type": "EmailAddress",
        "email_claim_type": "EmailAddress",
        "is_enabled": false,
        "external_user_creation_url": "http://my-external-user-creation-url.com",
        "messages": {
          "signIn": "T_translationKey",
          "signInTitle": "T_translationKey",
          "signInDescription": "T_translationKey"
        }
      },
      {
        "$type": "Stylelabs.M.Portal.Authentication.SitecoreAuthenticationProviderConfigurator, Stylelabs.M.Portal",
        "identity_server_url": "",
        "client_id": "",
        "client_secret": "",
        "authentication_mode": "Passive",
        "username_claim_type": "name",
        "email_claim_type": "email",
        "external_user_creation_url": "http://my-external-user-creation-url.com",
        "is_enabled": false,
        "messages": {
          "signIn": "T_translationKey",
          "signInTitle": "T_translationKey",
          "signInDescription": "T_translationKey"
        }
      },
      {
        "$type": "Stylelabs.M.Portal.Authentication.YandexAuthenticationProviderConfigurator, Stylelabs.M.Portal",
        "app_id": "",
        "app_password": "",
        "is_enabled": false,
        "external_user_creation_url": "http://my-external-user-creation-url.com",
        "messages": {
          "signIn": "T_translationKey",
          "signInTitle": "T_translationKey",
          "signInDescription": "T_translationKey"
        }
      }
    ]
  }
...

Attributes

  • enableBasicAuthentication (options; default=True): If set to 'True', users can login using username and password on the login page.
  • enableRegister (optional; default=True): If set to 'True', users can create a new account by accessing the "Register" page. Note that this doesn't mean there has to be a "register"-link on the login-page. The parameter only makes the "Register" page accessible.
  • showRegister (optional; default=True): If set to 'True', a link to the "Register" page is shown on the "Login" page.
  • enableExternalAuthentication (optional; default=True): If set to 'True', external authentication is enabled and users can login using one of the configured OAuth providers.
  • enableConfirmationMail (optional; default=True): If set to 'True', e-mail confirmation is required for a user to access the system. When a user creates a new account, a confirmation e-mail is sent. Users can only login to the application after clicking the link in the e-mail.
  • enableEmailWhiteList (optional; default=False): If set to 'True', only users with e-mail addresses that match one of the configured patterns are allowed to create an account in the system. The patterns are configured in the "whiteListedEmailPatterns" section.
  • enableLockout (optional; default=True): If set to 'True', user accounts are automatically locked out after a configured amount of failed login attempts.
  • registrationLink (optional; default=""): If specified, users are redirected to the specified url when clicking the "register"-link on the login page.
  • minutesToLockout (optional; default=5): The amount of time a user is locked out of the system.
  • attemptsBeforeLockout (optional; default=5): The number of failed login attempts before a user is locked out of the system.
  • autoRestrict (optional; default=False): If set to 'True', newly created users are automatically restricted. This means they can only access a special landing-page until an Administrators verifies their account.
  • enableCredentialless (optional; default=False): If set to 'True', users can login using an external login provider without having to create an account in M. This means they don't need to specify a username and password. Exact behaviour depends on autoCreateUsers.
  • usernameClaimType (optional; default=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress): External login providers specify usernames using this claim-type.
  • emailClaimType (optional; default=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress): External login providers specify e-mail addresses using this claim-type.
  • cookieName (optional): The name of the authentication cookie.
  • cookieDomain (optional): The domain used for the authentication cookie.
  • expireTimeSpan (optional): The timespan in minutes before authentication cookie expires, default is set to 30 minutes.
  • tokenLifespan (optional): The timespan in minutes before password reset/confirmation token becomes invalid. Default value is 1 day.
  • autoCreateUsers (optional; default=False): If enableCredentialless is set to "True", new user accounts are automatically created. If an account with the specified username already exists, the external login is linked to that account.
  • postSignOutRedirectUrl (optional; default=""): Users will be redirected to the specified URL after signing out of the application. If this attribute is not specified, users are redirected back to the login page.
  • PasswordRules (optional, default: length: 6, all other attributes set to true): Rules that will be used to validate user password on creation/change/reset.
  • PasswordExpiration (optional; default=129600): The time in minutes for a password to expire. Users will be prompted to change their password once it's expired. Defaults to 90 days.
  • ReCaptcha (optional): If both the Key and Secret values are present, recaptcha widget will be shown on the user registration screen.

Overrides

The following "global" attributes can be overridden on the provider level:

  • username_claim_type
  • email_claim_type

Elements

Providers

The following providers are available:

With OAuth

  • Google
  • Microsoft
  • Yandex

For an example check out the Structure snippet. The client-id and client-secret are generated by the OAuth provider.

Note that OAuth providers don't support the "AuthenticationMode" option. They will always be added as passive providers.

Customizing the Sign in messages for the SSO providers

By default, when configuring an SSO provider, it will automatically display a new button on the login page with the label Sign in with 'the provider name'. This label can be customized and localized. You can also customize the message when you hover over the button, and even add a small help text to describe the provider.

This can be done by adding the messages dictionary in the configuration of the provider like shown in the Structure snippet. The messages dictionary can contain the 3 following keys:

  • signIn: for the button's message.
  • signInTitle: for the message when you hover over the button.
  • signInDescription: to add a small description for the provider.

The values must be the name of an existing translation entity key (e.g: "T_MyOwnCustomKey"). You can create you own translation entities on the translation admin page under the manage page.

Redirecting to another user creation page

When autoCreateUsers is set to true, a new user account is automatically created. However, when set to false, you are by default redirected to an error page. It is possible to override this behavior to redirect to an external user creation page instead by using the external_user_creation_url parameter in the provider configuration like shown in the Structure snippet.

Saml

Example:

RequestResponseshell
{
  "$type": "Stylelabs.M.Portal.Authentication.SamlAuthenticationProviderConfigurator, Stylelabs.M.Portal",
  "metadata_location": "",
  "sp_entity_id": "",
  "idp_entity_id": "",
  "provider_name": "SAML",
  "authentication_mode": "Passive",
  "is_enabled": false
}

Properties:

  • metadataLocation (required): The url or path pointing to the XML metadata of a SAML service provider.
  • spEntityId (required): The entity-id of the service provider.
  • idpEntityId (required): The entity-id of the identity provider.
  • providerName (optional, default=SAML): The name of the identity provider, as shown in the UI.
  • authenticationMode (optional; default=Passive): If set to "Active", the website will automatically redirect to the provider's login page. If set to passive, the user has to click the "Use SAML authentication" button, after which she is redirected to the provider's login page.
Note

Content Hub does not support signed authentication requests via certificates.

It's possible to configure multiple SAML providers. This can be done by simply specifying multiple objects of type "Stylelabs.M.Portal.Authentication.SamlAuthenticationProviderConfigurator, Stylelabs.M.Portal" in the "providers" section.

Most SAML providers require a callback URL. When a user has been authenticated, they will post a SAML token to this URL. By default, the callback url will always be in the following format: "https://marketingcontenthub/AuthServices-{provider-name-lowercase}/Acs".

Notes:

  • Multiple SAML providers are only support when they're all set to "authentication_mode = Passive". If one of the providers is "Active", the application will automatically redirect users to that provider's login page.
  • If multiple SAML providers are used, make sure they all have a unique "provider_name". The provider-name will be used in the callback-url, so it cannot contain any spaces or slashes.
WsFederation

Example:

RequestResponseshell
{
  "$type": "Stylelabs.M.Portal.Authentication.WsFederationAuthenticationMethodConfigurator, Stylelabs.M.Portal",
  "metadata_address": "",
  "authentication_type": "WsFederation",
  "wtrealm": "",
  "authentication_mode": "Passive",
  "is_enabled": false
}

Properties:

  • metadataUrl (required): Url that exposes the XML metadata of a WsFederation service provider.
  • applicationId (required): Unique id of the application, as provided by the WsFederation service provider.
  • providerName (optional, default=WsFederation): The name of the identity provider, as shown in the UI.
  • authenticationMode (optional; default=Passive): If set to "Active", the website will automatically redirect to the provider's login page. If set to passive, the user has to click the "Use SAML authentication" button, after which she is redirected to the provider's login page.

Sitecore

Example:

RequestResponseshell
{
  "$type": "Stylelabs.M.Portal.Authentication.SitecoreAuthenticationProviderConfigurator, Stylelabs.M.Portal",
  "identity_server_url": "",
  "client_id": "",
  "client_secret": "",
  "authentication_mode": "Passive",
  "username_claim_type": "name",
  "email_claim_type": "email",
  "is_enabled": false
}

Properties:

  • identity_server_url (required): Sitecore uses IdentityServer for authentication. This url should point to the identity-server instance to which users will be redirected during the signin process.
  • client_id (required): OAuth client id as known by the IdentityServer instance.
  • client_secret (required): OAuth client secret as known by the IdentityServer instance.
  • providerName (optional; default=Sitecore): The name of the identity provider, as shown in the UI.
  • authenticationMode (optional; default=Passive): If set to "Active", the website will automatically redirect to the provider's login page. If set to passive, the user has to click the "Use Sitecore authentication" button, after which she is redirected to the provider's login page.

The example overrides "username_claim_type" and "email_claim_type". This is because the default configuration of Sitecore's IdentityServer does not use the standardized claim-types for name and password. They use "name" and "e-mail" instead. See "Overrides" for more information.

DefaultUserGroups

When a new user is created in the system, she can be added to one or more default user-groups. The values in this collection can reference both existing and non-existing user-groups. User-groups that don't exist are created automatically. If this element is not included, the user isn't added to any user-groups.

WhiteListedEmailPatterns

This element is only relevant if "enableEmailWhiteList" is set to "True". Each value in the collection contains a regular expression. Users can only create an account in the system if their e-mail address matches at least one of those regular expressions.

Credentialless

When the flag "enableCredentialless" is set to "True" and a new user logs on to the system:

  • If no user with the specified username exists in the system:
    • If "autoCreateUsers=True": a new user account is created
    • If "autoCreateUsers=False": the user is not allowed to login to the system.
  • If a user account with the specified username already exists: the login is linked to the existing user account.

Email-templates

The system sends out e-mails on a couple of occasions. It uses Stylelabs.M.Mailing to do this.

The following mail-templates are used:

  • ConfirmAccount: Sent out when a user needs to confirm her e-mail address after creating a new account. The following variables can be used:
    • confirm_link: The link to the confirm password page.
    • base_url: The base url of the application. Can be used to reference images.
  • ResetPassword: Sent out when a user clicked the "forgot password" button or when an administrator resets a user's password. The following variables can be used:
    • reset_link: The link to the reset password page.
    • base_url: The base url of the application.

Management

The following section repeatedly uses the term "administrators". By "administrators", we mean users who have the permissions to manage other users (read other user entities).

Reset password

Administrators can reset other user's passwords by clicking the "reset password" button on the user detail page. Note that administrators need to have the "ResetUserPassword" privilege to be able to do this. If they don't have this privilege, the button won't be shown.

When user's password has been reset, a "reset-password" mail is sent out. The e-mail contains a link that redirects the user to a change-password page.

Unlock

Administrators can unlock users that have been locked out by clearing the "LockoutEndDate" property on the user detail page.

ATTENTION: If the administrator himself has been locked out, the only way to unlock him is by using the "UnlockUser" command from the command-line.

This command can also be used to unlock any other user.

Extensibility

Sitecore DAM provides a Scripting API to integrate custom scripts in their business logic so it is possible for users to extend the SSO feature. This can be done by the configuration of new Identity Servers using the Scripting API.

Note

For further information, please see the documentation on Cloud development.

Do you have some feedback for us?

If you have suggestions for improving this article,