This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

SAML2 Bearer Assertion Profile for OAuth 2.0

Owned by Former user (Deleted)
Last updated: Aug 21, 2014
3 min read

One of the very first complements to the OAuth 2.0 specification is the SAML2 Bearer Assertion Profile for OAuth 2.0. This page talks about the following two scenarios for the SAML2.0 Assertion.

  • Using SAML2.0 assertions as authorization grants
  • Using SAML2.0 assertions for client authentication

Among the above two scenarios, the former is the one that is more commonly needed in enterprises. The WSO2 Identity Server supports this process.

WSO2 Identity Server as an OAuth 2.0 Authorization Server can accept SAML2 Assertions from OAuth 2.0 clients as means of resource owner authentication and authorization. Additionally, it can exchange it with OAuth 2.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 OAuth 2.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 OAuth 2.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 OAuth 2.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 SAML 2.0 token to the authorization server and exchanging it directly to an OAuth 2.0 access token.

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 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.

  3. Start and log in to the WSO2 Identity Server and access the management console.
  4. Register a new Trusted Identity Provider. 
    1. To do this, go to Configure > Trusted Identity Providers. 
    2. Click on ‘Add New Trusted Identity Provider’. 
    3. Enter a unique identifier for this Trusted Identity Provider across the tenant. 

    4. Enter the Issuer value used to generate the SAML2 assertion into the 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.

    5. Upload the corresponding public certificate of the private key used to sign the SAML2 Assertion.
  5. Create a new OAuth2.0 application under Main -> Manage -> OAuth.

  6. Execute the following HTTP request using an HTTP client such as cURL or Advanced Rest Client in Google Chrome. The cURL command is as follows:

    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
  7. 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 output value of 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.