Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants
Extracted elements (28)
Client assertion authentication is orthogonal to and separable from using assertions as an authorization grant; they may be combined or used independently. Whether client authentication is required alongside an assertion authorization grant is a policy decision left to the authorization server.
Self-issued assertions can be used to demonstrate knowledge of a secret (such as a client secret) without transmitting the secret directly. In this case, only a bare minimum of information (issuance and usage conditions) is typically included because additional client-supplied content provides limited value to the relying party.
The Assertion ID field enables replay prevention by allowing servers to reject previously seen assertion IDs. Combined with Expires At, this relieves the authorization server from maintaining an infinite state table of processed assertion IDs.
This specification intentionally defines only abstract message flows and processing rules. Companion specifications (e.g., RFC 7522 for SAML 2.0 and RFC 7523 for JWT) are necessary to provide concrete instantiations, allowing the framework to interwork with multiple identity assertion formats.
As an abstract framework, this specification alone is insufficient for interoperable implementations. Concrete instantiations (RFC 7522 for SAML 2.0, RFC 7523 for JWT) and out-of-band agreements on Issuer/Audience identifiers, keys, endpoints, assertion types, one-time-use restrictions, maximum lifetimes, and Subject/attribute requirements are all required.
IETF URN values for 'grant_type' should use the form urn:ietf:params:oauth:grant-type:* and for 'client_assertion_type' the form urn:ietf:params:oauth:client-assertion-type:*, both requestable via the template in RFC 6755.
All requests to the token endpoint MUST use Transport Layer Security (TLS), as mandated in Section 3.2 of OAuth 2.0 (RFC 6749), because requests result in the transmission of clear-text credentials.
An assertion MUST contain a Subject identifying the principal. When the client is acting on behalf of itself, the Subject MUST be the value of the client's 'client_id'.
An assertion MUST contain an Audience identifying 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. Audience values MUST be compared using Simple String Comparison per RFC 3986 Section 6.2.1.
An assertion MUST contain an Expires At value limiting its validity window. The authorization server MUST reject expired assertions (subject to allowable clock skew), and MAY also reject assertions whose Expires At is unreasonably far in the future.
An assertion MUST contain an Issuer. If the assertion is self-issued, the Issuer MUST be the value of the client's 'client_id'. Compliant applications MUST compare Issuer values using Simple String Comparison per RFC 3986 Section 6.2.1.
Assertions used in protocol exchanges 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.
Authorization servers SHOULD NOT issue access tokens with a lifetime that exceeds the validity period of the assertion by a significant period. In practice, refresh tokens are typically not issued in response to assertion grant requests.
If an assertion used as an authorization grant is not valid or has expired, the authorization server MUST return an error response with error code 'invalid_grant'.
If an assertion used for client authentication is invalid for any reason, or if more than one client authentication mechanism is used, the authorization server MUST return an error response with error code 'invalid_client'.
The authorization server MUST reject assertions with an invalid signature or MAC. The algorithm for validating the signature and the mechanism for designating the secret are beyond the scope of this specification and must be defined by profile documents.
When exchanging assertions for access tokens, the requested scope MUST be equal to or less than the scope originally granted to the authorized accessor. The authorization server MUST limit the issued access token scope accordingly.
Assertions may contain privacy-sensitive information and should only be transmitted over encrypted channels such as TLS. Where necessary, the assertion or portions of it should be encrypted to the authorization server to prevent disclosure to the client. Deployments should include only the minimum information necessary.
Bearer assertions allow any entity in possession of the assertion to use it without demonstrating possession of a cryptographic key, and therefore require confidentiality protection in storage and transport. Holder-of-Key assertions require the presenter to additionally demonstrate possession of cryptographic material bound to the assertion.
The assertion metamodel defines six abstract fields: Issuer (unique identifier for the issuing entity), Subject (principal the assertion is about), Audience (intended relying parties), Issued At (UTC time of issuance), Expires At (UTC expiry time), and Assertion ID (nonce for de-duplication).
When a client acts on behalf of itself (analogous to the Client Credentials Grant), it combines both authentication and authorization grant patterns: it uses 'client_assertion_type' and 'client_assertion' for authentication while specifying grant_type=client_credentials for the authorization request.
When acting on behalf of an anonymous user, a mutually agreed-upon pseudonymous or static Subject identifier (e.g., 'anonymous') is used. Authorization may rely on additional attributes or claims in the assertion (e.g., an age claim) without disclosing the user's identity.
When using assertions as authorization grants, the request MUST include 'grant_type' (REQUIRED, an absolute URI identifying the assertion format) and 'assertion' (REQUIRED, the assertion value). The 'scope' parameter is OPTIONAL but must not exceed the originally granted scope.
When using assertions for client authentication, the request MUST include 'client_assertion_type' (REQUIRED, an absolute URI) and 'client_assertion' (REQUIRED, the assertion value). The 'client_id' is OPTIONAL but, if present, MUST identify the same client as identified by the assertion's Subject.
This document registers three parameters in the IANA 'OAuth Parameters' registry (established by RFC 6749): 'assertion' (token request), 'client_assertion' (token request), and 'client_assertion_type' (token request).
Forged assertion threat: an adversary could forge or alter an assertion to obtain an access token or impersonate a client. Countermeasure: the issuer must digitally sign the assertion or compute a MAC to ensure integrity.
Stolen assertion / replay threat: an adversary may obtain an assertion by eavesdropping and replay it later. Countermeasures include TLS for all exchanges, short assertion lifetimes, and using a combination of Assertion ID and Issued At/Expires At attributes to detect and reject replays without maintaining an infinite state table.
Unauthorized disclosure threat: assertions may carry authentication information, role, or other personal attributes. Countermeasures include TLS confidentiality for wire exchanges, optional assertion encryption for sensitive payloads, and obtaining prior consent for release of attributes from the resource owner.