Configure an external Identity Provider for Single Sign-On in a WSO2 API Management deployment
WSO2 API Manager is a complete solution which enables users to design and publish APIs, manage a developer community, secure and route API traffic in a scalable way. WSO2 Identity Server is an identity and entitlement management solution which 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 which uses WSO2 Identity Server for identity and access management.
- Why do we need to configure external identity providers?
- How does WSO2 allow authentication using an external identity provider to a deployment?
- Step by step guide on configuring an external IdP taking ADFS as an example
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 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 it in the context of WSO2 API Cloud. This is also applicable to a deployment with WSO2 API Manager and Identity Server.
Step by step guide on configuring an external IdP — AD FS
AD FS (Active Directory Federation Services) is a component developed by Microsoft that provide users with single sign-on access to systems and applications located across organizations. In this section, I will provide the guidelines that need to be followed in order to setup AD FS as the external identity provider for your organization in WSO2 API Cloud.
Following 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.
Export token signing certificates from ADFS. 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 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 relying party manually.
- Provide any display name.
- Choose 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 follows. https://identity.cloud.wso2.com/commonauth
- If you enable support for WS-Federation, specify the URL as follows. https://identity.cloud.wso2.com/commonauth
- Specify Relying party trust identifier as adfs-cloud. The value you enter here should be entered in Identity cloud IdP settings to refer to this IdP.
- When choosing issuance authorization rule, permit all users to access this relying party.
Add Claim Rules
We also 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 username or send the email address as an attribute in the authentication response. ADFS has an attribute name User-principle-name which 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 User-principle-name(this includes the domain name) to email address claim.
You need to transform the email claim to NameID claim and this can be done by using the “Transform an incoming claim” rule template. Select email address as incoming claim type and Name ID as 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 properties for the Relying Party Trust we just created and 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 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 ADFS as an external identity provider at Identity Cloud
I will be considering a scenario where AD FS relying party is configured to use SAML 2.0 protocol. In order to configure WSO2 Identity Cloud to handle requests from AD FS, we need to follow the below 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 the documentation [2] for the details.
- Login to management console of Identity Server in cloud and create an IdP for ADFS
- Upload the public certificate from ADFS as Identity Provider Public Certificate.
- Add claim configurations as follows.
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 follows.
Let’s map the ‘agent’ role from IdP to the ‘internal/publisher’ role as an example. Perform the mapping for each of the roles from IdP to relevant internal roles.
- Configure SAML2 Web SSO Configuration
Identity Provider Entity Id:
- This can be found in FederationMetadata.xml under entityID 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 same as what’s given in AD FS Relying Party configuration as trust identifier. Eg: adfs-cloud
SSO URL:
- This should be in the form http://<AD_FS_service>/adfs/ls
Enable logout
Logout URL: This should be in the form http://<AD_FS_service>/adfs/ls
Enable Logout Request Signing and include 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.
I have considered API publisher for example.
- Configure SAML Web SSO under Inbound Authentication configuration section.
- Make sure to specify the Issuer name as the same global issuer for Publisher App.
- Enable Response signing, Single logout, attribute profile and include attributes in Response
- Configure Local & Outbound Authentication Configuration section.
- Select the Authentication type as Federated Authentication and choose the defined external IdP.
- Make sure to select Use tenant domain in local subject identifier and Use user store domain in 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 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 to the user.
[2] https://docs.wso2.com/display/IS530/Configuring+a+JDBC+User+Store
