Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants
Extracted elements (25)
Client assertion authentication is orthogonal to and separable from using an Assertion as an authorization grant; they may be used in combination or separately. This separation allows either mechanism to be adopted independently without requiring the other.
The format and processing rules for SAML Assertions in this specification are intentionally similar (though not identical) to those in the SAML Web Browser SSO profile, deliberately reusing well-established patterns to ease adoption for parties already familiar with SAML SSO deployments.
Agreement between system entities on identifiers (Issuer, Audience), token endpoint location, signing keys, one-time use restrictions, maximum Assertion lifetime, and Subject/attribute requirements must be configured out of band. SAML Metadata [OASIS.saml-metadata-2.0-os] is one common method for this exchange.
The RSA-SHA256 algorithm (from RFC 6931) is a mandatory-to-implement XML signature algorithm for this profile, ensuring a baseline of interoperability for Assertion signing.
For client authentication, the 'client_assertion' parameter MUST contain a single SAML 2.0 Assertion encoded using base64url. The encoded data SHOULD NOT be line wrapped and pad characters SHOULD NOT be included.
If client credentials are present in an authorization grant request, the authorization server MUST validate them regardless of whether client authentication is required by policy.
The Assertion MUST be digitally signed or have a MAC applied by the issuer. The authorization server MUST reject Assertions with an invalid signature or MAC.
The Assertion MUST contain a <Conditions> element with an <AudienceRestriction> element identifying the authorization server as an intended audience. The authorization server MUST reject any Assertion that does not contain its own identity as the intended audience.
The Assertion MUST contain a <Subject> element identifying the principal. For client authentication, the Subject MUST be the 'client_id' of the OAuth client.
The Assertion MUST have an expiry limiting the time window during which it can be used, expressed as the NotOnOrAfter attribute of the <Conditions> element or of a <SubjectConfirmationData> element.
The 'assertion' parameter MUST contain a single SAML 2.0 Assertion encoded using base64url (RFC 4648 Section 5, padding bits set to zero). The encoded data MUST NOT be line wrapped and pad characters ('=') MUST NOT be included.
The Assertion's <Issuer> element MUST contain a unique identifier for the issuing entity. Compliant applications MUST compare Issuer values using Simple String Comparison (RFC 3986 Section 6.2.1) absent an application profile specifying otherwise.
The authorization server MUST reject an Assertion that is not valid in all other respects per the SAML 2.0 core specification, including all content within the Conditions element.
The authorization server MUST reject the entire Assertion if the NotOnOrAfter instant on the <Conditions> element has passed (subject to allowable clock skew). The server MAY ensure Bearer Assertions are not replayed by maintaining used ID values.
The <Subject> element MUST contain at least one <SubjectConfirmation> with Method 'urn:oasis:names:tc:SAML:2.0:cm:bearer'. When present, <SubjectConfirmationData> MUST have a Recipient attribute matching the token endpoint URL and a NotOnOrAfter attribute.
When an Assertion authorization grant is invalid, the error response MUST use the 'invalid_grant' error code. When a client authentication Assertion is invalid, the error response MUST use the 'invalid_client' error code.
When the Assertion was issued with the intention that the client act autonomously on behalf of the subject, an <AuthnStatement> SHOULD NOT be included, and the presenting client SHOULD be identified in the <NameID> or <SubjectConfirmation> element or by other means such as the SAML Delegation Restriction condition.
Deployments should include only the minimum necessary information in an Assertion, limiting <AttributeStatement> content or omitting it altogether. The Subject MAY be a pseudonymous or anonymous identifier.
SAML Assertions may contain privacy-sensitive information and SHOULD only be transmitted over encrypted channels such as TLS. Subject and/or attributes SHOULD be encrypted to the authorization server when necessary to prevent disclosure to the client.
The client assertion type URN for using a SAML 2.0 Bearer Assertion for client authentication is 'urn:ietf:params:oauth:client-assertion-type:saml2-bearer', sent as the 'client_assertion_type' parameter.
The grant type URN for using a SAML 2.0 Bearer Assertion as an OAuth 2.0 authorization grant is 'urn:ietf:params:oauth:grant-type:saml2-bearer', sent as the 'grant_type' parameter in the token request.
The SAML Assertion used as an authorization grant must include an <Issuer>, <Subject> with bearer <SubjectConfirmation>, <Conditions> with <AudienceRestriction>, and a digital signature. An <AuthnStatement> SHOULD be included if the issuer directly authenticated the subject.
Registers URN 'urn:ietf:params:oauth:client-assertion-type:saml2-bearer' in the IANA OAuth URI registry for use as the client_assertion_type value when using a SAML 2.0 Bearer Assertion for client authentication.
Registers URN 'urn:ietf:params:oauth:grant-type:saml2-bearer' in the IANA OAuth URI registry (established by RFC 6755) for use as the grant_type value when presenting a SAML 2.0 Bearer Assertion as an authorization grant.
Replay protection for SAML Assertions used as authorization grants or for client authentication is optional; implementations may employ it at their discretion by maintaining the set of used Assertion ID values for the duration of their validity window.