Share via

3.1.5.2.1.3 Processing Details

  • Article

The processing details are the same as those specified in [MS-OAPX] section 3.1.5.1.1.3, with the following addition.

If a primary refresh token is available to the client in the Primary Refresh Token ADM element (section 3.1.1), the client can choose to include the token in the optional x-ms-RefreshTokenCredential HTTP header. The format of the x-ms-RefreshTokenCredential HTTP header is a signed JWT as defined in section 2.2.1.1, with the fields described in section 3.2.5.2.1.1.1. The client populates the header as follows:

  • The client uses the Primary Refresh Token ADM element to populate the required refresh_token field of the x-ms-RefreshTokenCredential HTTP header.

  • The client uses the Nonce ADM element value (section 3.1.1) that it received from the server in a previous nonce request (section 3.1.5.1.1) to populate the required request_nonce field of the x-ms-RefreshTokenCredential HTTP header.

The client derives a signing key from the Session Key ADM element (section 3.1.1), the constant label "AzureAD-SecureConversation", and the ctx value provided in the JWT header of the request by using the process described in [SP800-108]. The client uses this signing key to sign the JWT. If the capabilities field of the OpenID Provider Metadata ([MS-OIDCE] section 2.2.3.2) from the server includes the value "kdf_ver2", the client can use KDFv2 version for deriving the Session Key. If the client chooses to use KDFv2, the client MUST use SHA256(ctx || assertion payload) instead of ctx as the context for deriving the signing key. The client MUST also add the JWT header field "kdf_ver" with value set to 2 to communicate that KDFv2 was used for creating the derived signing key.

If a certificate is available to the client in the Device Certificate ADM element (section 3.1.1), the client can include the optional x-ms-DeviceCredential HTTP header. The format of the x-ms-DeviceCredential HTTP header is a signed JWT as defined in section 2.2.1.2, with the fields described in section 3.2.5.2.1.1.2. The client populates the header as follows:

  • The client uses the Nonce ADM element value (section 3.1.1) that it received from the server in a previous nonce request (section 3.1.5.1.1) to populate the request_nonce field of the request.

The client signs the request JWT described in section 3.1.5.1.2.1 using the private key of the Device Certificate ADM element.

Note The client can include both the x-ms-RefreshTokenCredential HTTP header and the x-ms-DeviceCredential HTTP header in a request, but the server ignores the x-ms-DeviceCredential HTTP header if the x-ms-RefreshTokenCredential HTTP header that is provided is valid.