identity 1.0 documentation

Assertion Framework for OAuth 2.0

«  SAML 2.0 Bearer Assertion Profiles for OAuth 2.0   ::   Contents   ::   OAuth 2.0 Multiple Response Type Encoding Practices  »

Assertion Framework for OAuth 2.0

http://tools.ietf.org/html/draft-ietf-oauth-assertions-09

Abstract

This specification provides a framework for the use of assertions with OAuth 2.0 in the form of a new client authentication mechanism and a new authorization grant type. Mechanisms are specified for transporting assertions during interactions with a token endpoint, as well as general processing rules.

The intent of this specification is to provide a common framework for OAuth 2.0 to interwork with other identity systems using assertions, and to provide alternative client authentication mechanisms.

Note that this specification only defines abstract message flows and processing rules. In order to be implementable, companion specifications are necessary to provide the corresponding concrete instantiations.

Note

Abstract message flow and assertion content for

  • client credeintial
  • authorization grant

Token in OAuth can be in two type of generic format (“3.1. Tokens ”):

  • Handle - “artifact”
  • Assertion - “self-contained token”

(draft 09)

1. Introduction

OAuth 2.0 [RFC6749] is an authorization framework that enables a third-party application to obtain limited access to a protected HTTP resource. In OAuth, those third-party applications are called clients; they access protected resources by presenting an access token to the HTTP resource. Access tokens are issued to clients by an authorization server with the (sometimes implicit) approval of the resource owner. These access tokens are typically obtained by exchanging an authorization grant, which represents the authorization granted by the resource owner (or by a privileged administrator). Several authorization grant types are defined to support a wide range of client types and user experiences. OAuth also provides an extensibility mechanism for defining additional grant types, which can serve as a bridge between OAuth and other protocol frameworks.

Note

  • Grant Typeを追加することで、他のプロトコルフレームワークにブリッジできる。

This specification provides a general framework for the use of assertions as authorization grants with OAuth 2.0. It also provides a framework for assertions to be used for client authentication. It provides generic mechanisms for transporting assertions during interactions with an authorization server’s token endpoint, as well as general rules for the content and processing of those assertions. The intent is to provide an alternative client authentication mechanism (one that doesn’t send client secrets), as well as to facilitate the use of OAuth 2.0 in client-server integration scenarios, where the end-user may not be present.

Note

  • OAuth 2.0 でアサーションを認可交付(認可証?)として使う為のフレームワーク
  • また、クライアント認証でアサーションを使う時のフレームワーク

This specification only defines abstract message flows and processing rules. In order to be implementable, companion specifications are necessary to provide the corresponding concrete instantiations. For instance, SAML 2.0 Bearer Assertion Profiles for OAuth 2.0 [I-D.ietf-oauth-saml2-bearer] defines a concrete instantiation for SAML 2.0 tokens and JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0 [I-D.ietf-oauth-jwt-bearer] defines a concrete instantiation for JWT tokens.

Note: The use of assertions for client authentication is orthogonal to and separable from using assertions as an authorization grant. They can be used either in combination or separately. Client assertion authentication is nothing more than an alternative way for a client to authenticate to the token endpoint and must be used in conjunction with some grant type to form a complete and meaningful protocol request. Assertion authorization grants may be used with or without client authentication or identification. Whether or not client authentication is needed in conjunction with an assertion authorization grant, as well as the supported types of client authentication, are policy decisions at the discretion of the authorization server.

