Understanding Sitecore authentication behavior changes

Version: 10.4

Sitecore Identity (SI) uses the federated authentication features introduced in Sitecore 9.0. These features build upon OWIN authentication middleware. However, in Sitecore 9.0, OWIN authentication integration and federated authentication are both disabled by default.

In Sitecore 9.1 and later, Sitecore Identity is enabled by default. OWIN authentication and federated authentication are also enabled, because they are required by SI. 

This topic describes changes in Sitecore authentication behavior and outlines how to:

Configure authentication scope

By default, Sitecore configures the SI server provider to handle authentication for the Sitecore Client sites, for example shell and admin, only. This means if you authenticate in shell through the SI server, website does not accept that user and you  are anonymous in the website. It also means that if you use the GetSignInUrlInfoPipeline pipeline to generate sign-in links on your website, then the login link to sign-in with SI server does not unexpectedly appear there.

To configure authentication scope:

  • In the mapEntry nodes under the sitecore/federatedAuthentication/identityProvidersPerSites/ node, specify the combinations between sites and identity providers you want to be allowed.

Sitecore comes with several mapEntry nodes that have predefined site lists. Every node has a name attribute with a meaningful value:

  • All sites

  • Sites with the web database

  • Sites with the core and unspecified database

  • Sites with extranet domain

  • Admin site

Note

These predefined mapEntry nodes were created to be dynamic and they demonstrate an ability to use special expressions in the mapEntry/sites section of your own mapEntry. Check the Config.Authentication.Owin.Authentication.config file to find out more.

By default, the SI server provider is placed in the sites with the core and unspecified database mapEntry node.

Access Sitecore with a new login page URL

Before SI, you used the /sitecore/login and /sitecore/admin/login.aspx URLs  to log in to the shell and admin sites, respectively. These URLs are not used with Sitecore Identity.

We recommend that you use the  /sitecore or /sitecore/admin URLs to access Sitecore, and that you use the Logout button to sign out or change to another user.

Sitecore Federated Authentication provides a new login page endpoint that allows Sitecore to redirect users directly to an external identity provider login page (without showing the login page in Sitecore) and then wait until the user clicks on the corresponding button.

The URL for this new login endpoint has this format: $(loginPath)/{site_name}/{identity_provider}[/{inner_identity_provider}], where:

  • $(loginPath) is a configuration variable ($(identityProcessingPathPrefix)login = /identity/login).

  • {site_name} is the name attribute value of the site node where the loginPage attribute value is set.

  • {identity_provider} is the name of the identity provider to whose login page you want the user to be redirected to.

  • {inner_identity_provider} is optional.  It is the name of the inner provider in the identity_provider. If you set  this value, then users are redirected directly to the inner_identity_provider login page immediately.

    Note

    The inner_identity_provider identity provider is sent to the identity_provider  identity provider as an acr_value = idp:inner_identity_provider. Therefore,  the identity_provider identity provider has to support acr_value.

The SI server provider is configured with the SitecoreIdentityServer name in Sitecore, and the  Sitecore.Owin.Authentication.IdentityServer.config file includes the following:

RequestResponse
<sites>
  <site name="shell" set:loginPage="$(loginPath)shell/SitecoreIdentityServer"/>
  <site name="admin" set:loginPage="$(loginPath)admin/SitecoreIdentityServer"/>
</sites>
Note

You must make sure that the site loginPage attribute value contains a relative URL to prevent cross-origin issues.

The /identity/login/… endpoint uses the GetSignInUrlInfoPipeline  pipeline internally to generate a proper sign-in link to the chosen external provider and to pass all necessary data to it. Use this login page format only for the loginPage attribute of site nodes and the GetSignInUrlInfoPipeline pipeline to get external sign-in URLs for particular sites for your presentation layer.

Get the /sitecore/login page back

You can bring back login buttons for previously configured external identity providers in Sitecore 9.0.

The Sitecore.Owin.Authentication.IdentityServer.config configuration file patches the loginPage attributes of the shell and admin sites to new special endpoints handled by Sitecore.

If you try to access the /sitecore/login page when SI is enabled, you are redirected to the login page specified for the shell site, unless they are the same.

