Skip to content

Set Up SAML2 Bearer Assertion Profile

This page guides you through using the SAML2 Bearer grant to exchange a SAML2 assertion for a valid OAuth access token.

Create a service provider

To register your application as a service provider in the MWARE IAM:

  1. Log in to the MWARE IAM Management Console using administrator credentials.

  2. Go to Main > Identity > Service Providers > Add.

  3. Enter a Service Provider Name. Optionally, enter a Description.

  4. Click Register.

Basic OAuth/OpenID Connect configuration

Make the following changes to the created service provider.

  1. Expand Inbound Authentication Configuration > OAuth/OpenID Connect Configuration and click Configure.

  2. Enter the Callback Url.


    The Callback Url is the exact location in the service provider's application to which an access token will be sent. This URL should be the URL of the page that the user is redirected to after successful authentication.

  3. Click Add. Note the OAuth Client Key and OAuth Client Secret that appear.


  • Make sure the SAML2 grant is enabled under Allowed Grant Types when configuring OAuth/OpenID Connect.

  • You can provide any valid URL as the Callback Url. This URL value is not used for any other operations during this sample.


To configure more advanced configurations, see OAuth/OpenID Connect Configurations.

SAML2 Web SSO configuration

  1. In the Inbound Authentication Configuration section of the previously created service provider, click Configure under the SAML2 Web SSO Configuration section.

    1. Now set the configurations as follows:

      1. Issuer:

      2. Assertion Consumer URL: http://wso2is.local:8080/
        Click Yes, in the message that appears.

    2. Select the following check-boxes:

      1. Enable Response Signing

      2. Enable Single Logout

      3. Enable Attribute Profile

      4. Include Attributes in the Response Always

      5. Enable Signature Validation in Authentication Requests and Logout Requests

    3. Select the following check-boxes and enter the following values:

      1. Enable Audience Restriction
        • Audience: https://localhost:9443/oauth2/token
      2. Enable Recipient Validation
        • Recipient: https://localhost:9443/oauth2/token



    For more information on other advanced configurations refer, Advanced SAML Configurations

  2. Click Register to save the changes.

Exchange SAML assertion for an OAuth access token

  1. Use the following curl command to exchange the SAML assertion for an OAuth access token.

    Request Format

    curl -k -d "grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer&assertion=<base64-URL_encoded_assertion>&scope=<scope>" -H "Authorization: Basic <base64_encoded_clientid:clientsecret>" -H "Content-Type: application/x-www-form-urlencoded" https://<host>:<port>/oauth2/token

    Sample Request

    curl -k -d "grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer&assertion=PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZczpUcmFuc2Zvcm1zPgo8ZHM6VHJhbnNmb3JtIEFsZ29yaXRobT0iaHR0cDovL3d3zOlRyYW5zZm9ybXMaW&scope=PRODUCTION" -H "Authorization: Basic TGZkcWt3eVNGVVNZVjNtUkNNaE5vNmw1cWZJYTpOb0JQZjZkZGhxS2pXdEpNWHVibU04bndqNW9h" -H "Content-Type: application/x-www-form-urlencoded" https://localhost:9443/oauth2/token

  2. Use the introspection endpoint of MWARE IAM to get the token information.

    Request Format

    curl -k -u <username>:<password> -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=<access token>' https://<IS_HOST>:<IS_PORT>/oauth2/introspect

    Sample Request

    curl -k -u admin:admin -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=f3116b04-924f-3f1a-b323-4f0988b94f9f' https://localhost:9443/oauth2/introspect

Try it

Set up the sample application


  • Download Apache Tomcat 8.x and install it. Tomcat server installation location will later be referred to as <TOMCAT_HOME> in this guide.

  • It is recommended that you use a hostname that is not localhost to avoid browser errors. Modify your machine's /etc/hosts entry to reflect this.


    Note that wso2is.local is used in this documentation as an example, but you must modify this when configuring the authenticators or connectors with this sample application.

    • Download the file from the latest release assets.

Deploy the sample

