RFC7521 - Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants

Abstract

[...] 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.

[...] to provide a common framework for OAuth 2.0 to interwork with other identity systems using assertions and to provide alternative client authentication mechanism.

1. Introduction

An assertion is a package of information that facilitates the sharing of identity and security information across security domains.

This specification provides two functionalities:

• a framework that uses packages of informations (assertions) as a credential representing the resource owner's authorization (authorization grant) with OAuth 2.0.
• a framework for assertions to be used for client authentication.

You'll also find:

[...] generic mechanisms for transporting assertions during interactions with an authorization server's token endpoint

[...] general rules for the content and processing of those assertions.

The intent behind adding this two functionalities are two:

• Alternative client authentication mechanism (one that doesn't send client secrets).
• Facilitate the use of OAuth 2.0 in client-server integration scenarios, where the end user may not be present.

Using the assertions as authorization grant is separable from using the assertion from client authentication. Each functionality can be used on its own.

Client assertion authentication is nothing more than an alternative way for a client to authenticate to the token endpoint.

2. Notational Conventions

Uses keywords as decribed in RFC 2119.

3. Framework

An assertion typically contains:

• information about a subject or principal
• information about the party that issued it
• when it was issued
• under which conditions the assertion is to be considered valid

The entity that creates and signs or integrity-protects it is know as the "Issuer".

The entity that consumes the assertion is known the "Relying party". In the context of this document, the authorization server acts as a Relying party.

The issuer must protect the integrity of an assertion by applying a digital signature or a Message Authentication Code (MAC). Its intent is to identify the issuer and ensure the assertion's content integrity.

In addition, an assertion might be encrypted.

The specification doesn't define how the Client obtains the assertion, but it suggests two main ways:

1. Assertion created by a third party

The Client obtains an assertion from a third-party entity capable of issuing, renewing, transforming, and validating security tokens. This entity is known as "security token service" (STS) or just "token service".

A trust relationship exists between the STS and the relying party (authorization service).

2. Self issued assertion

The Client creates assertions locally.

Self-issued assertions can be used to demonstrate knowledge of some secret, such as a Client secret, without actually communicating the secret directly in the transaction.

In the point of view of the entity presenting the assertion, there are two types of assertion:

1. Bearer Assertion: 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)
2. Holder-of-key Assertion: To access the associated resources, the entity presenting the assertion must demonstrate possession of additional cryptographic material. The STS thereby binds a key identifier to the assertion, and the Client has to demonstrate to the Relying Party knowledge about it.

The scope of this specification only covers a Client presenting a bearer assertion to an authorization server.

4. Transporting Assertions

Is mandatory to use HTTPS.

4.1. Using assertions as Authorization Grants

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.
• assertion: REQUIRED. The assertion being used as an authorization grant.
• scope: OPTIONAL. The request scope must be equal or less than the scope originally granted to the authorized accessor.

The authentication of the client is optional. Therefore, client_id is only required when the client authentication relies on this parameter.

Example:

POST /token HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer& assertion={assertion-goes-here}

An assertion used in this context is a short lived representation of the authorization grant. The access token issued by authorization server should not have a lifespan way bigger than its assertion validity.

4.1.1. Error Response

If an assertion is not valid or has expired the value of the error parameter must be the invalid_grant.

4.2 Using Assertions for Client Authentication

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.
• client_assertion: REQUIRED. The assertion being used to authenticate the client.
• client_id: OPTIONAL. It's unnecessary, the client is already identified by the subject of the assertion. If specified, it must be the same as identified by the client assertion.

Example:

POST /token HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code& code={{authorization_code_goes_here}}& client_assertion_type=urn:ietf:params:oauth:client-assertion-type:saml2-bearer& client_assertion={client_assertion-goes-here}

4.2.1. Error Response

If an assertion is invalid for any reason or if more than one client authentication mechanism is used the value of the error parameter must be the invalid_client.

5. Assertion Content and Processing

Provides general content and processing model for the use of assertions with OAuth 2.0.

5.1. Assertion Metamodel

The following are general terms abstract from any particular assertion format.

Issuer

A unique identifier for the entity that issued the assertion. It holds the key material used to sign or integrity-protect the assertion. OAuth Clients (self-issued assertions) and STS are examples.

Subject

A unique identifier for the principal that is the subject of the assertion. Two possible interpretations:

• Assertions during client authentication: Identifies the client to the authorization server using the value in the client_id.
• Assertions during authorization grant: Identifies an authorized accessor for which the access token is being requested.

Audience

Identifies the party or parties intended to process the assertion. The URL of the token endpoint can be used to indicate the authorization server as a valid intended audience.

Issued At

Time at which the assertion was issued. UTC format.

Expires At

Time at which the assertion expires. UTC format.

Assertion ID

An nonce or unique identifier for the assertion.

5.2. General Assertion Format and Processing Rules

The assertion must contain:

• Issuer
• Subject
• Audience: It must identify the authorization server as the intended audience.
• Expires At: Authorization server must reject assertions that are expired.
• Issued At

6. Common Scenarios

6.1. Client Authentication

A client uses an assertion to authenticate to the authorization server's token endpoint (as described in 4.2).

The assertion's Subject is the client.

If it's a self-issued assertion the assertion's Issuer is also the client.

6.2. Client Acting on Behalf of Itself

A client is accessing resources on behalf of itself. Analogous to the Client Credentials Grant. It combines both the authentication an authorization grant usage patterns.

The interaction with the authorization server is treated as using an assertion for Client authentication (as described in 4.2), while using the client_credentials as grant_type to indicate that the client is requesting an access token for itself.

Example:

POST /token HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded grant_type=client_credentials& client_assertion_type=urn:ietf:params:oauth:client-assertion-type:saml2-bearer& client_assertion={client_assertion-goes-here}

6.3. Client Acting on Behalf of a User

A client is accessing a resource on behalf of a user. It has to inform the assertion as the grant_type parameter (as described in 4.1). The Subject identifies an authorized accessor, typically the resource owner or an authorized delegate.

6.3.1. Client Acting on Behalf of an Anonymous User

A client is accessing resources on behalf of an anonymous user. A mutually agree-upon Subject identifier indicating anonymity is used.

Authorization may be based upon additional criteria, such as additional attributes or claims provided in the assertion.

7. Interoperability Considerations

On its own, this specification is not sufficient to produce interoperable implementations.

The RFC 7522 and RFC 7523 specify additional details about assertions encoding and processing rules.

Specific items that require agreement are:

• Values for the Issuer and Audience identifier
• Supported assertion and client authentication types
• The location of the token endpoint
• The key used to apply and verify the diginal signature or MAC over assertions
• Maximum assertion lifetime allowed
• Subject and attribute requirements

8. Security Considerations

8.1. Forged Assertion

Threat: An adversary could forge or alter an assertion in order to obtain an acces token (as described in 4.1) or to impersonate a client (as described in 4.2).

Countermeasure: Apply mechanisms for protecting the integrity of the assertion (digital signature or MAC).

8.2. Stolen Assertion

Threat: An adversary might obtain an assertion and then reuse it later in time.

Countermeasure: Use secure communication channels with server authentication for all network exchanges.

8.3. Unauthorized Disclosure of Personal Information

Threat: Other entities to obtain information about an individual (role in an organization, authentication information, ...)

Countermeasure: Use of TLS and encrypt assertion.

8.4. Privacy Considerations

An assertion may contain privacy-sensitive information, therefore, use TLS and encrypt this information.

9. IANA Considerations

Register of assertion, client_assertion, client_assertion_type.