Note

The InterceptLegacyShellLoginPage processor is responsible for this behavior.

Users will end up on the /sitecore/login?fbc=1 page if the SI server is unreachable and Sitecore is unable to obtain its initial metadata.

Note

Check the IdentityProviderIsInaccessible processor and its configuration.

If you have already configured an external identity provider(s) to sign in users in  shell using federated authentication, then you still have to use the /sitecore/login page because the SI server login page does not show those extra login buttons.

Note

If you want to add external identity providers to the SI server, see Federation Gateway.

To prevent Sitecore from redirecting users away from the sitecore/login page:

  1. Patch the shell login page back to /sitecore/login, or request /sitecore/login with extra an URL parameter (?fbc=1).

  2. Alternatively, patch the legacyShellLoginPage property of the InterceptLegacyShellLoginPage processor to some random value. 

Either of these actions prevents Sitecore from redirecting users away from the /sitecore/login page. The SI server is configured as a regular external identity provider in Sitecore and it means you see its sign-in button on the /sitecore/login page. The caption is Go to login.

Disable Sitecore Identity

The Sitecore instance is an SI client, but you can disable SI so Sitecore works without the SI server, as it did in versions before  9.1.

By default, if the Sitecore instance cannot reach the SI server during the first sign-in after Sitecore has started up, it uses the /sitecore/login page as a login page fallback.

Note

If authentication fallback happens, OWIN authentication middleware is still used, because it is enabled by the Owin.Authentication.Enabled setting.

To not use the SI server at all:

  • Activate this config file: \App_Config\Include\Examples\Sitecore.Owin.Authentication.IdentityServer.Disabler.config.example. This file does the following:

    • Sets the Enabled property of the SitecoreIdentityServer provider to false.

      Note

      All external identity providers configured in sitecore/federatedAuthentication/identityProviders have an Enabled property you use to disable individual identity providers from being registered in Sitecore.

    • Patches the loginPage attributes of the shell and admin sites to their initial values (/sitecore/login and /sitecore/admin/login.aspx).

To disable OWIN and federated authentication:

  • Activate this config file: \App_Config\Include\Examples\Sitecore.Owin.Authentication.Disabler.config.example. The file does the following:

    • Sets Owin.Authentication.Enabled and FederatedAuthentication.Enabled to false.

    • Patches the loginPage attributes of the shell and admin sites to their initial values (/sitecore/login and /sitecore/admin/login.aspx).

  • Add this setting to the web.config file:

    RequestResponse
    <add key="owin:AutomaticAppStartup" value="false" />
  • Restore the original authentication node in the web.config file:

    RequestResponse
    <authentication mode="Forms">
          <forms name=".ASPXAUTH" cookieless="UseCookies" />
    </authentication>

Implement user sign-out

Federated authentication has been extended in Sitecore 9.1. It is easier to implement sign out from external identity providers when a user signs out from Sitecore.

When a user signs out from an external identity provider, Sitecore Identity redirects the user to the logout page of this identity provider, and then back to Sitecore. A full sign out from both Sitecore and the underlying identity provider usually cannot happen with a single request. However, Sitecore Identity handles everything automatically when you use the AuthenticationManager.Logout() method.

This functionality is turned on by default only for the SI server provider (SitecoreIdentityServer in the configuration): sitecore/federatedAuthentication/identityProviders/identityProvider[id=SitecoreIdentityServer]/triggerExternalSignOut is true by default.

Important

This feature requires that you configure postLogoutRedirectUri correctly for the identity provider in the authentication middleware and allow postLogoutRedirectUri on the identity provider itself. Sitecore relies on this to ensure that external sign out has happened. If you do not configure postLogoutRedirectUri correctly, then the user is redirected to the external provider sign-out page each time they try to access Sitecore after sign-out. Users can wait 1 minute or clean up Sitecore cookies to avoid this.

Configure user lockout

User account lockout helps to avoid a password-guessing attack known as a brute force attack. A brute force attack is an attempt to discover a password by systematically trying every possible combination of letters, numbers, and symbols until you discover the one correct combination that works.

