Share via

Authentication Handler Overview

  • Article

 

When Active Directory® Federation Services (AD FS) 2.0 receives an authentication request, it does the following:

  1. Validates the request.

  2. If the single sign-on (SSO) cookie is present, authenticates the request with that. Otherwise, continue to step 3.

    1. If the SSO authentication succeeds, redirects the request back to the requestor with a security token.

    2. Otherwise, continue to step 3.

  3. Based on the AD FS 2.0 configuration and the request parameters, AD FS 2.0 invokes authentication handlers in the order in which they are specified in the web.config file in the Sign-In Pages.

The following table shows what each authentication handler does and when it is invoked.

Authentication handler type When it is invoked Function Notes
Integrated If authentication request allows for Windows authentication. Allows for Windows Integrated Authentication. Included as the default local authentication handler when AD FS 2.0 is installed in the non-proxy role. If invoked, it does not pass the request on to the next handler.
Forms If authentication request allows for password authentication. Renders the FormsSignIn.aspx page to collect user name and password credentials. Included as the default local authentication handler when AD FS 2.0 is installed in the proxy role. If invoked, it does not pass the request on to the next handler.
TlsClient If authentication request allows for TlsClient authentication. Allows for transport-level authentication with an X.509 client certificate. Included to allow for TlsClient authentication, but is not the default authentication handler when AD FS 2.0 is installed. If invoked, it does not pass the request on to the next handler.
Basic If authentication request allows for password authentication. Allows for transport-level basic authentication with a user name and password. If invoked, it does not pass the request on to the next handler.

The presence of each handler and the order in which they are invoked can be specified in the web.config file in the Sign-In Pages, under the <microsoft.identityServer.web>/<localAuthenticationTypes> element.

<localAuthenticationTypes>  
<!-- The first authentication type that matches the requirements of the request  
will be used to handle the request.  
The order of the authentication types is important and affects the user experience.  
In general, the first authentication type is the default authentication type.  
-->  
</localAuthenticationTypes>

By default, all handlers are enabled, except when AD FS 2.0 is installed as a proxy, in which case the Integrated handler is not enabled. The default handler order is Integrated, Forms, TlsClient, and Basic.

If a handler is present in the web.config file, then the Sign-In Pages will accept an authentication request with the corresponding token type. If the handler is absent, requests with that token type will fail.

A handler that does not satisfy the requirements in the request is not invoked. For example, if a request specifies that TlsClient authentication is required, then the Forms handler is not invoked, even if it is included in the web.config file.

The order of the handlers in the web.config file specifies the order in which the handlers are invoked. Note that some handlers, if they are invoked, do not pass an incoming request on to the next handler. For example, if the Forms handler appears before the TlsClient handler in the web.config file, and the Forms handler is invoked, then the TlsClient handler is not invoked.

Example Handler Configurations

The following examples show different handler configurations in the web.config file.

  • The following configuration is one you might use on an Internet-facing page:

    <localAuthenticationTypes>  
  <add name="Forms" page="FormsSignIn.aspx" />  
  <add name="TlsClient" page="auth/sslclient/" />  
</localAuthenticationTypes>

    The default authentication method is Forms-based user name and password. The TlsClient handler is invoked only if AD FS determines that it should be invoked based on the requested authentication context supplied with the request. Authentication requests that evaluate to authentication methods other than Forms-based authentication or TLS Client will fail. For more information about how AD FS evaluates the requested authentication context, see Specifying an Authentication Method in SAML Web Browser SSO Passive Authentication.

  • To configure AD FS 2.0 to accept only client SSL certificates and to reject requests that use all other authentication methods, use the following configuration:

    <localAuthenticationTypes>  
  <add name="TlsClient" page="auth/sslclient/" />  
</localAuthenticationTypes>

  • To configure AD FS 2.0 to act as a pure RP-STS, remove all local authentication handlers:

    <localAuthenticationTypes>  
</localAuthenticationTypes>

Specifying an Authentication Method in WS-Federation Passive Authentication

