SAML2 Bearer Assertion Profile for OAuth 2.0 with WSO2 Identity Server

One of the very first complements to the OAuth2.0 specification is the SAML2 Bearer Assertion Profile for OAuth2.0. This profile talks about two use cases for the SAML2.0 Assertion.

1. Using SAML2.0 assertions as authorization grants

2. Using SAML2.0 assertions for client authentication

Among the above two use cases the former is the one that is more commonly needed in enterprises. The WSO2 Identity Server has had support for this use case from its 4.1.0 release onwards. WSO2 Identity Server as an OAuth2.0 Authorization Server can accept SAML2 Assertions from OAuth2.0 clients as means of resource owner authentication and authorization and exchange it to OAuth2.0 access tokens in order to access protected resources on behalf of the resource owner.

Many existing enterprises that have implemented SOA rely on SAML. In the case of WSO2 Identity Server SAML is used in its Web SSO feature and STS feature. Such enterprises could face a situation where they now need to consume OAuth protected resources through APIs. OAuth and OAuth2.0 in particular are more recent specifications compared to SAML. An enterprise that has already got a working SAML2.0 based SSO infrastructure between itself and the Service Provider (SP) would prefer to use the existing trust relationship between the Identity Provider (IDP) and the Service Provider, even if the OAuth Authorization Server is entirely different from the IDP. Especially if there could be a cut down in the number of steps performed in the OAuth2.0 dance in obtaining an access token due to the fact that the clients have already authenticated themselves to the IDP and the resource owner has authenticated himself and authorized the client, enterprises are going to love it. The SAML2 Bearer Assertion Profile for OAuth2.0 is the answer to the question of how we leverage on the existing trust relationship between the SP and the IDP, by presenting the SAML2.0 token to the authorization server and exchanging it directly to an OAuth2.0 access token.

SAML2.0 Bearer Assertion Profile for OAuth2.0 Enterprise Use Case

SAML2.0 Bearer Assertion Profile for OAuth2.0 Enterprise Use Case

How to try the SAML2.0 Assertion grant type with WSO2 Identity Server

1. Create a SAML2 Assertion. You can use the command line client program from here. Extract the ZIP file, change directory into the extracted folder and execute the following command in the command line.

java -jar SAML2AssertionCreator.jar <saml2_assertion_issuer> <saml2_assertion_subject> <saml2_assertion_recipient> <saml2_asseertion_audience_restriction> <your_JKS_file> <your_JKS_password> <your_certificate_alias> <your_private_key_password>

The first argument to the program is the saml:Issuer value. The second argument is the saml:Subject -> saml:NameId value. The third argument is the value of saml:Subject -> saml:SubjectConfirmation -> saml:SubjectConfirmationData.Recipient. The fourth argument could actually take multiple values separated by commas which are added to the saml:AudienceRestriction element of the token. Each value is added as a saml:Audience element within saml:AudienceRestriction. The fifth argument points to the Java Key Store (JKS) file to be used for signing credentials. The sixth argument is the JKS password. The seventh argument is the alias of the public certificate to be used. The eighth argument is the password of the private key that is used for signing.

2. Download the WSO2 Identity Server from here. Start the WSO2 Identity Server and log in to the management console.

3. Register new Trusted Identity Provider. Go to Configure -> Trusted Identity Providers. Click on ‘Add New Trusted Identity Provider’. Enter a unique identifier for this Trusted Identity Provider across the tenant. Enter the Issuer value used to generate the SAML2 assertion into Trusted Identity Provider Issuer field. (The default Issuer value of the WSO2 Identity Server when acting as an SSO provider is ‘https://localhost:9443/samlsso‘. The default Identity Provider URL is also same as the Issuer value.) Upload the corresponding public certificate of the private key used to sign the SAML2 Assertion.

4. Create a new OAuth2.0 application under Main ->  Manage -> OAuth

5. Execute the following HTTP request using an HTTP client such as cURL or Advanced Rest Client in Google Chrome. I have listed the cURL command here.

curl -X POST -u "QlthIzYUOK5DS0BXW8Cy8uFJjKAa:XFfgPmTbMaQ5eScc0rSnAW9ZIgwa" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -d "grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer&assertion=PHNhbWxwOl...[omitted for brevity]...ZT4" https://localhost:9443/oauth2/token

The -u flag should specify the “<Client Id>:<Client Secret>” value. The assertion parameter should specify the base64url encoded SAML2.0 assertion. Copy and paste the value that was output by the command line client. Make sure you have carefully copied and pasted the exact same value produced by the client; no more no less, since that value can be quite large.

You would have now received the response from the token endpoint. The response would contain the access token, refresh token, expiry time and token type.