Export (0) Print
Expand All

3.1.5 Message Processing Events and Sequencing Rules

SharePoint

The following sequence of events occurs for the client application to authenticate with the application server.

Step 1: The client application makes an anonymous service call to the application server.

Step 2: The application server returns an HTTP 401 challenge with an empty Bearer authorization header. The Bearer authorization header is specified in [IETFDRAFT-JWTOAuth].

The response contains the following parameters:

  • client_id: An application identifier. The value MUST be 00000003-0000-0ff1-ce00-000000000000.

  • realm: The source realm (2) of the application. The format of realm is specified in [MS-OAUTH2EX].

  • trustedissuers: The list of the name identifiers of the issuers that the application server trusts.

Step 3: The client application creates a server-to-server token that contains the user identity information as an outer token. The following table describes claims that are used in the outer token, and are exchanged in server-to-server security tokens. The claim values are all string data types, as specified in [MS-DTYP]. All values in any server-to-server tokens MUST be lowercase strings.

Claim type

Claim description

Required value formats

aud

The audience that is the targeted service for which the token is issued. This claim type MUST be provided.

The value MUST be specified in the following format, where hostname is the application server’s host name, and realm is the realm (2) provided in the HTTP 401 response.

00000003-0000-0ff1-ce00-000000000000/hostname@realm

iss

The principal (1) of the issuer. This claim type MUST be provided.

Any string format is allowed. The following format is typical, where principalconfiguredguid is preferably a GUID, but it can also be a name.

principalid@principalconfiguredguid

nameid

The name identifier that is the value of the principal (1) that makes the request, such as the signed-in user’s UPN value.

Any string format is allowed. In general the following format is a typical format.

domain\user

nii

The name identifier issuer.

If the name identifier was issued with identityprovider equal to "windows", then the following string is used.

urn:office:idp:activedirectory

If the name identifier was issued by custom forms-based membership providers, then the following format is used, where membershipprovidername is the name of the membership provider.

urn:office:idp:forms:membershipprovidername

If the name identifier was issued by a SAML identity provider, then the following format is used, where samlprovidername is the name of the SAML provider.

urn:office:idp:trusted:samlprovidername

nbf

The not_before time at which the token was created. This claim type MUST be provided.

The format of this value is specified in [MS-OAUTH2EX] section 3.1.1.

exp

The expires_on time at which the token expires. This claim type MUST be provided.

The format of this value is specified in [MS-OAUTH2EX] section 3.1.1.

trustedfordelegation

A value indicating whether the caller is trusted to delegate a user identity.

The value MUST be one of the following values:

  • true

  • false

identityprovider

A value indicating the identity provider who authenticated the caller.

The value MUST be one of the following values:

  • windows

  • accesstoken

  • forms

  • trusted

actortoken

A value that points to the security token issued and signed by a trusted issuer.

The value is an application identity token described in the next claims table.

smtp

The logged-on user’s email address. This is an additional claim that trusted issuers send.

Any string format is allowed. For example, user@contoso.com.

sip

The logged on user’s SIP address.

This is an additional claim that trusted issuers send.

Any string format is allowed. The claim value depends on what is configured as the SIP address for the user. For example, sip:user@contoso.com.

Step 4: The client application constructs an application identity token which is inserted into the outer token as the value of the actortoken claim. The following table describes claims that are used in the application identity token. The claim values are all string data types, as specified in [MS-DTYP]. All values in any server-to-server tokens MUST be lowercase strings.

Claim type

Claim description

Required value formats

aud

The audience that is the targeted service for which the token is issued. This claim type MUST be provided.

The value MUST be specified in the following format, where hostname is the application server’s host name, and realm is the realm (2) provided in the HTTP 401 response.

00000003-0000-0ff1-ce00-000000000000/hostname@realm

iss

The principal (1) of the issuer. This claim type MUST be provided.

Any string format is allowed. The following format is typical, where principalconfiguredguid is preferably a GUID, but it can also be a name.

principalid@principalconfiguredguid

nameid

The name identifier that is the value of the principal (1) that makes the request, such as the signed-in user’s UPN value.

The value MUST use the following format where realm is the realm (2) provided in the HTTP 401 response.

00000003-0000-0ff1-ce00-000000000000@realm

nii

The name identifier issuer.

If the name identifier was issued with identityprovider equal to "windows", then the following string is used.

urn:office:idp:activedirectory

If the name identifier was issued by custom forms-based membership providers, then the following format is used, where membershipprovidername is the name of the membership provider.

urn:office:idp:forms:membershipprovidername.

If the name identifier was issued by a SAML identity provider, then the following format is used, where samlprovidername is the name of the SAML provider.

urn:office:idp:trusted:samlprovidername

nbf

The not_before time at which the token was created. This claim type MUST be provided.

The format of this value is specified in [MS-OAUTH2EX] section 3.1.1.

exp

The expires_on time at which the token expires. This claim type MUST be provided.

The format of this value is specified in [MS-OAUTH2EX] section 3.1.1.

trustedfordelegation

A value indicating whether the caller is trusted to delegate a user identity.

The value MUST be one of the following values:

  • true

  • false

identityprovider

A value indicating the identity provider who authenticated the caller.

The value MUST be one of the following values:

  • windows

  • forms

  • trusted

Step 5: The client application sends the server-to-server token, which includes the outer token with user identity information, to the application server. The server-to-server token MUST be compatible with the JSON web token format specified in [IETFDRAFT-JWT] and [MS-OAUTH2EX].

Step 6: The application server validates the server-to-server token and extracts the user identity information.

A relying party application accepts server-to-server tokens as long as the following criteria are met:

  • The token is signed with one of the application server’s trusted signing certificates.

  • The token contains at least one of the following claims:

    • nid claim with the UPN value

    • smtp claim

    • sip claim

  • The iss claim value in the outer token matches the nameid claim value in the inner token. The match is case sensitive.

  • The aud claim value passes the audience validation check, which includes the following:

    • The aud claim MUST contain these parameters: client_id, hostname, and realm. The match is case sensitive.

    • The client_id parameter MUST be 00000003-0000-0ff1-ce00-000000000000.

    • The hostname parameter is the host name of the application server’s endpoint (4).

    • The realm parameter matches the requested resource’s realm (2).

The application server uses the claims in the token to grant access to its resources based on the user profile.

This protocol is used for the following endpoints (4) on the application server:

  • Client.svc

  • Listdata.svc

  • Sites.asmx

  • _api

Show:
© 2014 Microsoft