To configure user account lockout:

  1. Configure MaxInvalidPasswordAttempts and PasswordAttemptWindow with the  Sitecore:IdentityServer:SitecoreMembershipOptions:MaxInvalidPasswordAttempts and Sitecore:IdentityServer:SitecoreMembershipOptions:PasswordAttemptWindow settings.

  2. Alternatively, specify MaxInvalidPasswordAttempts and PasswordAttemptWindow in the Web.config file of the Sitecore instance. This only works is when the Sitecore Identity server is disabled or the password policy parameters in identityServer.xml are not specified.

Important

You must restrict access to the SI server root https://{si_server}/ and https://{si_server}/account/login URLs outside of your organization.

There are two types of cookie:

  • Session cookies (non-persistent)  -  these are temporary cookie files. They are erased when you close your browser.

  • Persistent cookies - the browser stores these cookie files until you delete them manually or the browser deletes them, based on the lifespan specified in the persistent cookie file itself.

Modern browsers tend to preserve session cookies between browser sessions when the appropriate browser option is turned on. It often makes session cookies behave like persistent ones. OWIN authentication allows you to store the cookie lifespan value in the cookie value itself. It means that the cookie is treated as expired by the web application if the cookie is expired, but the browser still sends it to the server.

To specify the authentication cookie lifetime:

  • Use the following patch snippet to specify the default cookie lifespan, and to enable or disable sliding expiration:

    RequestResponse
    <?xml version="1.0" encoding="utf-8"?>
    <configuration>
      <sitecore>
        <pipelines>
          <owin.initialize>
            <processor name="CookieAuthentication">
              <!-- Controls how much time the cookie will remain valid from the point it is created.
                 Format: d:hh:mm:ss
    
                 No matter the cookie is persistent or not, OWIN authentication will not pass the expired cookie.
                 ExpireTimeSpan could be overwritten by the http://www.sitecore.net/identity/claims/cookieExp claim where
                 the claim value is Unix time expressed as the number of seconds that have elapsed since 1970-01-01T00:00:00Z. -->
              <ExpireTimeSpan>00:30:00</ExpireTimeSpan>
              <SlidingExpiration>true</SlidingExpiration>
            </processor>
            ...
    

Web applications create persistent authentication cookies when a user selects a Remember me option. Authentication through Federated Authentication produces only non-persistent cookies.

For example, if you sign in through an external identity provider without selecting the Remember me option on that provider, then you have to sign in again after the browser session expires.

If you sign in through an external identity provider and you select the Remember me option on that provider, then you will lose your Sitecore authentication cookie when the browser session expires.  However, after a quick auto-redirect to the identity provider and back, you are automatically signed in to Sitecore again.

To override the cookie ExpireTimeSpan  setting for specific identity providers:

  • Specify a claims transformation for the identity provider that adds a http://www.sitecore.net/identity/claims/cookieExp claim with a value that specifies the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

This value indicates the time on or after which the authentication cookie must not be accepted for processing by the browser.

Sitecore uses the exp claim value for the Sitecore Identity server provider for this purpose - see the Config.Authentication.IdentityServer.Owin.Authentication.IdentityServer.config file:

RequestResponse
<sitecore>
  <federatedAuthentication>
    <identityProviders>
      <identityProvider id="SitecoreIdentityServer"  ...>
        <transformations ...>
            <!-- owin.cookieAuthentication.signIn pipeline uses http://www.sitecore.net/identity/claims/cookieExp claim to override authentication cookie expiration.
                 'exp' claim value can be configured on Sitecore Identity server on the client configuration by IdentityTokenLifetimeInSeconds setting.
                 Note: Claim value is Unix time expressed as the number of seconds that have elapsed since 1970-01-01T00:00:00Z -->
            <transformation name="use exp claim for authentication cookie expiration" type="Sitecore.Owin.Authentication.Services.DefaultTransformation, Sitecore.Owin.Authentication">
              <sources hint="raw:AddSource">
                <claim name="exp"/>
              </sources>
              <targets hint="raw:AddTarget">
                <claim name="http://www.sitecore.net/identity/claims/cookieExp"/>
              </targets>
              <keepSource>true</keepSource>
            </transformation>

Do you have some feedback for us?

If you have suggestions for improving this article,