diff options
Diffstat (limited to 'doc/rfc/rfc7521.txt')
| -rw-r--r-- | doc/rfc/rfc7521.txt | 1123 |
1 files changed, 1123 insertions, 0 deletions
diff --git a/doc/rfc/rfc7521.txt b/doc/rfc/rfc7521.txt new file mode 100644 index 0000000..89340d8 --- /dev/null +++ b/doc/rfc/rfc7521.txt @@ -0,0 +1,1123 @@ + + + + + + +Internet Engineering Task Force (IETF) B. Campbell +Request for Comments: 7521 Ping Identity +Category: Standards Track C. Mortimore +ISSN: 2070-1721 Salesforce + M. Jones + Y. Goland + Microsoft + May 2015 + + + Assertion Framework for OAuth 2.0 Client Authentication and + Authorization Grants + +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; + general processing rules are also specified. + + 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. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc7521. + + + + + + + + +Campbell, et al. Standards Track [Page 1] + +RFC 7521 OAuth Assertion Framework May 2015 + + +Copyright Notice + + Copyright (c) 2015 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. + +Table of Contents + + 1. Introduction ....................................................3 + 2. Notational Conventions ..........................................4 + 3. Framework .......................................................4 + 4. Transporting Assertions .........................................7 + 4.1. Using Assertions as Authorization Grants ...................7 + 4.1.1. Error Responses .....................................8 + 4.2. Using Assertions for Client Authentication .................9 + 4.2.1. Error Responses ....................................10 + 5. Assertion Content and Processing ...............................10 + 5.1. Assertion Metamodel .......................................10 + 5.2. General Assertion Format and Processing Rules .............12 + 6. Common Scenarios ...............................................12 + 6.1. Client Authentication .....................................13 + 6.2. Client Acting on Behalf of Itself .........................13 + 6.3. Client Acting on Behalf of a User .........................13 + 6.3.1. Client Acting on Behalf of an Anonymous User .......14 + 7. Interoperability Considerations ................................14 + 8. Security Considerations ........................................15 + 8.1. Forged Assertion ..........................................15 + 8.2. Stolen Assertion ..........................................15 + 8.3. Unauthorized Disclosure of Personal Information ...........16 + 8.4. Privacy Considerations ....................................17 + 9. IANA Considerations ............................................17 + 9.1. "assertion" Parameter Registration ........................17 + 9.2. "client_assertion" Parameter Registration .................18 + 9.3. "client_assertion_type" Parameter Registration ............18 + 10. References ....................................................18 + 10.1. Normative References .....................................18 + 10.2. Informative References ...................................18 + Acknowledgements ..................................................20 + Authors' Addresses ................................................20 + + + +Campbell, et al. Standards Track [Page 2] + +RFC 7521 OAuth Assertion Framework May 2015 + + +1. Introduction + + An assertion is a package of information that facilitates the sharing + of identity and security information across security domains. + Section 3 provides a more detailed description of the concept of an + assertion for the purpose of this specification. + + 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. + + 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) and to 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. In order to be implementable, companion specifications are + necessary to provide the corresponding concrete instantiations. For + instance, "Security Assertion Markup Language (SAML) 2.0 Profile for + OAuth 2.0 Client Authentication and Authorization Grants" [RFC7522] + defines a concrete instantiation for Security Assertion Markup + Language (SAML) 2.0 Assertions and "JSON Web Token (JWT) Profile for + OAuth 2.0 Client Authentication and Authorization Grants" [RFC7523] + defines a concrete instantiation for JWTs. + + 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 + + + +Campbell, et al. Standards Track [Page 3] + +RFC 7521 OAuth Assertion Framework May 2015 + + + 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. + +2. Notational Conventions + + 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. + +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, and 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 or integrity-protects 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 integrity protected using a digital + signature or Message Authentication Code (MAC) applied by the issuer, + which authenticates the issuer and ensures integrity of the assertion + content. In many cases, the assertion is issued by a third party, + and it must be protected against tampering by the client that + presents it. An assertion MAY additionally be encrypted, preventing + unauthorized parties (such as the client) 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. + + + + + + +Campbell, et al. Standards Track [Page 4] + +RFC 7521 OAuth Assertion Framework May 2015 + + + 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 integrity-protect them with a signature + or message authentication code. 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: Assertion Created by Third Party + + In the second pattern, depicted in Figure 2, the client creates + assertions locally. To apply the signatures or message + authentication codes to 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. + + + + +Campbell, et al. Standards Track [Page 5] + +RFC 7521 OAuth Assertion Framework May 2015 + + + 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. + + 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 + (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. Secure communication + channels are 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. + + The protocol parameters and processing rules defined in this document + are intended to support a client presenting a bearer assertion to an + authorization server. They are not directly suitable for use with + holder-of-key assertions. While they could be used as a baseline for + a holder-of-key assertion system, there would be a need for + + + + + +Campbell, et al. Standards Track [Page 6] + +RFC 7521 OAuth Assertion Framework May 2015 + + + additional mechanisms (to support proof-of-possession of the secret + key), and possibly changes to the security model (e.g., to relax the + requirement for an Audience). + +4. Transporting Assertions + + 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 use Transport + Layer Security (TLS), as mandated in Section 3.2 of OAuth 2.0 + [RFC6749]. + +4.1. Using Assertions as Authorization Grants + + This section defines the use of assertions as authorization grants, + based on the definition provided in Section 4.5 of OAuth 2.0 + [RFC6749]. When using assertions as authorization grants, the client + includes the assertion and related information using the following + HTTP request parameters: + + grant_type + REQUIRED. The format of the assertion as defined by the + authorization server. The value will be an absolute URI. + + assertion + REQUIRED. The assertion being used as an authorization grant. + Specific serialization of the assertion is defined by profile + documents. + + scope + OPTIONAL. The requested scope as described in Section 3.3 of + OAuth 2.0 [RFC6749]. When exchanging assertions for access + tokens, the authorization for the token has been previously + granted through some out-of-band mechanism. As such, the + requested scope MUST be equal to or less than the scope originally + granted to the authorized accessor. The authorization server MUST + limit the scope of the issued access token to be equal to or less + than the scope originally granted to the authorized accessor. + + Authentication of the client is optional, as described in + Section 3.2.1 of OAuth 2.0 [RFC6749], and consequently, the + "client_id" is only needed when a form of client authentication that + relies on the parameter is used. + + + + + + +Campbell, et al. Standards Track [Page 7] + +RFC 7521 OAuth Assertion Framework May 2015 + + + The following example demonstrates an assertion being used as an + authorization grant (with extra line breaks for display purposes + only): + + POST /token HTTP/1.1 + Host: server.example.com + Content-Type: application/x-www-form-urlencoded + + 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 IETF URN for use as the "grant_type" value can be requested using + the template in [RFC6755]. A URN of the form + urn:ietf:params:oauth:grant-type:* is suggested. + +4.1.1. Error Responses + + If an assertion is not valid or has expired, the authorization server + constructs an error response as defined in OAuth 2.0 [RFC6749]. 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" + } + + + + + + + +Campbell, et al. Standards Track [Page 8] + +RFC 7521 OAuth Assertion Framework May 2015 + + +4.2. Using Assertions for Client Authentication + + The following section defines the use of assertions as client + credentials as an extension of Section 2.3 of OAuth 2.0 [RFC6749]. + When using assertions as client credentials, the client includes the + assertion and related information using the following HTTP request + parameters: + + client_assertion_type + REQUIRED. The format of the assertion as defined by the + authorization server. The value will 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. + + client_id + OPTIONAL. The client identifier as described in Section 2.2 of + OAuth 2.0 [RFC6749]. The "client_id" is unnecessary for client + assertion authentication because the client is identified by the + subject of the assertion. If present, the value of the + "client_id" parameter MUST identify the same client as is + identified by the client assertion. + + The following example demonstrates a client authenticating using an + assertion during an access token request, as defined in Section 4.1.3 + of OAuth 2.0 [RFC6749] (with extra 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=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4& + 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 IETF URN for use as the "client_assertion_type" value may be + requested using the template in [RFC6755]. A URN of the form + urn:ietf:params:oauth:client-assertion-type:* is suggested. + + + +Campbell, et al. Standards Track [Page 9] + +RFC 7521 OAuth Assertion Framework May 2015 + + +4.2.1. Error Responses + + If an assertion is invalid for any reason or if more than one client + authentication mechanism is used, the authorization server constructs + an error response as defined in OAuth 2.0 [RFC6749]. 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" + } + +5. Assertion Content and Processing + + This section provides a general content and processing model for the + use of assertions in OAuth 2.0 [RFC6749]. + +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 + A unique identifier for the entity that issued the assertion. + Generally, this is the entity that holds the key material used to + sign or integrity-protect the assertion. Examples of issuers are + OAuth clients (when assertions are self-issued) and third-party + security token services. If the assertion is self-issued, the + Issuer value is the client identifier. If the assertion was + issued by a security token service (STS), the Issuer should + identify the STS in a manner recognized by the authorization + server. In the absence of an application profile specifying + otherwise, compliant applications MUST compare Issuer values using + the Simple String Comparison method defined in Section 6.2.1 of + RFC 3986 [RFC3986]. + + + + +Campbell, et al. Standards Track [Page 10] + +RFC 7521 OAuth Assertion Framework May 2015 + + + Subject + A unique identifier for the principal that is the subject of the + assertion. + + * When using assertions for client authentication, the Subject + identifies the client to the authorization server using the + value of the "client_id" of the OAuth client. + + * When using assertions as an authorization grant, the Subject + identifies an authorized accessor for which the access token is + being requested (typically, the resource owner or an authorized + delegate). + + Audience + A value that identifies the party or parties intended to process + the assertion. The URL of the token endpoint, as defined in + Section 3.2 of OAuth 2.0 [RFC6749], can be used to indicate that + the authorization server is a valid intended audience of the + assertion. In the absence of an application profile specifying + otherwise, compliant applications MUST compare the Audience values + using the Simple String Comparison method defined in Section 6.2.1 + of RFC 3986 [RFC3986]. + + Issued At + The time at which the assertion was issued. While the + serialization may differ by assertion format, it is REQUIRED that + the time be 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, it is REQUIRED that the time be + 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 for + that entity or any other entity to accidentally assign the same + identifier to a different data object. + + + + + + + + + + + +Campbell, et al. Standards Track [Page 11] + +RFC 7521 OAuth Assertion Framework May 2015 + + +5.2. General Assertion Format and Processing Rules + + The following are general format and processing rules for the use of + assertions in OAuth: + + o The assertion MUST contain an Issuer. The Issuer identifies the + entity that issued the assertion as recognized by the + authorization server. If an assertion is self-issued, the Issuer + MUST be the value of the client's "client_id". + + o The assertion MUST contain a Subject. The Subject typically + identifies an authorized accessor for which the access token is + being requested (i.e., the resource owner or an authorized + delegate) but, in some cases, may be a pseudonymous identifier or + other value denoting an anonymous user. When the client is acting + on behalf of itself, the Subject MUST be the value of the client's + "client_id". + + o The assertion MUST contain an Audience that identifies the + authorization server as the intended audience. The authorization + server MUST reject any assertion that does not contain its own + identity as the intended audience. + + o The assertion MUST contain an Expires At entity that limits the + time window during which the assertion can be used. The + authorization server MUST reject assertions that have expired + (subject to allowable clock skew between systems). Note that the + authorization server may reject assertions with an Expires At + attribute value that is unreasonably far in the future. + + o The assertion MAY contain an Issued At entity containing the UTC + time at which the assertion was issued. + + o The authorization server MUST reject assertions with an invalid + signature or MAC. The algorithm used to validate the signature or + message authentication code and the mechanism for designating the + secret used to generate the signature or message authentication + code over the assertion are beyond the scope of this + specification. + +6. Common Scenarios + + The following provides additional guidance, beyond the format and + processing rules defined in Sections 4 and 5, on assertion use for a + number of common use cases. + + + + + + +Campbell, et al. Standards Track [Page 12] + +RFC 7521 OAuth Assertion Framework May 2015 + + +6.1. Client Authentication + + A client uses an assertion to authenticate to the authorization + server's token endpoint by using the "client_assertion_type" and + "client_assertion" parameters as defined in Section 4.2. The Subject + of the assertion identifies the client. If the assertion is self- + issued by the client, the Issuer of the assertion also identifies the + client. + + The example in Section 4.2 shows a client authenticating using an + assertion during an access token request. + +6.2. Client Acting on Behalf of Itself + + When a client is accessing resources on behalf of itself, it does so + in a manner analogous to the Client Credentials Grant defined in + Section 4.4 of OAuth 2.0 [RFC6749]. 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, while using the "grant_type" + parameter with the value "client_credentials" to indicate that the + client is requesting an access token using only its client + credentials. + + The following example demonstrates an assertion being used for a + client credentials access token request, as defined in Section 4.4.2 + of OAuth 2.0 [RFC6749] (with extra line breaks for display purposes + only): + + POST /token HTTP/1.1 + Host: server.example.com + Content-Type: application/x-www-form-urlencoded + + grant_type=client_credentials& + client_assertion_type=urn%3Aietf%3Aparams%3Aoauth + %3Aclient-assertion-type%3Asaml2-bearer& + client_assertion=PHNhbW...[omitted for brevity]...ZT + +6.3. Client Acting on Behalf of a User + + When a client is accessing resources on behalf of a user, it does so + by using the "grant_type" and "assertion" parameters as defined in + Section 4.1. The Subject identifies an authorized accessor for which + the access token is being requested (typically, the resource owner or + an authorized delegate). + + + + + +Campbell, et al. Standards Track [Page 13] + +RFC 7521 OAuth Assertion Framework May 2015 + + + The example in Section 4.1 shows a client making an access token + request using an assertion as an authorization grant. + +6.3.1. Client Acting on Behalf of an Anonymous User + + When a client is accessing resources on behalf of an anonymous user, + a mutually agreed-upon Subject identifier indicating anonymity is + used. The Subject value might be an opaque persistent or transient + pseudonymous identifier for the user or be an agreed-upon static + value indicating an anonymous user (e.g., "anonymous"). The + authorization may be based upon additional criteria, such as + additional attributes or claims provided in the assertion. For + example, a client might 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. + + More information about anonymity, pseudonymity, and privacy + considerations in general can be found in [RFC6973]. + +7. Interoperability Considerations + + This specification defines a framework for using assertions with + OAuth 2.0. However, as an abstract framework in which the data + formats used for representing many values are not defined, on its + own, this specification is not sufficient to produce interoperable + implementations. + + Two other specifications that profile this framework for specific + assertions have been developed: [RFC7522] uses SAML 2.0 Assertions + and [RFC7523] uses JSON Web Tokens (JWTs). These two instantiations + of this framework specify additional details about the assertion + encoding and processing rules for using those kinds of assertions + with OAuth 2.0. + + However, even when profiled for specific assertion types, agreements + between system entities regarding identifiers, keys, and endpoints + are required in order to achieve interoperable deployments. Specific + items that require agreement are as follows: values for the Issuer + and Audience identifiers, supported assertion and client + authentication types, the location of the token endpoint, the key + used to apply and verify the digital signature or MAC over the + assertion, one-time use restrictions on assertions, maximum assertion + lifetime allowed, and the specific Subject and attribute requirements + of the assertion. The exchange of such information is explicitly out + of the scope of this specification. Deployments for particular trust + frameworks, circles of trust, or other uses cases will need to agree + + + +Campbell, et al. Standards Track [Page 14] + +RFC 7521 OAuth Assertion Framework May 2015 + + + among the participants on the kinds of values to be used for some + abstract fields defined by this specification. In some cases, + additional profiles may be created that constrain or prescribe these + values or specify how they are to be exchanged. The "OAuth 2.0 + Dynamic Client Registration Core Protocol" [OAUTH-DYN-REG] is one + such profile that enables OAuth Clients to register metadata about + themselves at an authorization server. + +8. Security Considerations + + This section discusses security considerations that apply when using + assertions with OAuth 2.0 as described in this document. As + discussed in Section 3, there are two different ways to obtain + assertions: either as self-issued 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. 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 concern + presenting an assertion for client authentication and for the + authorization grant. + +8.1. Forged Assertion + + Threat: + An adversary could forge or alter an assertion in order to obtain + an access token (in the case of the authorization grant) or to + impersonate a client (in the case of the client authentication + mechanism). + + Countermeasures: + To avoid this kind of attack, the entities must assure that proper + mechanisms for protecting the integrity of the assertion are + employed. This includes the issuer digitally signing the + assertion or computing a MAC over the assertion. + +8.2. Stolen Assertion + + Threat: + An adversary may be able obtain an assertion (e.g., by + eavesdropping) and then reuse it (replay it) at a later point in + time. + + + + + + +Campbell, et al. Standards Track [Page 15] + +RFC 7521 OAuth Assertion Framework May 2015 + + + Countermeasures: + The primary mitigation for this threat is the use of secure + communication channels with server authentication for all network + exchanges. + + An assertion may also contain several elements to prevent replay + attacks. There is, however, a clear trade-off between reusing an + assertion for multiple exchanges and obtaining and creating new, + fresh assertions. + + Authorization servers and resource servers may use a combination + of the Assertion ID and Issued At/Expires At attributes for replay + protection. Previously processed assertions may be rejected based + on the Assertion ID. The addition of the validity window relieves + the authorization server from maintaining an infinite state table + of processed Assertion IDs. + +8.3. Unauthorized Disclosure of Personal Information + + Threat: + The ability for other entities to obtain information about an + individual, such as authentication information, role in an + organization, or other authorization-relevant information, raises + privacy concerns. + + Countermeasures: + To address this threat, two cases need to be differentiated: + + First, a third party that did not participate in any of the + exchange is prevented from eavesdropping on the content of the + assertion by employing confidentiality protection of the exchange + using TLS. This ensures that an eavesdropper on the wire is + unable to obtain information. However, this does not prevent + legitimate protocol entities from obtaining information that they + are not allowed to possess from assertions. Some assertion + formats allow for the assertion to be encrypted, preventing + unauthorized parties from inspecting the content. + + Second, an authorization server may obtain an assertion that was + created by a third-party token service and that token service may + have placed attributes into the assertion. To mitigate potential + privacy problems, prior consent for the release of such attribute + information from the resource owner should be obtained. OAuth + itself does not directly provide such capabilities, but this + consent approval may be obtained using other identity management + protocols or user consent interactions; it may also be obtained in + an out-of-band fashion. + + + + +Campbell, et al. Standards Track [Page 16] + +RFC 7521 OAuth Assertion Framework May 2015 + + + For the cases where a third-party token service creates assertions + to be used for client authentication, privacy concerns are + typically lower, since many of these clients are Web servers + rather than individual devices operated by humans. If the + assertions are used for client authentication of devices or + software that can be closely linked to end users, then privacy + protection safeguards need to be taken into consideration. + + Further guidance on privacy friendly protocol design can be found + in [RFC6973]. + +8.4. Privacy Considerations + + An assertion may contain privacy-sensitive information and, to + prevent disclosure of such information to unintended parties, should + only be transmitted over encrypted channels, such as TLS. In cases + where it is desirable to prevent disclosure of certain information to + the client, the assertion (or portions of it) should be encrypted to + the authorization server. + + Deployments should determine the minimum amount of information + necessary to complete the exchange and include only such information + in the assertion. In some cases, the Subject identifier can be a + value representing an anonymous or pseudonymous user, as described in + Section 6.3.1. + +9. IANA Considerations + + This section registers three values, as listed in the subsections + below, in the IANA "OAuth Parameters" registry established by RFC + 6749 [RFC6749]. + +9.1. "assertion" Parameter Registration + + o Name: assertion + + o Parameter Usage Location: token request + + o Change Controller: IESG + + o Specification Document(s): RFC 7521 + + + + + + + + + + +Campbell, et al. Standards Track [Page 17] + +RFC 7521 OAuth Assertion Framework May 2015 + + +9.2. "client_assertion" Parameter Registration + + o Name: client_assertion + + o Parameter Usage Location: token request + + o Change Controller: IESG + + o Specification Document(s): RFC 7521 + +9.3. "client_assertion_type" Parameter Registration + + o Name: client_assertion_type + + o Parameter Usage Location: token request + + o Change Controller: IESG + + o Specification Document(s): RFC 7521 + +10. References + +10.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + <http://www.rfc-editor.org/info/rfc2119>. + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, DOI 10.17487/RFC3986, January 2005, + <http://www.rfc-editor.org/info/rfc3986>. + + [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", + RFC 6749, DOI 10.17487/RFC6749, October 2012, + <http://www.rfc-editor.org/info/rfc6749>. + +10.2. Informative References + + [OASIS.WS-Trust] + Nadalin, A., Ed., Goodner, M., Ed., Gudgin, M., Ed., + Barbir, A., Ed., and H. Granqvist, Ed., "WS-Trust", + February 2009, <http://docs.oasis-open.org/ws-sx/ + ws-trust/v1.4/ws-trust.html>. + + + + + + +Campbell, et al. Standards Track [Page 18] + +RFC 7521 OAuth Assertion Framework May 2015 + + + [OAUTH-DYN-REG] + Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and + P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", + Work in Progress, draft-ietf-oauth-dyn-reg-29, May 2015. + + [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace + for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, + <http://www.rfc-editor.org/info/rfc6755>. + + [RFC6973] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., + Morris, J., Hansen, M., and R. Smith, "Privacy + Considerations for Internet Protocols", RFC 6973, + DOI 10.17487/RFC6973, July 2013, + <http://www.rfc-editor.org/info/rfc6973>. + + [RFC7522] Campbell, B., Mortimore, C., and M. Jones, "Security + Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 + Client Authentication and Authorization Grants", RFC 7522, + DOI 10.17487/RFC7522, May 2015, + <http://www.rfc-editor.org/info/rfc7522>. + + [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token + (JWT) Profile for OAuth 2.0 Client Authentication and + Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May + 2015, <http://www.rfc-editor.org/info/rfc7523>. + + + + + + + + + + + + + + + + + + + + + + + + + + +Campbell, et al. Standards Track [Page 19] + +RFC 7521 OAuth Assertion Framework May 2015 + + +Acknowledgements + + The authors wish to thank the following people who have influenced or + contributed to this specification: Paul Madsen, Eric Sachs, Jian Cai, + Tony Nadalin, Hannes Tschofenig, the authors of the OAuth WRAP + specification, and the members of the OAuth working group. + +Authors' Addresses + + Brian Campbell + Ping Identity + + EMail: brian.d.campbell@gmail.com + + + Chuck Mortimore + Salesforce.com + + EMail: cmortimore@salesforce.com + + + Michael B. Jones + Microsoft + + EMail: mbj@microsoft.com + URI: http://self-issued.info/ + + + Yaron Y. Goland + Microsoft + + EMail: yarong@microsoft.com + + + + + + + + + + + + + + + + + + + +Campbell, et al. Standards Track [Page 20] + |