An RP can include the wauth parameter in a WS-Federation sign-in request to specify the type of authentication required to satisfy the request. Specifying this parameter can override the priority established by the order in which the handlers are configured. The behavior of AD FS 2.0 when the wauth parameter is specified is as follows:

  1. If a session already exists, and the method of authentication specified in the wauth parameter matches that of the SSO token stored in the session cookie, AD FS 2.0 will leverage the existing SSO token to respond to the requestor with a new token for the requested RP.

  2. If no session exists, or if a session exists, but the method specified in the wauth parameter does not match that stored in the session cookie, AD FS 2.0 examines the configured handlers to find one that can satisfy the method specified in the wauth parameter. Handlers that are configured first in web.config have higher priority. The first handler in the list that can authenticate the user with the specified method is invoked.

  3. If none of the configured handlers can be used to satisfy the authentication request, authentication fails.

The following WS-Federation passive request specifies user name and password authentication (urn:oasis:names:tc:SAML:1.0:am:password) in the wauth parameter.

https://AdfsServer.contoso.com/adfs/ls/?wa=wsignin1.0&wtrealm=https%3a%2f%2fAdfsServer.contoso.com%2fClaimsAwareWebAppWithManagedSTS%2f&wctx=rm%3d0%26id%3dpassive%26ru%3d%252fClaimsAwareWebAppWithManagedSTS%252fdefault.aspx&wct=2011-05-05T00%3a22%3a00Z&wauth=urn:oasis:names:tc:SAML:1.0:am:password

For example, assume the following:

  • The user and the AD FS 2.0 server are members of the same Active Directory domain and that the user is signed on to the domain.

  • No prior session exists between the user and the AD FS 2.0 server.

  • The AD FS 2.0 server is not a proxy server and that it has the default handler configuration (Integrated, Forms, TlsClient, and Basic).

For this scenario, without the wauth parameter in the request, AD FS 2.0 would try to authenticate the user with her Windows token because the Integrated handler is configured first in web.config. However, because the wauth parameter specifies user name and password authentication (urn:oasis:names:tc:SAML:1.0:am:password), AD FS 2.0 will present the FormsSignIn.aspx page to collect username and password credentials and use these credentials to authenticate her.

The following table shows the authentication type URIs that are recognized by AD FS for WS-Federation passive authentication.

Method of authentication wanted wauth URI
User name and password authentication urn:oasis:names:tc:SAML:1.0:am:password
SSL client authentication urn:ietf:rfc:2246
Windows integrated authentication urn:federation:authentication:windows

Specifying an Authentication Method in SAML Web Browser SSO Passive Authentication

In SAML Web SSO, the SAMLRequest carries an authentication request in the form of a SAML <AuthnRequest> element. An RP can set several attributes of the <AuthnReqeust> element and include a <RequestedAuthnContext> element to specify how the user should be authenticated by AD FS 2.0.

Note

IdP-Initiated SSO is a special case of the SAML Web Browser Passive Profile. In AD FS 2.0, IdP-initiated sign-on is handled by the IdPSignOnPage.aspx page. For more information about how to specify an authentication method using request parameters when performing IdP-intiated sign-on, see IdpInitiatedSignOnPage Class Overview.

The following attributes and elements can be specified to modify the sign-on request. This is not a complete list of elements or attributes that can be specified in the <AuthnRequest> element; it is only a list of the elements and attributes that influence the method of authentication used by AD FS 2.0.

<AuthnRequest Consent = URI  
              IsPassive = “true” | “false”  
              ForceAuthn = “true” | “false”  
              ... >  
    ...  
  
    <RequestedAuthnContext Comparison = “better” | “exact” | “maximum” | “minimum” >  
        <AuthnContextClassRef>  
            URI  
        </AuthnContextClassRef>  
        <AuthnContextClassRef>  
            URI  
        </AuthnContextClassRef>  
  
        ...  
    </ReqeustedAuthnContext>  
    ...  
  
</AuthnRequest>

Warning

