WSO2 API Manager 3.2.0 with WSO2 Identity Server 5.10.0 — SSO + User Self Registration

Hello Geeks!!! 😊😊😊

Today, I’ll explain how to integrate WSO2 Identity Server 5.10.0 as IDP with WSO2 API Manager 3.2.0 for SSO and how to work with user self-registration flow.

As you know, WSO2 API Manager is the world’s leading open-source, enterprise-grade API management platform for on-premises, cloud, and hybrid architectures.

WSO2 Identity Server is an API-driven open source Identity Access Management product designed to help build effective CIAM solutions.

OK. Let’s start with the use case.😇😇😇

If you need to configure the WSO2 Identity Server as IDP with WSO2 API Manager for SSO without sharing user stores and if you need to enable user self-registration flow, how to achieve both use cases?

Eg: If you need to enable the user self-registration flow for the dev portal and the API Manager is configured with the Identity Server as IDP, How to assign the relevant role permissions to the user if user stores are not shared?

Sounds like a common use case. Let’s understand the flow of the user registration and the problem that we will face.

When the user is registering through the self-sign-up flow from the API Manager, the user is registering in the Identity Server and federate the user from Identity Server to the API Manager when logging into the system.

When a user is trying to access the dev portal of the API Manager, that user needs to have Internal/subscriber permission to achieve it. But if the user store is not shared with the API Manager and the Identity Server, the Internal/subscriber role does not include in the Identity Server.

Then, how to accomplish this??? 🤔🤔🤔

OK, Let’s understand the self-registration flow only with the API Manager.

When a user is doing a self-registration process when accessing the dev portal, the user is getting created in the user store with the Internal/subscriber role. When the self-registration request comes to the API Manager, that will go through the UserPostSelfRegistrationHandler [1] and assign the Internal/subscriber role to the user to grant the access permission to the dev portal.

But when comes to the use case with the Identity Server, the Internal/subscriber role is not included in the Identity Server. Hence, the UserPostSelfRegistrationHandler is not in the Identity Server. Therefore, we have to create a custom user role and implement a custom handler to achieve this requirement.

OK. Let’s implement it like a boss. 😎😎😎

  • Check out the source code of the custom user self-registration handler from the repository [2]
  • Execute the following command from the root directory of the project to generate the JAR artifact.
  • After building the project, copy the built JAR artifact from <PROJECT_HOME>/target directory and place it inside the <IS_HOME>/repository/components/dropins directory.

Now you have placed the custom registration handler. Let’s engage that with the Identity Server. 😀😀😀

  • Open the deployment.toml file inside the <IS_HOME>/repository/conf directory.
  • Add the below configurations to engage the custom UserPostSelfRegistrationHandler that we implemented previously.

