| OAuth Working Group | B. Campbell |
| Internet-Draft | Ping |
| Intended status: Standards Track | C. Mortimore |
| Expires: January 01, 2013 | Salesforce |
| M.B. Jones | |
| Y.Y. Goland | |
| Microsoft | |
| July 02, 2012 |
Assertion Framework for OAuth 2.0
draft-ietf-oauth-assertions-04
This specification provides a framework for the use of assertions with OAuth 2.0 in the form of new client authentication mechanism and a new authorization grant type. Mechanisms are specifies 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 and that, in order to be implementable, companion specifications are necessary to provide the corresponding instantiation.
The IETF has been notified of intellectual property rights claimed in regard to some or all of the specification contained in this document. For more information consult the online list of claimed rights.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 01, 2013.
Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
OAuth 2.0 [I-D.ietf-oauth-v2] is an authorization framework that enables a third-party application to obtain limited access to a protected HTTP resource. In OAuth those third-party application are called clients and 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 trust frameworks.
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 over HTTP), 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 flows and processing rules and that, in order to be implementable, companion specifications are necessary to provide the corresponding instantiation.
Note: The use of assertions for client authentication is orthogonal and separable from using assertions as an authorization grant and can be used either in combination or in isolation.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] .
Throughout this document, values are quoted to indicate that they are to be taken literally. When using these values in protocol messages, the quotes must not be used as part of the value.
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 who issued the assertion and when was it issued, as well as conditions under which the assertion is to be considered valid like 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 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 to prevent 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 that are worth mentioning.
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' or just 'Token Service' and a trust relationship (usually manifested in the exchange of some kind of keying material) exists between the token service and the relying party. The token service is the assertion issuer and its role is to fulfill requests from clients, who present various credentials, and mint assertions as requested, fill them with verified information, and sign them. WS-Trust [OASIS.WT-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 | |
|------------------------->| |
| | |
| | |
In Figure 2 the second pattern is depicted where the client creates assertions locally. In order to sign the assertions it has to obtain keying material, either a symmetric key or an asymmetric key pair, out-of-band or though some other process.
Although assertions are usually used to convey identity and security information, self-created 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 is included in such an assertion, such as issuing and conditions information.
Relying
Party Client
| |
| | 1) Create
| | Assertion
| |--------------+
| | |
| | 2) Assertion |
| |<-------------+
| 3) Assertion |
|<-------------------------|
| |
| 4) OK or Failure |
|------------------------->|
| |
| |
Deployments need to determine the best possible variant based on the required level of security, trust relationship between the entities, and other factors.
From the perspective of what must be done by the entity presenting the assertion, there are two general types of assertions:
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.
This section defines HTTP parameters for transporting assertions during interactions with a token endpoint of an OAuth authorization server. Because requests to the token endpoint result in the transmission of clear-text credentials (in both the HTTP request and response), all requests to the token endpoint MUST require the use of TLS as mandated in Section 3.2 of OAuth 2.0 [I-D.ietf-oauth-v2].
This section defines the use of assertions as authorization grants based on the definition provided in Section 4.5 of OAuth 2.0 [I-D.ietf-oauth-v2]. When using assertions as authorization grants, the client includes the assertion and related information using the following HTTP request parameters:
The following non-normative example demonstrates an assertion being used as an authorization grant (with line breaks 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%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer& assertion=PHNhbWxwOl...[omitted for brevity]...ZT4
An assertion used in this context is generally a short lived representation of the authorization grant and authorization servers SHOULD NOT issue access tokens with a lifetime that exceeds the validity period of the assertion by a significant period. In practice, that will usually mean that refresh tokens are not issued in response to assertion grant requests and access tokens will be issued with a reasonably short lifetime. Clients can refresh an expired access token by requesting a new one using the same assertion, if it is still valid, or with a new assertion.
An IEFT URN for use as the grant_type value can be requested using the template in An IETF URN Sub-Namespace for OAuth [I-D.ietf-oauth-urn-sub-ns]. A URN of the from urn:ietf:params:oauth:grant_type:* is suggested.
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"
}
The following section defines the use of assertions as client credentials as an extension of Section 2.3 of OAuth 2.0 [I-D.ietf-oauth-v2]. When using assertions as client credentials, the client includes the assertion and related information using the following HTTP request parameters:
The following non-normative example demonstrates a client authenticating using an assertion during an Authorization Token Request as defined in Section 4.1.3 of OAuth 2.0 [I-D.ietf-oauth-v2] (with line breaks 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%3Aietf%3Aparams%3Aoauth %3Aclient-assertion-type%3Asaml2-bearer& client_assertion=PHNhbW...[omitted for brevity]...ZT
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 parameters, which will only be present when using assertions for client authentication.
An IEFT URN for use as the client_assertion_type value may be requested using the template in An IETF URN Sub-Namespace for OAuth [I-D.ietf-oauth-urn-sub-ns]. A URN of the from urn:ietf:params:oauth:client-assertion-type:* is suggested.
If an assertion is invalid for any reason or if more than one client authentication 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 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_client"
"error_description":"assertion has expired"
}
This section provides a general content and processing model for the use of assertions in OAuth 2.0 [I-D.ietf-oauth-v2].
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.
The following are general format and processing rules for the use of assertions in OAuth:
The following clarifies the format and processing rules defined in Section 4 and Section 5 for a number of common use cases:
When a client uses an assertion for authentication it SHOULD do so according to Section 4.2. The following format and processing rules apply.
The following non-normative example demonstrates the use of a client authentication using an assertion during an Access Token Request as defined in Section 4.1.3 of OAuth 2.0 [I-D.ietf-oauth-v2] (with line breaks 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%3Aietf%3Aparams%3Aoauth %3Aclient-assertion-type%3Asaml2-bearer& client_assertion=PHNhb...[omitted for brevity]...ZT4
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.2, with the addition of a grant_type parameter. The following format and processing rules apply.
The following non-normative example demonstrates the use of a an 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] (with line breaks 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%3Aietf%3Aparams%3Aoauth %3Aclient-assertion-type%3Asaml2-bearer& client_assertion=PHNhbW...[omitted for brevity]...ZT
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.1. The following format and processing rules apply.
The following non-normative example demonstrates a client presenting as assertion during an Authorization Grant during an Access Token Request as defined in Section 4.1.3 of OAuth 2.0 [I-D.ietf-oauth-v2] (with line breaks 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%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer& assertion=PHNhbWxwOl...[omitted for brevity]...ZT
When a client is accessing resources on behalf of an anonymous user, the following format and processing rules apply.
This section discusses security considerations that apply when using assertions with OAuth 2.0 as proposed in this document. As described in Section 3 there are two different ways to obtain assertions, either as self-created or obtained from a third party token service. While the actual interactions for obtaining an assertion are outside the scope of this document, the details are important from a security perspective. Section 3 discusses the high level architectural aspects and many of the security considerations discussed in this section are applicable to both the OAuth exchange as well as the client obtaining the assertion.
The remainder of this section focuses on the exchanges that concerns presenting an assertion for client authentication and for the authorization grant.
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:
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:
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:
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |
| [I-D.ietf-oauth-v2] | Hammer-Lahav, E, Recordon, D and D Hardt, "The OAuth 2.0 Authorization Protocol", Internet-Draft draft-ietf-oauth-v2-25, March 2012. |
| [I-D.ietf-oauth-urn-sub-ns] | Campbell, B and H Tschofenig, "An IETF URN Sub-Namespace for OAuth", Internet-Draft draft-ietf-oauth-urn-sub-ns-05, June 2012. |
| [I-D.iab-privacy-considerations] | Cooper, A, Tschofenig, H, Aboba, B, Peterson, J and J Morris, "Privacy Considerations for Internet Protocols", Internet-Draft draft-iab-privacy-considerations-01, October 2011. |
| [OASIS.WT-Trust] | Nadalin, A., Goodner, M., Gudgin, M., Barbir, A. and H. Granqvist, "WS-Trust", Feb 2009. |
The authors wish to thank the following people that have influenced or contributed this specification: Paul Madsen, Eric Sachs, Jian Cai, Tony Nadalin, Hannes Tschofenig the authors of OAuth WRAP, and those in the OAuth working group.
[[ to be removed by RFC editor before publication as an RFC ]]
draft-ietf-oauth-assertions-04
draft-ietf-oauth-assertions-03
draft-ietf-oauth-assertions-02