[Article] Use Cases: Utilizing SAML with WSO2 API Manager

  • By Nadeesha Gamage
  • 8 Mar, 2017

SAML 2.0 (referred to as SAML in this article) has been a widely used standard that provides the capability to authenticate, authorize, and federate identity between different entities. SAML is supported by many identity providers today and is considered the de-facto standard for providing single sign-on (SSO) and identity federation.

The capability to integrate with SAML allows an organization to provide a better user experience to its API consumers who consume APIs that are exposed via WSO2 API Manager. WSO2 API Manager supports SAML in multiple scenarios as listed below:

  1. To provide the capability to federate to a SAML identity provider to authenticate and authorize users accessing the APIs in the API manager
  2. To provide the capability for applications to exchange their existing SAML tokens to OAuth 2.0 tokens to invoke APIs secured via the API manager
  3. To provide the capability to integrate with a SAML SSO provider to enable SSO to different web applications used by WSO2 API Manager

This article looks at how WSO2 API Manager facilitates these three use cases and provides references on how to configure each of these scenarios in WSO2 API Manager.

Use case 1: Using SAML for identity federation

WSO2 API Manager provides the capability to integrate with an external user-store in order to authenticate and authorize users. However, in some cases, the API manager would be required to authenticate users that reside in an external identity provider to which they do not have access at a user-store level. In such a case, the API manager has the capability to federate to an external identity server using SAML. SAML federation allows the API manager to federate authentication for API invocations as well as for the API manager user interface access. This use case looks at how WSO2 API Manager authenticates users from a third-party identity provider when making API invocations to the API manager. Federation of access to web user interfaces would be discussed in use case 3.

The ability to authenticate API invocations from a federated identity provider can be done using either SAML or OpenId Connect. Since this article focuses on the capabilities of SAML, we will only explore how this is done using SAML.

An SAML identity federation scenario is depicted in Figure 1:

Figure 1

As illustrated, an application would make a token request to the API manager. The application would use the client ID as the identifier to allow the API manager to identify the application. A grant type is passed with the request that suggests how the user should be authenticated. Based on the grant type, the API manager would federate authentication to the SAML identity provider. The user would then be re-directed to the login page of this identity provider. The user would login to the identity provider and is requested to grant access to the application. Once authenticated and access is granted by the user, the API manager would return an authorization code to the application. The application would pass this authorization code to the API manager and get an access token that can be used for all subsequent requests to access the API. This type of SAML federation works for authorization code and implicit grant types that redirect the client to a login page to enter credentials and grant permission to the application.

Let’s look at how this scenario can be configured. We would be considering WSO2 Identity Server as the Federated SAML identity provider. We would also be running the API manager as an all-in-one node. For this sample, all nodes will run on a single machine with the following port offsets:

WSO2 API Manager - 0

WSO2 Identity Server - 2

Configuring WSO2 API Manager

  1. Let’s login to the API manager node and register the federated SAML identity provider as an identity provider. You can do this by going to the ‘Add’ Identity Provider option as shown below.

    Figure 2

    Include the below configuration

    • Identity Provider Name - FederatedIdP
    • Alias -https://{IP}:9443/oauth2/token

    Then expand the ‘Federated Authenticators’ and select ‘SAML 2 Web SSO Configuration’ and enter the following configuration:

    • Enable SAML 2 Web SSO - Yes
    • >Default - Yes
    • Service Provider Entity ID - wso2km
    • Identity Provider Entity ID FederatedIdP
    • SSO URL - https://{IP}:9445/samlsso/
    • Enable Logout - Yes

    Once the above steps have been completed, register the identity provider.

  2. Let’s now configure the API manager to use this newly created federated identity provider for all applications that would be created from the API Store. This can be done by configuring the file below:


    Edit the configuration in the XML file as given below. As you would have noticed, we have commented the local authenticator configuration provided by default and added ‘FederatedIdP’ as the identity provider.

                    </LocalAuthenticatorConfigs> -->

    Once this has been completed, you would need to restart the API manager server.

