3.2.5.2.1.3 Processing Details

  • Article

The steps performed by the AD FS server to process an OAuth 2.0 client's access token request are defined in [RFC6749] sections 4.1.3 (Access Token Response), 5 (Issuing an Access Token), and 6 (Refreshing an Access Token), and in [RFC8628] section 3.5 (Device Access Token Response).

The following additional processing steps are expected as a result of the extensions included in this document:

  • If the OAuth 2.0 client specified either the client-request-id query parameter or the client-request-id HTTP header in the access token request, the AD FS server MUST use the request identifier specified in the request when logging errors or failures that occur while processing that access token request.

  • If the OAuth 2.0 client specifies both the client-request-id query parameter as well as the client-request-id HTTP header, the AD FS server MUST use the value specified in the query parameter when logging errors or failures that occur while processing that authorization request and ignore the value specified in the HTTP header.

  • If the AD FS server encountered an internal error when processing the OAuth 2.0 client's access token request, it MUST respond to the OAuth 2.0 client according to the requirements of [RFC6749] section 5.2 (Error Response). The REQUIRED error parameter of the response MUST be set to server_error (section 2.2.4.2).

  • If the AD FS server's ad_fs_behavior_level is AD_FS_BEHAVIOR_LEVEL_2 or higher and the client is refreshing an access token ([RFC6749] section 6):

    • If the client provides a resource parameter in the request and the provided refresh token is a multi-resource refresh token, the AD FS server issues the access token for the resource given in this request.

    • If the client provides a resource parameter in the request and the provided refresh token is not a multi-resource refresh token, the AD FS server SHOULD either issue an access token for the resource given in this request, or send an error response to the OAuth 2.0 client according to the requirements of [RFC6749] section 5.2 (Error Response).<12> If sending an error, the value for the REQUIRED error parameter of the response SHOULD be invalid_grant.

    • If the client does not provide a resource parameter in the request, the AD FS server returns an access token for the same resource as was specified when the refresh token was initially granted to the client.

  • If the AD FS server's ad_fs_behavior_level is AD_FS_BEHAVIOR_LEVEL_2 or higher and the server is returning a multi-resource refresh token, it includes a resource parameter in the response set to the identifier of the resource for which the current access token is being issued.

  • If the AD FS server's ad_fs_behavior_level is AD_FS_BEHAVIOR_LEVEL_2 or higher and the use_windows_client_authentication parameter has a value of "true", the AD FS server authenticates the client via the HTTP Negotiate Authentication Scheme described in [RFC4559].

    • Upon successful authentication using the HTTP Negotiate Authentication Scheme, the AD FS server verifies that the account used to authenticate is one that was previously associated with the client during client registration: if there is a client registration record with client_id matching the client_id parameter in the request and the account used is included in the Windows_client_authentication_accounts field of the client registration record, then the client authentication is successful and processing continues. Otherwise, the AD FS server sends an error response to the OAuth 2.0 client according to the requirements of [RFC6749] section 5.2 (Error Response). The REQUIRED error parameter of the response MUST be set to invalid_client.

  • If the AD FS server's ad_fs_behavior_level is AD_FS_BEHAVIOR_LEVEL_2 or higher and the client is authenticating using private key jwt, as described in [OIDCCore] section 9:

    • If the client is not configured with the AD FS server to use either the jwks_uri or sign_certificates ADM element, as described in section 3.2.1.2, the AD FS server MUST send an error response to the OAuth 2.0 client according to the requirements of [RFC6749] section 5.2 (Error Response). The REQUIRED error parameter of the response MUST be set to invalid_client.

    • If the client is configured with the AD FS server to use either the jwks_uri or sign_certificates ADM element, as described in section 3.2.1.2, the AD FS server MUST validate the JSON Web Token signature [RFC7519] using the certificate or public key identified by the x5t or kid field [RFC7517] according to the requirements in [RFC7519]. If the signature cannot be verified, the AD FS server MUST send an error response to the OAuth 2.0 client according to the requirements of [RFC6749] section 5.2 (Error Response). The REQUIRED error parameter of the response MUST be set to invalid_client.

  • If the AD FS server's ad_fs_behavior_level is AD_FS_BEHAVIOR_LEVEL_2 or higher and the grant_type parameter has a value of "urn:ietf:params:oauth:grant-type:jwt-bearer":

    • If the requested_token_use parameter is not present or has any value other than "on_behalf_of" or "logon_cert", the AD FS server MUST send an error response to the OAuth 2.0 client according to the requirements of [RFC6749] section 5.2 (Error Response). The REQUIRED error parameter of the response MUST be set to invalid_request.

    • If the assertion parameter is not present, the AD FS server MUST send an error response to the OAuth 2.0 client according to the requirements of [RFC6749] section 5.2 (Error Response). The REQUIRED error parameter of the response MUST be set to invalid_request.

    • If the resource parameter is not present, the AD FS server MUST send an error response to the OAuth 2.0 client according to the requirements of [RFC6749] section 5.2 (Error Response). The REQUIRED error parameter of the response MUST be set to invalid_request.

    • If the resource parameter is invalid or not found to be registered on the AD FS server, the AD FS server MUST send an error response to the OAuth 2.0 client according to the requirements of [RFC6749] section 5.2 (Error Response). The REQUIRED error parameter of the response MUST be set to invalid_grant.

    • If the client specified by the client_id parameter (or otherwise identified by a client authentication method) is not a confidential client or did not provide valid client credentials according to [RFC6749] section 2.3, the AD FS server MUST send an error response to the OAuth 2.0 client according to the requirements of [RFC6749] section 5.2 (Error Response). The REQUIRED error parameter of the response MUST be set to invalid_client.

    • If the requested_token_use parameter has a value of "on_behalf_of":

      • If the assertion parameter does not contain a valid, non-expired access token previously issued by the AD FS server for the scope "user_impersonation" to the resource whose identifier matches the current client identifier (provided either in the client_id parameter or via the client authentication), the AD FS server MUST send an error response to the OAuth 2.0 client according to the requirements of [RFC6749] section 5.2 (Error Response). The REQUIRED error parameter of the response MUST be set to invalid_grant.

      • The AD FS server issues a new access token to the resource given in the resource parameter.

    • If the requested_token_use parameter has a value of "logon_cert":

      • If the assertion parameter does not contain a valid, non-expired access token that was previously issued by the AD FS server for the scope "logon_cert" to the resource whose identifier matches the current client identifier (provided either in the client_id parameter or by using client authentication), the AD FS server MUST send an error response to the OAuth 2.0 client according to the requirements of [RFC6749] section 5.2 (Error Response). The REQUIRED error parameter of the response MUST be set to invalid_grant.

      • If the csr_type parameter is not present or is not set to a value of "http://schemas.microsoft.com/windows/pki/2009/01/enrollment#PKCS10", the AD FS server MUST send an error response to the OAuth 2.0 client according to the requirements of [RFC6749] section 5.2 (Error Response). The REQUIRED error parameter of the response MUST be set to invalid_request.

      • If the csr parameter is not present or is not a valid base64-encoded PKCS#10 request ([MS-WCCE] section 2.2.2.6.1), the AD FS server MUST send an error response to the OAuth 2.0 client according to the requirements of [RFC6749] section 5.2 (Error Response). The REQUIRED error parameter of the response MUST be set to invalid_request.

      • The AD FS server omits the access_token parameter from the response and instead provides a base64-encoded CMS certificate chain or a CMC full PKI response ([MS-WCCE] section 2.2.2.8) in the x5c response parameter. The response that is given in the x5c parameter is created based upon the request in the csr parameter, as described in [MS-WCCE] section 3.2.1.4.2.1.4.1, with the following exceptions:

        • All fields in the original request except for SubjectPublicKeyInfo ([MS-WCCE] section 2.2.2.6.1) are ignored.

        • The Subject field of the response MUST match the identity that is represented by the original access token provided in the assertion parameter.

    • The Extended Key Usage field ([RFC5280] section 4.2.1.12) contains the OIDs 1.3.6.1.5.5.7.3.2 (clientAuth) and 1.3.6.1.4.1.311.20.2.2 (smartcardLogin).

  • If the AD FS server's ad_fs_behavior_level is AD_FS_BEHAVIOR_LEVEL_2 or higher and it has not encountered any prior errors in processing, the AD FS server includes an ID token in the response as described in [OIDCCore] section 3.1.3.3.

  • If the AD FS server's ad_fs_behavior_level is AD_FS_BEHAVIOR_LEVEL_2 or higher and it has not encountered any prior errors in processing, and a referred token-binding ID was provided (see below), the AD FS server includes a token-binding claim in the Access Token in the response, as defined in [IETFDRAFT-OAUTH2TOKBIND-08]. The token-binding ID can be provided in one of the following ways:

    • If the response is for the OAuth device flow request [RFC8628] then use the tbidv2 POST parameter provided on the device authorization endpoint (/devicecode) request.

    • Otherwise use the tbidv2 POST parameter on the current request.