Configure an External Identity Provider for Single Sign-On in a WSO2 API Deployment

DZone 's Guide to

Configure an External Identity Provider for Single Sign-On in a WSO2 API Deployment

Want to learn more about WSO2 API Management? This post explores how to configure an external Identity Provider for a single sign-on.

· Security Zone ·
Free Resource

WSO2 API Manager is a complete solution that enables users to design and publish APIs, manage a developer community, and secure and route API traffic in a scalable way.

WSO2 Identity Server is an identity and entitlement management solution that provides security by managing multiple identities across different applications.

In this article, I will be walking you through the following areas in the context of WSO2 API Cloud, a WSO2 API Management solution that uses the WSO2 Identity Server for identity and access management.

Why Do We Need to Configure External Identity Providers?

If you already have an Identity Provider (IdP) used in your organization, it’s easy to plug that IdP to WSO2 API management deployment rather than migrating all the user identities to the WSO2 Identity Server. Moreover, this removes the overhead on users to memorize different credentials for each application used within the organization.

How Does WSO2 Authenticate Using an External Identity Provider to a Deployment?


You can refer the documentation[1] for the details of the authentication flow with an external IdP. The document [1] explains the context of the WSO2 API Cloud. This is also applicable to a deployment with WSO2 API Manager and Identity Server.

Step-by-Step Guide to Configuring an External Identity Provider — AD FS

AD FS (Active Directory Federation Services) is a component developed by Microsoft that provides users with single sign-on access to systems and applications located across organizations. In this section, I will provide the guidelines to set up AD FS as the external identity provider for an organization in WSO2 API Cloud. This is applicable to an on-premises deployment as well.

Below are the three main steps to complete the configuration:

  • Export certificates from AD FS and WSO2 API Cloud.
  • Configure WSO2 as a relying party at AD FS.
  • Configure AD FS as an external identity provider at Identity Cloud.

Export Certificates From AD FS and WSO2 API Cloud

Here are some export token signing certificates from AD FS. Select the export file format as Base-64 encoded X.509.

Export tenant’s public certificate from Identity Cloud management console.

Configure WSO2 as a Relying Party

In order for WSO2 to communicate with ADFS, you need to specify WSO2 as a relying party at the AD FS Management Console. Go through the Add Relying Party Trust Wizard, completing each step according to the below guidelines.

  • Select to enter the data about the relying party manually.
  • Provide any display name.
  • Choose an AD FS configuration Profile.
  • Skip the next step as we are not using an encryption certificate.
  • ADFS supports SAML 2.0 Web SSO and WS-Federation Passive protocol for relying parties.
    •  If you enable support for SAML 2.0, specify the URL as https://identity.cloud.wso2.com/commonauth.

    • If you enable support for WS-Federation, specify the URL as https://identity.cloud.wso2.com/commonauth

  • Specify your relying party trust identifier as AD FS-cloud. The value you enter here should be entered in Identity Cloud IdP settings to refer to this IdP.
  • When choosing an issuance authorization rule, you need to permit all users to access this relying party.

Add Claim Rules

We need to add claim rules to pass relevant information to WSO2 during authentication and authorization.

WSO2 cloud uses email as the username, and, therefore, IDPs should support email usernames or send the email address as an attribute in the authentication response. AD FS has an attribute name, User-principle-name, that can be used as an email attribute. In order to set that attribute, select the rule template “Send LDAP attributes as claims," select Active Directory as the Attribute store, and map the User-principle-name (this includes the domain name) to your email address claim.

You need to transform the email claim to NameID claim. This can be done by using the “Transform an incoming claim” rule template. Select email address as the incoming claim type and Name ID as the outgoing claim type for this rule.

Then, another rule, “send group membership as a claim,” is required to map the group memberships in AD FS to specific roles at the API deployment. At WSO2 Identity server, this role can be mapped to an internal role to allow/restrict users to specific applications based on role.

Configure Signature and Endpoint Properties

Open the properties for the relying party trust that we just created. Let’s add some further properties that are required for the authentication.

Select the Signature tab and add the public certificate of your tenant domain exported in a previous step to verify the requests from Identity Cloud to ADFS.

If you are using a SAML 2.0 Web SSO protocol for the relying party, you have to configure the SAML logout endpoint as follows:

Binding: POST

Trusted URL: https://<ADFS_SERVICE_URL>/adfs/ls

Response URL: https://identity.cloud.wso2.com/commonauth

Configuring AD FS as an External Identity Provider at Identity Cloud

I will be considering a scenario where the AD FS relying party is configured to use SAML 2.0 protocol. In order to configure the WSO2 Identity Cloud to handle requests from AD FS, we need to follow the following steps. If you are using WSO2 API Cloud, these configurations will be done by the WSO2 Cloud support team.

  • Add a secondary JDBC userstore. You can refer to the documentation [2] for the details.
  • Log in to the management console of Identity Server in the cloud as the tenant admin user and create an IdP for AD FS
  • Upload the public certificate from ADFS as the Identity Provider Public Certificate.

  • Add the claim configurations show below:

Map the claim “http://schemas.microsoft.com/ws/2008/06/identity/claims/role” to the local role claim and select it as Role claim URI.

  • Add role mapping as shown below:

As an example, let’s map the ‘agent’ role from IdP to the ‘internal/publisher’ role. Next, perform the mapping for each of the roles from IdP to relevant internal roles.

  • Configure the SAML2 Web SSO Configuration

Identity Provider Entity ID:

This can be found in FederationMetadata.xml under the Entity ID attribute. The FederationMetadata.xml can be accessed using https://<AD_FS_server>/FederationMetadata/2007-06 /FederationMetadata.xml.

The Entity ID is usually in the form http://<AD_FS_service>/adfs/services/trust

Service Provider Entity ID:

This should be the same as what’s given in the AD FS, relaying party configuration as a trust identifier, e.g. adfs-cloud.


This should be in the form http://<AD_FS_service>/adfs/ls.

  • Enable logout and specify the logout URL as "Logout URL." This should be in the form http://<AD_FS_service>/adfs/ls."

  • Enable Logout Request Signing and include the Public certificate in the request. Select HTTP Binding as HTTP-POST.

  • Configure "Just-in-time" provisioning to the created secondary user store:

  • Create Service Provider for API cloud application. In this configuration, I have considered the API publisher, for example. Next, configure SAML Web SSO under the Inbound Authentication configuration section.
    • Make sure to specify the Issuer name as the same global issuer for Publisher Application.

    • Enable Response Signing, Single Logout, Attribute Profile, and Include Attributes in the Response

  • Configure the Local and Outbound Authentication Configuration section.
    • Select the Authentication type as Federated Authentication and choose the defined external IdP.

    • Make sure to select the Use tenant domain in the local subject identifier and Use user store domain in the local subject identifier.

Once all the above configurations are done, you can start using AD FS as the external identity provider for applications in API Cloud.

According to the discussed example, when you visit the API Publisher application in WSO2 API Cloud, you will be redirected to AD FS and prompted for login details. When submitted, the authentication will be done at AD FS and the relevant claims will be sent to WSO2 Identity Cloud. Then, Identity Cloud will allow access to the API Publisher application for the user.

identity access management ,api management ,api cloud ,wso2 ,wso2 api manager ,wso2 identity server ,saml 2.0 ,security

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}