( http://tools.ietf.org/html/draft-ietf-oauth-assertions-09#section-1 )

2. Overview

Note

Assertions in this spec are for:

  • clent credential ( for 3rd party authentication )
  • authorization grant

Definitions are for:

The OAuth 2.0 Authorization Protocol [I-D.ietf.oauth-v2] provides a method for making authenticated HTTP requests to a resource using an access token. Access tokens are issued to clients by an authorization server with the (sometimes implicit) approval of the resource owner. These access tokens are typically obtained by exchanging an authorization grant representing authorization by the resource owner or privileged administrator. Several authorization grant types are defined to support a wide range of client types and user experiences. OAuth also allows for the definition of new extension grant types to support additional clients or to provide a bridge between OAuth and other trust frameworks. Finally, OAuth allows the definition of additional authentication mechanisms to be used by clients when interacting with the authorization server.

In scenarios where security is at a premium one wants to avoid sending secrets across the Internet, even on encrypted connections. Instead one wants to send values derived from the secret that prove to the receiver that the sender is in possession of the secret without actually sending the secret. Typically the way derived values are created is by generating an assertion that is then either HMAC’ed or digitally signed using an agreed upon secret. By validating the HMAC or digital signature on the assertion, the receiver can prove to themselves that the entity that generated the assertion was in possession of the secret without actually communicating the secret directly.

This specification provides a general framework for the use of assertions as client credentials and/or authorization grants with OAuth 2.0. It includes a generic mechanism for transporting assertions during interactions with a token endpoint, as wells as rules for the content and processing of those assertions. The intent is to provide an enhanced security profile by using derived values such as signatures or HMACs, as well as facilitate the use of OAuth 2.0 in client-server integration scenarios where the end-user may not be present.

This specification only defines abstract message flow and assertion content. Actual use requires implementation of a companion protocol binding specification. Additional profile documents provide standard representations in formats such as SAML and JWT.

3. Framework

An assertion is a package of information that allows identity and security information to be shared across security domains. An assertion typically contains information about a subject or principal, information about the party that issued the assertion and when was it issued, as well as the conditions under which the assertion is to be considered valid, such as when and where it can be used.

The entity that creates and signs the assertion is typically known as the “Issuer” and the entity that consumes the assertion and relies on its information is typically known as the “Relying Party”. In the context of this document, the authorization server acts as a relying party.

Assertions used in the protocol exchanges defined by this specification MUST always be protected against tampering using a digital signature or a keyed message digest applied by the issuer. An assertion MAY additionally be encrypted, preventing unauthorized parties from inspecting the content.

Although this document does not define the processes by which the client obtains the assertion (prior to sending it to the authorization server), there are two common patterns described below.

Third Party Created Assertion

In the first pattern, depicted in Figure 1, the client obtains an assertion from a third party entity capable of issuing, renewing, transforming, and validating security tokens. Typically such an entity is known as a “Security Token Service” (STS) or just “Token Service” and a trust relationship (usually manifested in the exchange of some kind of key material) exists between the token service and the relying party. The token service is the assertion issuer; its role is to fulfill requests from clients, which present various credentials, and mint assertions as requested, fill them with appropriate information, and sign them.

WS-Trust [OASIS.WS-Trust] is one available standard for requesting security tokens (assertions).

Relying
Party                     Client                   Token Service
|                          |                         |
|                          |  1) Request Assertion   |
|                          |------------------------>|
|                          |                         |
|                          |  2) Assertion           |
|                          |<------------------------|
|    3) Assertion          |                         |
|<-------------------------|                         |
|                          |                         |
|    4) OK or Failure      |                         |
|------------------------->|                         |
|                          |                         |
|                          |                         |

Figure 1: Third Party Created Assertion

Self-Issued Assertion

In the second pattern, depicted in Figure 2, the client creates assertions locally. To sign the assertions, it has to obtain key material: either symmetric keys or asymmetric key pairs. The mechanisms for obtaining this key material are beyond the scope of this specification.

Although assertions are usually used to convey identity and security information, self-issued assertions can also serve a different purpose. They can be used to demonstrate knowledge of some secret, such as a client secret, without actually communicating the secret directly in the transaction. In that case, additional information included in the assertion by the client itself will be of limited value to the relying party and, for this reason, only a bare minimum of information is typically included in such an assertion, such as information about issuing and usage conditions.

Relying
Party                     Client
|                          |
|                          | 1) Create
|                          |    Assertion
|                          |--------------+
|                          |              |
|                          | 2) Assertion |
|                          |<-------------+
|    3) Assertion          |
|<-------------------------|
|                          |
|    4) OK or Failure      |
|------------------------->|
|                          |
|                          |

