doc: Add RFC documents

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]
+