Deploy this sample web app on a web container.

  1. Copy the into the webapps folder. For example, <TOMCAT_HOME>/apache-tomcat-<version>/webapps

  2. Open a terminal window and add the following entry to the /etc/hosts file of your machine to configure the hostname.   wso2is.local

    Why is this step needed?

    Some browsers do not allow you to create cookies for a naked hostname, such as localhost. Cookies are required when working with SSO . Therefore, to ensure that the SSO capabilities work as expected in this tutorial, you need to configure the etc/host file as explained in this step.

    The etc/host file is a read-only file. Therefore, you won't be able to edit it by opening the file via a text editor. Instead, edit the file using the terminal commands.
    For example, use the following command if you are working on a Mac/Linux environment.

    sudo nano /etc/hosts
  3. Open the file found in the <TOMCAT_HOME>/webapps/ directory and configure the following property with the hostname ( wso2is.local ) that you configured above.

    #The URL of the SAML 2.0 Assertion Consumer
  4. Restart the Tomcat server.

To check the sample application, navigate to http://<TOMCAT_HOST>:<TOMCAT_PORT>/ on your browser.

For example, http://wso2is.local:8080/


If you wish to change properties like the issuer ID, consumer URL, and IdP URL, you can edit the file found in the directory. Also if the service provider is configured in a tenant you can use "QueryParams" property to send the tenant domain. For example, "".

This sample uses the following default values.

Properties Description A unique identifier for this SAML 2.0 Service Provider application
SAML2.AssertionConsumerURL= http://wso2is.local:8080/ The URL of the SAML 2.0 Assertion Consumer
SAML2.IdPURL= https://localhost:9443/samlsso The URL of the SAML 2.0 Identity Provider
SAML2.IsPassiveAuthn=true Set this to send SAML2 passive authentication requests

If you edit the file, restart the Apache Tomcat server for the changes to take effect.

CORS configuration

SAML2 POST Binding requires CORS configurations to be set up.

Before configuring the service provider, add the following configurations to the deployment.toml file found in <IS_HOME>/repository/conf/. Adding this configuration allows HTTP POST requests.

``` toml
allow_generic_http_requests = true
allow_any_origin = false
allowed_origins = [
allow_subdomains = false
supported_methods = [
support_any_header = true
supported_headers = []
exposed_headers = []
supports_credentials = true
max_age = 3600
tag_requests = false

Enable SAML2 grant in the sample

  1. Open the file found in the <TOMCAT_HOME>/webapps/ folder.

  2. Edit the following configurations.

    Enter the client ID and client secret you received when registering the OAuth/OpenID Connect application.

    OAuth2.ClientId= (enter the client ID received at the application registration)
    OAuth2.ClientSecret= (enter the client secret received at the application registration)
  3. Restart the Tomcat server to apply the changes.

Log in with SAML

  1. Start the Tomcat server and access the following URL on your browser: http://wso2is.local:8080/

  2. Click Click here to login with SAML from Identity Server (Post binding or Redirect Binding)

    You are redirected to MWARE IAM for authentication.

  3. Enter the username and password and click Continue.


  4. Click Request OAuth2 Access Token to receive the access token.


    You will receive an access token as shown below.


  5. Use the introspection endpoint of MWARE IAM to get the token information.


    Request Format

    curl -k -u <username>:<password> -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=<access token>' https://<IS_HOST>:<IS_PORT>/oauth2/introspect

    Sample Request

    curl -k -u admin:admin -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=f3116b04-924f-3f1a-b323-4f0988b94f9f' https://localhost:9443/oauth2/introspect


  6. Since the Travelocity application has now exchanged the SAML assertion for a valid OAuth access token, you can use the received access token to access a protected resource in MWARE IAM.

    Use the SCIM User Endpoint which is secured with OAuth to retrieve users.


    Request Format

    curl -v -k --header "Authorization: Bearer <access token>" https://<IS_HOST>:<IS_PORT>/wso2/scim/Users

    Sample Request

    curl -v -k --header "Authorization: Bearer 865c60a5-969b-36b4-95e2-721a1fb5c867" https://localhost:9443/wso2/scim/Users