Figure 2: Self-Issued Assertion

Deployments need to determine the appropriate variant to use based on the required level of security, the trust relationship between the entities, and other factors.

Assertion Types(Bearer/HoK)

From the perspective of what must be done by the entity presenting the assertion, there are two general types of assertions:

1. Bearer Assertions: Any entity in possession of a bearer assertion (e.g. the bearer) can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer assertions need to be protected from disclosure in storage and in transport. A secure communication channel is required between all entities to avoid leaking the assertion to unauthorized parties.

2. Holder-of-Key Assertions: To access the associated resources, the entity presenting the assertion must demonstrate possession of additional cryptographic material. The token service thereby binds a key identifier to the assertion and the client has to demonstrate to the relying party that it knows the key corresponding to that identifier when presenting the assertion. This mechanism provides additional security properties.

The protocol parameters and processing rules defined in this document are intended to support a client presenting a bearer assertion to an authorization server. The use of holder-of-key assertions are not precluded by this document, but additional protocol details would need to be specified.

( http://tools.ietf.org/html/draft-ietf-oauth-assertions-09#section-3 )

4. Transporting Assertions

This section defines generic HTTP parameters for transporting assertions during interactions with a token endpoint.

Transportations:

4.1. Using Assertions for Client Authentication

In scenarios where one wants to avoid sending secrets, one wants to send values derived from the secret that prove to the receiver that the sender is in possession of the secret without actually sending the secret.

For example, a client can establish a secret using an out-of-band mechanism with a resource server. As part of this out-of-band communication the client and resource server agree that the client will authenticate itself using an assertion with agreed upon parameters that will be signed by the provisioned secret. Later on, the client might send an access token request to the token endpoint for the resource server that includes an authorization code, as well as a client_assertion that is signed with the previously agreed key and parameters. The client_assertion proves to the token endpoint the identity of the client and the authorization code provides the link to the end-user authorization.

The following section defines the use of assertions as client credentials as an extension of Section 3.2 of OAuth 2.0 [I-D.ietf.oauth-v2]. When using assertions as client credentials, the client MUST include the assertion using the following HTTP request parameters:

client_id
OPTIONAL. The client identifier as described in Section 3 of OAuth 2.0 [I-D.ietf.oauth-v2].
client_assertion_type
REQUIRED. The format of the assertion as defined by the authorization server. The value MUST be an absolute URI.
client_assertion
REQUIRED. The assertion being used to authenticate the client. Specific serialization of the assertion is defined by profile documents. The serialization MUST be encoded for transport within HTTP forms. It is RECOMMENDED that base64url be used.

The following non-normative example demonstrates a client authenticating using an assertion during an Authorization Code Access Token Request as defined in Section 4.1.3 of OAuth 2.0 [I-D.ietf.oauth-v2]. (line breaks are for display purposes only):

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=i1WsRn1uB1&
client_id=s6BhdRkqt3&
client_assertion_type=urn%3Aoasis%3Anames%sAtc%3ASAML%3A2.0%3Aassertion&
client_assertion=PHNhbWxwOl...[omitted for brevity]...ZT

The client MUST NOT include the client_credential using more than one mechanism. Token endpoints can differentiate between client assertion credentials and other client credential types by looking for the presence of the client_assertion and client_assertion_type attributes which will only be present with client assertion credentials. See section 7 for more details

4.2. Using Assertions as Authorization Grants

An assertion can be used to request an access token when a client wishes to utilize an existing trust relationship. This may be done through the semantics of (and a digital signature/HMAC calculated over) the assertion, and expressed to the authorization server through an extension authorization grant type. The processes by which authorization is previously granted, and by which the client obtains the assertion prior to exchanging it with the authorization server, are out of scope.

The following defines the use of assertions as authorization grants as an extension of OAuth 2.0 [I-D.ietf.oauth-v2], section 4.5. When using assertions as authorization grants, the client MUST include the assertion using the following HTTP request parameters:

client_id
OPTIONAL. The client identifier as described in Section 3 of OAuth 2.0 [I-D.ietf.oauth-v2].
grant_type
REQUIRED. The format of the assertion as defined by the authorization server. The value MUST be an absolute URI.
assertion
REQUIRED. The assertion being used as an authorization grant. Specific serialization of the assertion is defined by profile documents. The serialization MUST be encoded for transport within HTTP forms. It is RECOMMENDED that base64url be used.
scope
OPTIONAL. The request MAY contain a “scope” parameter. The scope of the access request is expressed as a list of space-delimited strings. The value is defined by the authorization server. If the value contains multiple space-delimited strings, their order does not matter, and each string adds an additional access range to the requested scope. When exchanging assertions for access_tokens, the authorization for the token has been previously granted through some other mechanism. As such, the requested scope SHOULD be equal or lesser than the scope originally granted to the authorized accessor. If the scope parameter and/or value is omitted, the scope SHOULD be treated as equal to the scope originally granted to the authorized accessor. The Authorization Server SHOULD limit the scope of the issued access token to be equal or lesser than the scope originally granted to the authorized accessor.

The following non-normative example demonstrates an assertion being used as an authorization grant. (line breaks are for display purposes only):

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

client_id=s6BhdRkqt3&
grant_type=urn%3Aoasis%3Anames%sAtc%3ASAML%3A2.0%3Aassertion&
assertion=PHNhbWxwOl...[omitted for brevity]...ZT4

5. Assertion Content and Processing

This section provides a general content and processing model for the use of assertions in OAuth 2.0 [I-D.ietf.oauth-v2].

Formats:

5.1. Assertion Metamodel

The following are entities and metadata involved in the issuance, exchange and processing of assertions in OAuth 2.0. These are general terms, abstract from any particular assertion format. Mappings of these terms into specific representations are provided by profiles of this specification.

Issuer
The unique identifier for the entity that issued the assertion. Generally this is the entity that holds the keying material used to generate the assertion. In some use-cases Issuers may be either OAuth Clients (when assertions are self- asserted ) or a Security Token Service (an entity capable of issuing, renewing, transforming and validating of security tokens).
Principal
A unique identifier for the subject of the assertion. When using assertions for client authentication, the Principal SHOULD be the client_id of the OAuth client. When using assertions as an authorization grant, the Principal MUST identify an authorized accessor for whom the access token is being requested (typically the resource owner, or an authorized delegate).
Audience
A URI that identifies the party intended to process the assertion. The audience SHOULD be the URL of the Token Endpoint as defined in section 2.2 of OAuth 2.0 [I-D.ietf.oauth-v2].
Issued At
The time at which the assertion was issued. While the serialization may differ by assertion format, this is always expressed in UTC with no time zone component.
Expires At
The time at which the assertion expires. While the serialization may differ by assertion format, this is always expressed in UTC with no time zone component.
Assertion ID
A nonce or unique identifier for the assertion. The Assertion ID may be used by implementations requiring message de- duplication for one-time use assertions. Any entity that assigns an identifier MUST ensure that there is negligible probability that that entity or any other entity will accidentally assign the same identifier to a different data object.

5.2. General Assertion Format and Processing Rules

The following are general format and processing rules for the use of assertions in OAuth:

  • The assertion MUST contain an Issuer. The Issuer MUST identify the entity that issued the assertion as recognized by the Authorization Server. If an assertion is self-asserted, the Issuer SHOULD be the client_id.
  • The assertion SHOULD contain a Principal. The Principal MUST identify an authorized accessor for whom the access token is being requested ( typically the resource owner, or an authorized delegate ) When the client is acting on behalf of itself, the Principal SHOULD be the client_id.
  • The assertion MUST contain an Audience that identifies the Authorization Server as the intended audience. The Authorization Server MUST verify that it is an intended audience for the assertion. The Audience SHOULD be the URL of the Authorization Server’s Token Endpoint.
  • The assertion MUST contain an Expires At entity that limits the time window during which the assertion can be used. The authorization server MUST verify that the expiration time has not passed, subject to allowable clock skew between systems. The authorization server SHOULD reject assertions with an Expires At attribute value that is unreasonably far in the future.
  • The assertion MAY contain an Issued At entity containing the UTC time at which the assertion was issued.
  • The assertion MAY contain an Assertion ID. An Authorization Server MAY dictate that Assertion ID is mandatory.
  • The Authorization Server MUST validate the assertion in order to establish a mapping between the Issuer and the secret used to generate the assertion. The algorithm used to validate the assertion, and the mechanism for designating the secret used to generate the assertion is out-of-scope for this specification.

6. Specific Assertion Format and Processing Rules

The following clarifies the format and processing rules defined in section 4 and section 5 for a number of common use-cases:

images/6.png

Format and Rules:

6.1. Client authentication

When a client authenticates to a token service using an assertion, it SHOULD do so according to section 4.1. The following format and processing rules SHOULD be applied:

The following non-normative example demonstrates the use of a client authentication using an assertion during an Authorization Code Access Token Request as defined in Section 4.1.3 of OAuth 2.0 [I-D.ietf.oauth-v2]. (line breaks are for display purposes only):

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=i1WsRn1uB1&
client_id=s6BhdRkqt3&
client_assertion_type=urn%3Aoasis%3Anames%sAtc%3ASAML%3A2.0%3Aassertion&
client_assertion=PHNhbWxwOl...[omitted for brevity]...ZT4

6.2. Client acting on behalf of itself

When a client is accessing resources on behalf of itself, it SHOULD do so in a manner analogous to the Client Credentials flow defined in Section 4.4 of OAuth 2.0 [I-D.ietf.oauth-v2]. This is a special case that combines both the authentication and authorization grant usage patterns. In this case, the interactions with the authorization server SHOULD be treated as using an assertion for Client Authentication according to section 4.1, with the addition of a grant_type parameter.

The following format and processing rules SHOULD be applied.

The following non-normative example demonstrates the use of a sample assertion being used for a Client Credentials Access Token Request as defined in Section 4.4.2 of OAuth 2.0 [I-D.ietf.oauth-v2]. (line breaks are for display purposes only):

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

client_id=s6BhdRkqt3&
grant_type=client_credentials&
client_assertion_type=urn%3Aoasis%3Anames%sAtc%3ASAML%3A2.0%3Aassertion&
client_assertion=PHNhbWxwOl...[omitted for brevity]...ZT4%3D

6.3. Client acting on behalf of a user

Note

I’m not quite sure what use case is taken accounted into....

When a client is accessing resources on behalf of a user, it SHOULD be treated as using an assertion as an Authorization Grant according to section 4.2. The following format and processing rules SHOULD be applied:

The following non-normative example demonstrates the use of a client authenticating using an assertion during an Authorization Code Access Token Request as defined in Section 4.1.3 of OAuth 2.0 [I-D.ietf.oauth-v2]. (line breaks are for display purposes only):

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

client_id=s6BhdRkqt3&
grant_type=urn%3Aoasis%3Anames%sAtc%3ASAML%3A2.0%3Aassertion&
assertion=PHNhbWxwOl...[omitted for brevity]...ZT4%3D

6.4. Client acting on behalf of an anonymous user

When a client is accessing resources on behalf of an anonymous user, the following format and processing rules SHOULD be applied:

  • The client_id HTTP parameter MUST identify the client to the authorization server.
  • The grant_type HTTP request parameter MUST indicate the assertion format.
  • The assertion HTTP parameter MUST contain the serialized assertion as in a format indicated by the grant_type parameter.
  • The Issuer of the assertion MUST identify the entity that issued the assertion as recognized by the Authorization Server. If the assertion is self-asserted, the Issuer SHOULD be the client_id. If the assertion was issued by a Security Token Service, the Issuer SHOULD identify the STS as recognized by the Authorization Server.
  • The Principal SHOULD indicate to the Authorization Server that the client is acting on-behalf of an anonymous user as defined by the Authorization Server. It is implied that authorization is based upon additional criteria, such as additional attributes or claims provided in the assertion. For example, a client may present an assertion from a trusted issuer asserting that the bearer is over 18 via an included claim. In this case, no additional information about the user’s identity is included yet all the data needed to issue an access token is present.
  • The Audience of the assertion MUST identify the Authorization Server and MAY be the URL of the Token Endpoint.
  • The Authorization Server MUST validate the assertion in order to establish a mapping between the Issuer and the secret used to generate the assertion.

7. Error Responses

If an assertion is not valid or has expired, the Authorization Server MUST construct an error response as defined in OAuth 2.0 [I-D.ietf.oauth-v2]. The value of the error parameter MUST be the “invalid_grant” error code. The authorization server MAY include additional information regarding the reasons the assertion was considered invalid using the “error_description” or “error_uri” parameters.

For example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{
"error":"invalid_grant",
"error_description":"Audience validation failed"
}

A client MUST NOT include client credentials using more than one mechanism. Token endpoints can differentiate between assertion based credentials and other client credential types by looking for the presence of the client_assertion and client_assertion_type attributes which will only be present when using assertions for client authentication.

If more than one mechanism is used, the Authorization Server MUST construct an error response as defined in OAuth 2.0 [I-D.ietf.oauth-v2]. The value of the error parameter MUST be the “invalid_client” error code. The authorization server MAY include additional information regarding the reasons the client was considered invalid using the “error_description” or “error_uri” parameters.

For example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{
"error":"invalid_client"
"error_description":"Multiple Credentials Not Allowed"
}

8. Security Considerations

Authorization Providers concerned with preventing replay attacks may choose to implement using replay detection using a combination of the AssertionID and IssuedAt/ExpiredAt attributes. Previously processed assertions MAY be de-duped and rejected based on the AssertionID.

The addition of the validity window relieves the authorization server from maintaining an infinite state table of processed assertion IDs.

Authorization Servers SHOULD consider the amount of information exposed in error responses, and the risk associated with exposing details of specific processing errors. In addition, Authorization Servers SHOULD prevent timing attacks related to cryptographic processing of the assertion.

No additional considerations beyond those described within the OAuth 2.0 Protocol Framework, Section 10 [I-D.ietf.oauth-v2].

9. IANA Considerations

9.1. Parameter Registration Request

The following is the parameter registration request, as defined in The OAuth Parameters Registry of The OAuth 2.0 Authorization Protocol [I-D.ietf.oauth-v2], for the “assertion” parameter:

  • Parameter name: assertion
  • Parameter usage location: client authentication, token request
  • Change controller: IETF
  • Specification document(s): [[this document]]

9.2. Parameter Registration Request

The following is the parameter registration request, as defined in The OAuth Parameters Registry of The OAuth 2.0 Authorization Protocol [I-D.ietf.oauth-v2], for the “client_assertion” parameter:

  • Parameter name: client_assertion
  • Parameter usage location: client authentication, token request
  • Change controller: IETF
  • Specification document(s): [[this document]]

9.3. Parameter Registration Request

The following is the parameter registration request, as defined in The OAuth Parameters Registry of The OAuth 2.0 Authorization Protocol [I-D.ietf.oauth-v2], for the “client_assertion_type” parameter:

  • Parameter name: client_assertion_type
  • Parameter usage location: client authentication, token request
  • Change controller: IETF
  • Specification document(s): [[this document]]

10. Acknowledgements

The authors wish to thank the following people that have influenced or contributed this specification: Paul Madsen, Eric Sachs, Jian Cai, Tony Nadalin, the authors of OAuth WRAP, and those in the OAuth 2 working group.

11. Normative References

[I-D.ietf.oauth-v2]
Hammer-Lahav, E., “The OAuth 2.0 Authorization Protocol”, September 2011.
[RFC2119]
Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997.

«  SAML 2.0 Bearer Assertion Profiles for OAuth 2.0   ::   Contents   ::   OAuth 2.0 Multiple Response Type Encoding Practices  »