AD FS 2.0 does not support the <AuthnContextDeclRef> element in the <RequestedAuthnContext> element. It does not process this element.

AD FS 2.0 treats these elements in the following manner.

  • AuthnRequest@IsPassive attribute: If this attribute is set to “true”, AD FS 2.0 tries to authenticate the user by using the SSO token saved in the session cookie. If an authentication context is specified, AD FS 2.0 evaluates the method of authentication stored in the cookie against the authentication context classes and comparison rule specified in the requested authentication context to determine whether the user can be authenticated. The IsPassive attribute specifies that logon must be completed without user interaction. The attribute may be used by applications to silently renew an existing token when it is close to expiration. It should not be used to do first-time authentication of a user with AD FS because none of the authentication methods that AD FS supports can be guaranteed not to require user interaction.

  • AuthnRequest@ForceAuthn attribute: If this attribute is set “true”, AD FS 2.0 ignores any existing session with the user and tries to authenticate the user by using the configured handlers. If an authentication context is specified, the handler invoked to authenticate the user is determined by the authentication context classes and comparison rule specified in the requested authentication context.

  • AuthnRequest@Consent attribute: A consent identifier URI that specifies the conditions under which the user authenticated. The consent identifiers are defined in section 8.4 of the SAML V2.0 Core specification on the SAML Specifications website.

  • RequestedAuthnContext element: Specifies desired authentication methods through one or more AuthnContextClassRef elements and a comparison rule through the Comparison attribute that specifies how the methods should be evaluated.

  • RequestedAuthnContext@Comparison attribute: Specifies the comparison rule that should be used to evaluate the specified authentication methods. For example, if “exact” is specified, the authentication method used must match one of the authentication methods specified by the AuthnContextClassRef elements.

  • AuthnContextClassRef element: Contains an authentication context class URI that specifies an authentication method. SAML authentication classes are defined in section 3.4 of the Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0 Specification (https://go.microsoft.com/fwlink/?LinkId=217497). AD FS 2.0 supports only a subset of the authentication context classes defined in this specification. For more information about the authentication context classes that AD FS 2.0 supports, see Supported SAML Authentication Context Classes and Strengths.

AD FS 2.0 evaluates the authentication request in the following manner.

Value of the IsPassive attribute Value of the ForceAuthn attribute How the request is processed.
true false AD FS 2.0 authenticates the user using the session cookie. If a requested authentication context is specified, AD FS 2.0 evaluates it against the last method used to authenticate the user stored in the session cookie. If this method meets the requirements imposed by the requested authentication context, authentication succeeds and AD FS 2.0 redirects the request back to the requestor with a security token; otherwise, authentication fails. If a requested authentication context is not specified, AD FS 2.0 redirects the request back to the requestor with a security token. If there is no session already established with the user authentication fails.
false true AD FS 2.0 ignores the session cookie and authenticates the user with one of the configured handlers. If no requested authentication context is specified, the first handler configured in web.config is invoked. If a requested authentication context is specified, it is evaluated against the configured handlers. Handlers are evaluated in the order in which they are configured in web.config. The first handler that can authenticate the user with a method that meets the requirements imposed by the requested authentication context is invoked. If none of the handlers can use a method that meets the requirements of the requested authentication context, authentication fails.
false false AD FS 2.0 first tries to authenticate the user with the session cookie. If the user cannot be authenticated with the session cookie, either because there is no current session with the user or because the last method of authentication used in the session does not meet the requirements of the requested authentication context, AD FS 2.0 tries to authenticate the user with the configured handlers.
true true Authentication fails, or, if the server is deployed in a server farm, the user is redirected to the parent STS if possible (for example, if home realm discovery was done earlier by the user and no further interaction is required now).

AD FS 2.0 evaluates the requested authentication context in the following manner:

  • Authentication context classes are evaluated in the order in which they are specified under the <RequestedAuthnContext> element.

  • If the Comparison attribute is set to “exact”, the method of authentication used must match one of the specified authentication context classes. The default is “exact” if the Comparison attribute is omitted.

  • If the Comparison attribute is set to “better”, “minimum”, or “maximum”, the method of authentication must be stronger than, at least as strong as, or no stronger than one of the specified authentication classes. The relative strength of different methods is determined by the order in which they are configured in the Authentication Context Order policy. This policy can be viewed and modified by using AD FS 2.0Windows PowerShell cmdlets. For more information about the Authentication Context Order policy, see Supported SAML Authentication Context Classes and Strengths.

The following is an example authentication request for TLS client or Windows authentication.

<samlp:AuthnRequest ID="_6b2e0c13-fea0-467c-9add-733a9a66f5c8"   
                    Version="2.0"   
                    IssueInstant="2011-05-03T20:49:33.151Z"   
                    Destination="https://AdfsServer.contoso.com/adfs/ls/"   
                    Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified"   
                    ForceAuthn="true"   
                    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">  
    <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">  
        http://AdfsServer.contoso.com/adfs/services/trust  
    </Issuer>  
  
    <Conditions xmlns="urn:oasis:names:tc:SAML:2.0:assertion">  
        <AudienceRestriction>  
            <Audience>  
                https://SamlApp.sales.contoso.com/adfs/ls/  
            </Audience>  
        </AudienceRestriction>  
    </Conditions>  
  
    <samlp:RequestedAuthnContext Comparison=”exact”  
         <samlp:AuthnContextClassRef xmlns:samlp="urn:oasis:names:tc:SAML:2.0:assertion">  
              urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient  
         </samlp:AuthnContextClassRef>  
         <samlp:AuthnContextClassRef xmlns:samlp="urn:oasis:names:tc:SAML:2.0:assertion">  
              urn:federation:authentication:windows  
         </samlp:AuthnContextClassRef>  
     </samlp:RequestedAuthnContext>  
</samlp:AuthnRequest>

Assume the following scenario:

  • The user and the AD FS 2.0 server are members of the same Active Directory domain and that the user is signed on to the domain.

  • A prior session exists between the user and the AD FS 2.0 server. The user authenticated with user name and password.

  • The AD FS 2.0 server is not a proxy server and that it has the default handler configuration (Integrated, Forms, TlsClient, and Basic).

For this scenario, AD FS 2.0 will authenticate the user with her Windows token. This is because:

  • The AuthnContext@ForceAuthn attribute is “true”, so AD FS 2.0 ignores the session cookie and authenticates the user from the configured handlers.

  • The RequestedAuthnContext@Comparison attribute is set to “exact”, so AD FS 2.0 will choose a method of authentication that exactly matches one of the specified authentication context classes.

  • Even though TLS Client authentication is specified first in the requested authentication context, the Integrated handler is specified before the TlsClient handler in web.config, so it is evaluated first by AD FS 2.0. Because the Windows authentication context class URI is specified in the requested authentication context, AD FS 2.0 invokes the Integrated handler to authenticate the user.

The following are some ways in which the requested authentication context could be modified to select a different method of authenticating the user.

  • If only the TLS client class URI is specified in the requested authentication context and the Comparison attribute is set to “exact”, AD FS 2.0 will use the TlsClient handler to authenticate the user. This is because this is the only handler that provides TLS Client authentication.

  • If only the TLS client class URI is specified in the requested authentication context and the Comparison attribute is set to “maximum”, AD FS 2.0 authenticates the user with user name and password authentication. This is because when the Comparison attribute is set to “maximum”, the method of authentication used can be no stronger than at least one of the specified authentication context classes. AD FS 2.0 evaluates the Integrated handler first; however, because Windows authentication is stronger than TLS Client authentication (as specified in the Authentication Context Order policy), AD FS 2.0 does not invoke the Integrated handler. AD FS 2.0 then evaluates the Forms handler since it is configured next in web.config. Because Password authentication is weaker than TLS client authentication in the Authentication Context Order policy, AD FS 2.0 will invoke the Forms handler to authenticate the user.