Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants

1. Introduction

The Security Assertion Markup Language 2.0 is an XML-based framework that allows identity and security information to be shared across security domains.

SAML is defined by another specification. OASIS.saml-core-2.0-os.

SAML is primarily targeted at providing cross domain Web browser single sign-on.

The assertion, an XML security token, defined by the SAML specification is often used by other protocols and specs.

An Identity Provider issues Assertions.

A Service Provider relies on its content to identify the Assertion's subject for security-related purposes.

After that, the specification gives a small overview about OAuth 2.0 (RFC 6749) and the use of assertions as authentication grant/ client credentials (RFC 7521).

This specification defines two main things:

1. How a SAML assertion can be used to request an access token when a client wishes to utilize an existing trust relationship (SAML Assertion), without a direct user approval step at the authorization server.
2. How a SAML can be used as a client authentication mechanism.

1.1. Notational Conventions

Uses keywords as described in RFC 2119.

1.2. Terminology

As described in the RFC6749, RFC 7521 and OASIS.saml-core-2.0-os.

2. HTTP Parameter Bindings for Transporting Assertions

Same parameters as defined in the RFC7521.

2.1. Using SAML Assertions as Authorization Grants

As described in the section 4.1 of the RFC7521.

The value of grant_type parameter is urn:ietf:params:oauth:grant-type:saml2-bearer.

The value of assertion parameter is contains a single SAML 2.0 Assertion encoded by base64url.

The scope parameter may be used to indicate the request scope.

Authentication of the client is optional.

Same example as RFC7521 in the section 4.1.

2.2. Using SAML Assertions for Client Authentication

As described in the section 4.2 of the RFC7522.

The value of client_assertion_type parameter is urn:ietf:params:oauth:client-assertion-type:saml2-bearer

The value of client_assertion parameter contains a single SAML 2.0 Assertion encoded by base64url.

Same example as RFC7521 in the section 4.2.

3. Assertion format and Processing Requirements

Authorization server must validate the Assertion according to the criteria below.

1. Assertion's Issuer has an unique identifier.
2. It must have an <Conditions> element with an <AudiencRestriction> element with an <Audience> element that identifies the authorization server as audience.

3. The Assertion must have an <Subject> element that identifies the principal that is the subject of the Assertion.

   1. Authorization grant: Resource Owner or authorized delegate.
   2. Client authentication: the client_id.
4. The assertion must have expiry. Either as the <Conditions NotOnOrAfter=""> or <SubjectConfirmationData NotOnOrAfter="">.
5. The <Subject>must have at least one <SubjectConfirmation>.
6. The authorization server rejects the Assertion if the expiry instant has passed.
7. Should contain a single <AuthnStatement> if the assertion issuer directly authenticated the subject.
8. May have AttributeStatement.
9. The Assertion must be digitally signed or have a MAC applied by the issuer.
10. The assertion may have encrypted elements.
11. The authorization server must reject an Assertion that is not valid in all other respects per SAML specification.

3.1. Authorization Grant Processing

Assertion authorization grant may be used with or without client authentication or identification.

If client credentials are presented in the request, the authorization server must validate them.

If the assertion is not valid, the server creates a error response as defined by the OAuth 2.0.

The error parameter must be invalid_grant.

3.2. Client Authorization Processing

If the client authorization is not valid the authorization server response follows the OAuth 2.0 structure.

The error parameter must be ìnvalid_client.

4. Authorization Grant Example

The Assertion is issued and signed by the SAML Identity Provider ("https://saml-idp.example.com").

The subject of the assertion is identified by email address ("brian@example.com"). He authenticated to the Identity Provider through digital signature.

The intended audience is "https://saml-sp.example.net", which is an SAML Service Provider. The authorization service identifies itself to the SAML Service Provider.

The assertion is sent as part of an access token request to the authorization server.

The specification contains an assertion as example.

5. Interoperability Considerations

Very similar to the RFC 7521.

6. Security Considerations

Same security considerations as the applicable to the RFC 6749, RFC 7521 and SAML 2.0.

7. Privacy Considerations

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

8. IANA

Registers the values grant-type:saml2-bearer and client-assertion-type:saml2-bearer .