🚩 When the user has created an account, an activation email will send to the provided email address to activate the user account. If you did not enable email configurations in the Identity Server, you can simply add the below configurations to the deployment.toml file. (Please refer to the documentation [3] for more information about the below configuration)

  • Start the Identity Server. In this case, I will use an offset value to start the server in a different port. (port: 9444)
  • Go to the carbon management console. (https://<IS_HOSTNAME>:<IS_PORT>/carbon)
  • Now we need to create a service provider. For that, click on the Add button under the Service Providers section.
  • Give a name to the service provider and click on the Register.
  • On the next page, In a multi-tenanted environment, for all tenants to be able to sign in to the APIM Web applications, you can simply enable the SaaS Application option.
  • Expand the Claim Configuration section and add the role claim as a Mandatory Claim to parse the role in the SAML response when doing the dev portal authentication.
  • Expand the Inbound Authentication Configuration section, expand SAML2 Web SSO Configuration, and then click on the Configure.
  • On the next page, you can configure the Issuer, Assertion Consumer URL by providing the Application Consumer URL of the application.
  • Select the following options.
  1. Enable Response Signing
  2. Enable Signature Validation in Authentication Requests and Logout Request
  3. Enable Single Logout
  4. Enable Attribute Profile
  5. Include Attributes in the Response Always
  • To enable tenant-specific SSO with IS 5.10.0 for the API Publisher and Developer Portal, you can follow the below sub-steps.
  1. Expand the Local & Outbound Authentication Configuration section.
  2. Select Use tenant domain in local subject identifier option.
  • Finally, you can click on the Register button to apply the configuration to the registered service provider.

For more information about the configuration in the Identity Server for SSO, please refer to the documentation [4]

Now, let’s create the TEST user role on the Identity Server side.

  • Click on the Add button under the Users and Roles section.
  • Provide the name of the role and click on the Finish button.

OK. Now, let’s enable the self-registration flow in the Identity Server.

  • Click on the Resident button under the Identity Providers section.
  • Expand the Account Management Policies and expand the User Self Registration section.
  • Add a tick to Enable Self User Registration option and click on the Update button.

Now, let’s move to the API Manager side to configure an Identity Provider to link the Identity Server. 😀😀😀

  • Start the API Manager server.
  • Go to the carbon management console. (https://<APIM_HOST>:<APIM_PORT>/carbon)
  • Click on the Add button under the Identity Providers section.
  • Upload the public certificate of the Identity Server. (The public certificate needs to be in PEM format)
  • Since we have to enable access for the user to the dev portal, we have to bind the Internal/subscriber role to the federated user. Hence, we have to configure a role map. For that, expand the Role Configuration section.
  • Click on the Add Role Mapping and provide the Identity Provider Role and the Local Role as below image.
  • Expand the Federated Authenticators and expand the SAML2 Web SSO Configuration section.
  • Put a tick to Enable SAML2 Web SSO option.
  • Provide the Issuer of the service provider that you have configured in the Identity Server side to the Service Provider Entity ID field.
  • Add the Identity Provider’s entity identifier value to the Identity Provider Entity ID field.
  • For the SSO URL, you can provide the SAML SSO URL of the Identity Server.
  • Select the following options.
  1. Enable Authentication Request Signing
  2. Enable Authentication Response Signing
  3. Enable Logout Request Signing
  4. Single Logout Profile
  • Select HTTP-POST as the HTTP Binding.
  • Expand the Just-in-Time Provisioning section and select Always provision to User Store Domain with Provision silently option as below to federate the user from Identity Server to the API Manager.
  • Now click on the Register button.

For more information about the configuration in the API Manager for SSO, please refer to the documentation [5]

Now you have configured the WSO2 Identity Server as an IDP for the WSO2 API Manager successfully. Let’s configure the service provider of the dev portal to redirect the login request to the Identity Server. 😀😀😀

  • Click on the List button under the Service Providers section.
  • Click on the Edit button of the apim_devportal service provider. (apim_devportal service provider will appear if you have logged into the dev portal previously.)
  • Expand the Local & Outbound Authentication Configuration section.
  • Select the Federated Authentication option and select the configured Identity Provider.
  • Put a tick to Assert identity using mapped local subject identifier section. This is a mandatory step to authorize scopes for provisioned federated users.

For more information about the configuration of the service provider to enable SSO with Identity Server, please refer to the documentation [6]

Now you have successfully configured the WSO2 Identity Server as an IDP for the WSO2 API Manager and all the user authorizations in the dev portal will navigate to the Identity Server. 😀😀😀

Let’s test the solution. 🤓🤓🤓

  • Go to the dev portal. (https://<APIM_HOST>:<APIM_PORT>/devportal)
  • Click on the Sign In button in the right top corner of the web page.
  • Now you will redirect to the login page and that is prompting from the Identity Server.
  • Click on the Create Account button.
  • You can enter the username on the next page and click on the Proceed to Self Registration button.
  • On the next page, you can fill in all the profile details. Please make sure to add a valid email address since you have to activate the account via email.
  • After registering, you will see a below popup message.
  • Meantime, you will receive an account activation email to the provided email address.
  • Meantime, you will see the user getting created in the Identity Server with the TEST user role and the Internal/selfsignup user role.
  • After activating the user account, you will able to log into the dev portal by providing the user credentials. When logging into the dev portal, you will see the API Manager is requesting the role claim. (This needs to do the role mapping when federating the user from Identity Server)
  • After logging into the dev portal, you will able to see the federated user with the Internal/subscriber user role as below.

Hence, our solution is working as expected. 😁😁😁

Congratulations!!! Now you have successfully enabled SSO and self-sign-up flow with WSO2 API Manager 3.2.0 and WSO2 Identity Server 5.10.0 without sharing user stores between them 😎😎😎

🚩 You can use the same solution for the use case if the user stores have been shared between WSO2 API Manager and WSO2 Identity Server. In that case, you can ignore the Just-in-Time provisioning configurations in the API Manager, Role Mapping configurations in the Identity Server and you don’t need to create an additional user role to map with the Internal/subscriber. (Meantime, you can customize the custom self-registration handler code by assigning the Internal/subscriber user role to the user directly.)

Happy Stacking!!! 😁😁😁

[1] https://github.com/wso2/carbon-apimgt/blob/master/components/apimgt/org.wso2.carbon.apimgt.impl/src/main/java/org/wso2/carbon/apimgt/impl/handlers/UserPostSelfRegistrationHandler.java

[2] https://github.com/Sumudu-Sahan/is-apim-selfsignup-handler

[3] https://is.docs.wso2.com/en/5.10.0/setup/configuring-email-sending/

[4] https://apim.docs.wso2.com/en/3.2.0/develop/extending-api-manager/saml2-sso/configuring-identity-server-as-idp-for-sso/#configuring-wso2-api-manager-as-service-provider-for-identity-server

[5] https://apim.docs.wso2.com/en/3.2.0/develop/extending-api-manager/saml2-sso/configuring-identity-server-as-idp-for-sso/#configuring-wso2-identity-server-as-a-saml-20-sso-identity-provider

[6] https://apim.docs.wso2.com/en/3.2.0/develop/extending-api-manager/saml2-sso/configuring-identity-server-as-idp-for-sso/#configuring-wso2-api-manager-apps-as-saml-20-sso-service-providers

Software Engineer @ WSO2 | WSO2 Certified API Manager Expert | BIT(UCSC) | DiHN | OCPJP | Student Member of CSSL