SAML 2.0 Bearer Assertion Profile for OAuth 2.0
Introduction
This blog provides an overview of using SAML (Security Assertion Markup Language) assertion as means for requesting an OAuth 2.0 access token. Here, Ping Federate acts as an OAuth 2.0 Authorization Server accepting the user authentication and authorization details from the client application as a SAML assertion, validates it and issues an OAuth 2.0 access token, which the client application can then use to access the user’s protected resource.
OAuth 2.0 is the widely used open standard for authorization. It allows users to share their private resources stored on one site with another site without having to hand out their credentials, typically supplying username and password tokens instead. Each token grants access to a specific site for specific resources and for a defined duration. This allows a user to grant a third party site access to their information stored with another service provider, without sharing their access permissions or the full extent of their data.
Security Assertion Markup Language (SAML) 2.0 is an XML-based framework that allows identity and access information to be shared across security domains, in particular between an Identity Provider (IdP) and a Service Provider (SP). The SAML specification primarily targeted at providing cross domain Web browser single sign-on is also designed to be modular and extensible to facilitate use in other contexts. The Assertion, an XML security token, is a fundamental construct of SAML. It is generally issued by an identity provider and consumed by a service provider who relies on its content to identify the Assertion’s subject for security related purposes.
OAuth 2.0 provides a method for making authenticated HTTP requests to a resource using an access token. Access tokens are issued to third-party clients by an authorization server (AS) with the (sometimes implicit) approval of the resource owner. OAuth defines multiple profiles for obtaining access tokens to support a wide range of client types and user experiences. The OAuth 2.0 Assertion Profile (http://tools.ietf.org/html/draft-ietf-oauth-assertions-01) provides a general framework for the use of assertions as client credentials and/or authorization grants with OAuth 2.0. The OAuth 2.0 specification profiles the OAuth 2.0 Assertion Profile to define an extension grant type that uses a SAML 2.0 Bearer Assertion to request an OAuth 2.0 access token as well as for use as client credentials.
Ping Federate has support for the OAuth SAML2.0 Bearer Assertion profile which allows the exchange of a valid SAML assertion (as authorization grants) with the Ping Federate OAuth authorization server (AS) for an OAuth access token. Once a resource owner has authenticated himself at Ping Federate IdP or other trusted IdP, Ping Federate can act as a STS (Secure Token Service) service issuing a SAML token on behalf of the user, which the client application can then use it to exchange for an OAuth 2.0 Access Token at the Ping Federate OAuth token end point.
Use Case
Enterprises secure their REST based APIs using the OAuth 2.0 Assertion profile. The following use case shows how the SAML2.0 Bearer Assertion profile is used to protect and grant users/applications access to these REST based APIs:
- Token exchange
This use case displays how OAuth style REST API authentication can be enabled by an existing trust relationship and SAML-based SSO infrastructure between an enterprise and a SaaS provider. An enterprise has implemented SAML SSO to the SaaS provider – allowing its employees to access browser-based resources and applications hosted by the SaaS provider. But new use cases require the enterprise to be able to call a SaaS provider hosted API to retrieve employee-specific data, e.g. for a CRM Cloud provider, sales data for a particular sales representative.OAuth can be used to secure the REST API calls from enterprise to the Cloud, and the fact that the enterprise and the SaaS provider already have SAML SSO working between themselves can facilitate this REST API access. This scenario is shown in the diagram below:
Flow of SAML assertion for OAuth 2.0:
- The enterprise creates a SAML assertion for the particular sales employee as it would normally do for SAML SSO, but instead of delivering the SAML Assertion to the SaaS provider through the browser, uses the Ping Federate OAuth assertion flow to trade the SAML assertion at the SaaS AS (Ping Federate) for the desired access token (Steps 1 & 2).
- Once armed with the access token, the enterprise client includes it on subsequent API calls to the SaaS provider Resource Server (RS). As it was issued based on the named employee within the SAML assertion, the access token indirectly specifies that employee, and so allows the SaaS provider to respond with employee-specific CRM data. The named subject within the SAML assertion identifies the particular employee in question, and the enterprise signature over that assertion serves to demonstrate that the client ‘belongs’ to the enterprise and is implicitly authorized by the enterprise to request access tokens of the AS.
For the sake of simplicity, we don’t show in the above a likely interaction between the OAuth client and a local Security Token Service to obtain the SAML assertion before trading it to the SaaS AS in Step 1. This interaction could be WS-Trust, or conceivably a future profile of OAuth’s own STS.
Using SAML Assertions as Authorization Grants
Once a SAML token has been issued to the client application either by Ping Federate as IdP or other trusted IdP, the following parameter values and encodings need to be passed to the Ping Federate OAuth token endpoint to exchange SAML token for an Access Token:
- The value of “grant_type” parameter MUST be “urn:ietf:params:oauth:grant-type:saml2-bearer”
- The value of the “assertion” parameter MUST contain a single SAML 2.0 Assertion. The SAML Assertion XML data MUST be encoded using base64url, where the encoding adheres to the definition in Section 5 of RFC4648 [RFC4648] and where the padding bits are set to zero. To avoid the need for subsequent encoding steps (by “application/x-www-form-urlencoded” [W3C.REC-html401-19991224], for example), the base64url encoded data SHOULD NOT be line wrapped and pad characters (“=”) SHOULD NOT be included.
Ping Federate as OAuth Service and STS Service:
The following diagram shows how Ping Federate can be used be used to exchange SAML 2.0 Bearer Tokens for Access Token. Here another Ping Federate instance is used to create a valid SAML 2.0 Bearer assertion with a WS-Trust Request.
Flow of SAML assertion for OAuth 2.0:
- The client application makes a WS-Trust request to the IdP with the username token provided by the user and “urn:ietf:params:oauth:grant-type:saml2-bearer” token type.
- Here, Ping Federate acting as an IdP authenticates the user and acting as a STS service issues an OAuth SAML 2.0 bearer assertion. An existing IdP server within the enterprise can be leveraged and integrated with the Ping Federate OAuth 2.0 Authorization Server to provide the authentication and authorization services.
- The client application uses this SAML assertion and exchanges it with the OAuth Authorization server (AS) token end point with the “urn:ietf:params:oauth:grant-type:saml2-bearer” grant type. Here another instance of Ping acts an AS which has been configured to protect the Resource Server APIs.
- After validating the SAML assertion provided by the client application, the AS issues an OAuth 2.0 Access Token.
- The client application then uses this Access Token on every API request it makes to the Resource Server.