Configuring WSO2 Identity Server

Now let’s configure the external SAML identity provider; we will use WSO2 Identity Server as the external identity provider and it’s possible to use any SAML identity provider for this. We will create a service provider in WSO2 Identity Server. This service provider would refer to the API manager node that we configured above. Let's login to the management console of WSO2 Identity Server and register a new service provider. This can be done by going to the ‘Add’ service provider option as shown in Figure 3.

Figure 3

Include the following service provider name:
Service Provider name - wso2km

Then expand the ‘Inbound Authentication Configuration’ and select ‘SAML 2 Web SSO Configuration’ and click on the configure button.

Once inside add the configuration given below:

  • Issuer - wso2km
  • Assertion Consumer URL - https://{ip}t:9443/commonauth
  • Enable Response Signing - Yes
  • Enable Single Logout - Yes

Figure 4

Once the above data has been entered you can register the service provider with the identity server.

Creating the application in WSO2 API Manager

Now you can log in to the API manager and create a new application to subscribe and invoke the API. When creating the application ensure to enable ‘Authorization Code’ and ‘Implicit Grant’ types as shown in Figure 5.

Figure 5

If you don't have an application that has been already created to test this use case you can use the WSO2 OAuth Playground application for testing. Instructions on how to use the OAuth playground application can be found in the following link:

Use case 2: Using SAML token for API invocations

WSO2 API Manager uses OAuth 2.0 tokens to authenticate and authorize API invocations made by an application or a user. The API manager supports multiple OAuth 2.0 grant types that also includes a SAML 2 grant type. SAML 2 grant allows an application to exchange an existing SAML token to an OAuth 2.0 token to invoke an API via API manager. This allows an application that uses SAML SSO infrastructure to seamlessly consume APIs that are exposed via WSO2 API Manager rather than having to login again when accessing the API. The process involves creating a token, and accessing the API can be depicted in Figure 6.

Figure 6

In the scenario illustrated in Figure 6 a user would access a web application that supports SAML. The user would either have a valid SAML token or would be redirected to a login page that would authenticate the user and provide a SAML token. The steps 1-5 in the diagram depicts the SAML token generation process that does not involve WSO2 API Manager. The application can now access an API exposed via WSO2 API Manager. The API manager, in this case, would allow the application to use the SAML token and exchange it with an OAuth 2.0 access token, which the application can use to invoke the API. The API manager maintains a trust relationship with the SAML identity provider. The SAML token provided by the application to the API manager is signed using the private key of the SAML identity provider that allows the API manager to validate the authenticity of the SAML token using the public key of the identity provider. This flow requires both the identity provider and the API manager to be registered with each other prior to API invocation.

Instructions on how to allow applications to use a SAML token to access APIs in the API manager can be found in the following documentation:

Use case 3: SSO to WSO2 user interfaces using SAML SSO

WSO2 API Manager has multiple user interfaces that are used by various users of the API management solution. WSO2 API Manager provides the capability to enable SSO for these user interfaces. SSO can be provided by integrating with an existing SAML SSO provider. Integrating with a SAML SSO provider would allow users to login to WSO2 API Manager user interfaces by using the same session from any other SAML SSO-enabled application without needing to re-login. Similarly, users who need to access multiple user interfaces can move between these interfaces without needing to re-log into each user interface. This scenario has been depicted in Figure 7.

Figure 7

As illustrated here, if the user accesses any of the WSO2 API Manager interfaces, the user will be routed to a common login page of the organization's identity provider. The user can login via this login page and would be allowed to access SAML-enabled applications that are registered as service providers of the identity provider.

Instructions on how to setup SAML SSO for WSO2 API Manager can be found in the following document:


The three use cases discussed in this article looked at how WSO2 API Manager supports SAML in various scenarios. This provides the capability for an organization to offer a seamless user experience to its users when using its applications and consuming APIs exposed by the organization.