Configure tenant-wise portal SSO — WSO2 API Manager
Hello Geeks!!! 😊😊😊 Maybe after a loooong loooong time 🤓
Today, I’ll explain how to configure the SSO for the publisher and devportal for the tenant level in the API Manager.
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.
The WSO2 API Manager 4.x.x versions support the SSO integrations with external identity providers to authenticate the user from that external IDP and gain access to the API Manager portals.
Let’s understand the use case that we are trying to achieve today. 😇😇😇
Let’s assume that you have 10 organizations in the system (Simply, 10 tenant domains). Now you need to integrate different external identity providers to perform the SSO authentication and access the publisher portal and the devportal for each tenant.
Eg: For tenant 1, you need to integrate the WSO2 Identity Server as the external identity provider for the publisher and dev portal. But for tenant 2, you need to integrate Keycloak as the external identity provider for the publisher and devportal.
So, how we can achieve this? 🤔🤔🤔
OK. Let’s do it like a BOSS 😎😎😎
Below are the steps that we need to complete to achieve this. For this use case, I’ll take the WSO2 API Manager 4.2.0 version and the WSO2 Identity Server 6.1.0 version. But you can choose any external IDP to integrate this because the IDP has to send the claim responses after the authentication.
- Configure tenants in the API Manager 4.2.0
- Configure tenant portal URLs in API Manager
- Configure Nginx and /etc/hosts file for custom rules
- Enable service provider creation feature in tenant-wise
- Configure the IS 6.1.0 for SSO
- Getting the groups claim (OIDC flow) and then doing the role mapping
- Enable the JIT provisioning
- Exchange public certificates
Configure tenants in the API Manager 4.2.0
- Download the WSO2 API Manager 4.2.0 distribution through the official link [1]. (By selecting previous releases).
Also if you have a valid WSO2 subscription, then you can download the latest updates to the product by using the update 2.0 channel. For more information, please refer to the documentation [2]
- Open the deployment.toml file under the <APIM_HOME>/repository/conf directory.
- Add the below configuration to the file by pointing to the same API manager node address with the port for OIDC endpoints.
[apim.idp]
server_url = "https://localhost:9443/"
authorize_endpoint = "https://localhost:9443/oauth2/authorize"
oidc_logout_endpoint = "https://localhost:9443/oidc/logout"
oidc_check_session_endpoint = "https://localhost:9443/oidc/checksession"- Start the API Manager.
- Then go to the carbon management console. (Default URL: https://<APIM_HOST>:<APIM_PORT>/carbon)
- Create some tenants by clicking on the Add New Tenant button under the Configure section in the left navigation.
Since I’m going to configure the SSO for 2 tenant domains, I’ll create 2 tenants on the API Manager side named tenant1.com and tenant2.com
After creating those tenants, let’s go with Step 2. 😇
Configure tenant portal URLs in API Manager
Now we are going to create a custom URL for the devportal and publisher portal under the tenant1.com domain. After that, we can access the tenant publisher portal and tenant dev portal through these URLs. (Documentation [3])
- Log into the tenant carbon management console by using the super admin’s credentials.
- Then click on the Browse button under the Resources section on the left navigation menu.
- Navigate to the /_system/governance registry path and create customurl/api-cloud/<tenant-domain>/urlMapping directory structure in the registry. Since I’m going to do this to the tenant1.com domain, the complete registry resource path should be, /_system/governance/customurl/api-cloud/tenant1.com/urlMapping
- Now we need to create text content as a resource. For that, click on the Add Resource button and select Create Text Content as the method.
- For the Name, put tenant1.com (tenant domain that you logged into the system, tenant domain that you wish to do this change)
- For the content, put the below JSON content.
{
"tenantDomain":"tenant1.com",
"store":{
"customUrl":"dptenant1.wso2.com"
},
"publisher":{
"customUrl":"pubtenant1.wso2.com"
}
}The final view of the page should be as below.
- After this, click on the Add button to add this custom URL registry resource.
Configure Nginx and /etc/hosts file for custom rules
- Now we need to add dptenant1.wso2.com and pubtenant1.wso2.com DNS addresses to /etc/hosts mapping with the 127.0.0.1 address since we are going to do the complete setup with the load balancer in a local machine.
After this, we need to configure the load balancer to route these addresses to the tenant1.com’s devportal. For that, we need to write the routing logic under the nginx.conf file.
- Open the nginx.conf file under the Nginx load balancer installation location in your setup.
- Then add the below server block to the file.
server{
listen 443 ssl;
server_name dptenant1.wso2.com;
ssl_certificate <PUBLIC_CERTIFICATE>;
ssl_certificate_key <KEY_FILE>;
location /{
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $http_host;
proxy_read_timeout 5m;
proxy_send_timeout 5m;
proxy_pass https://127.0.0.1:9443/devportal/;
proxy_redirect https://127.0.0.1:9443/devportal/ /;
proxy_set_header X-WSO2-Tenant "tenant1.com";
}
location ~ (/api/am/devportal/v3|/authenticationendpoint|/logincontext|/commonauth|/oidc) {
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $http_host;
proxy_read_timeout 5m;
proxy_send_timeout 5m;
proxy_pass https://127.0.0.1:9443;
proxy_set_header X-WSO2-Tenant "tenant1.com";
}
location ~ (/oauth2) {
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $http_host;
proxy_read_timeout 5m;
proxy_send_timeout 5m;
proxy_pass https://127.0.0.1:9443;
proxy_redirect https://127.0.0.1:9443/ https://dptenant1.wso2.com/;
proxy_set_header X-WSO2-Tenant "tenant1.com";
}
}
server{
listen 443 ssl;
server_name pubtenant1.wso2.com;
ssl_certificate <PUBLIC_CERTIFICATE>;
ssl_certificate_key <KEY_FILE>;
location /{
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $http_host;
proxy_read_timeout 5m;
proxy_send_timeout 5m;
proxy_pass https://127.0.0.1:9443/publisher/;
proxy_redirect https://127.0.0.1:9443/publisher/ /;
proxy_set_header X-WSO2-Tenant "tenant1.com";
}
location ~ (/api/am/publisher/v4|/authenticationendpoint|/logincontext|/commonauth|/oidc) {
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $http_host;
proxy_read_timeout 5m;
proxy_send_timeout 5m;
proxy_pass https://127.0.0.1:9443;
proxy_set_header X-WSO2-Tenant "tenant1.com";
}
location ~ (/oauth2) {
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $http_host;
proxy_read_timeout 5m;
proxy_send_timeout 5m;
proxy_pass https://127.0.0.1:9443;
proxy_redirect https://127.0.0.1:9443/ https://pubtenant1.wso2.com/;
proxy_set_header X-WSO2-Tenant "tenant1.com";
}
}- After adding the above rule configurations and saving the conf file, you can simply reload the Nginx rule in the server. For that, you can execute the below command.
sudo nginx -s reloadEnable service provider creation feature in tenant-wise
- For this, you need to log into the admin portal of the API manager(Default URL: https://<APIM_HOST>:<APIM_PORT>/admin) by using the tenant admin’s credentials.
- Now click on the Advanced section on the left navigation and under the tenant conf JSON content in the window, add the below JSON key and value, and save the content.
"EnablePerTenantServiceProviderCreation": trueThe final view of the above step should be as below.
Now we have completed the basic configurations for the tenant level before going through the OIDC SSO configurations. Before moving with that, let’s try to load the tenant publisher portal and tenant dev portal. 😇
- Open a new tab of the browser and hit the below URLs to open portals and log into them.
Publisher: https://pubtenant1.wso2.com
Dev Portal: https://dptenant1.wso2.com
Configure the IS 6.1.0 for SSO
From this step onwards, we need to use the WSO2 Identity Server to configure that as an external Identity Provider for the API Manager portals. 😇
- Download the WSO2 Identity Server 6.1.0 distribution through the official link [1]. (By selecting previous releases).
Also if you have a valid WSO2 subscription, then you can download the latest updates to the product by using the update 2.0 channel. For more information, please refer to the documentation [2]
- Open the deployment.toml file inside the <IS_HOME>/repository/conf directory.
- Offset the server by adding 1. (Since we have started up the API Manager on top of the 9443 default port)
[server]
hostname = "localhost"
node_ip = "127.0.0.1"
offset=1
base_path = "https://$ref{server.hostname}:${carbon.management.port}"- Save the deployment.toml file and start the WSO2 Identity Server 6.1.0 pack.
- Log into the carbon management console. (Default URL: https://<IS_HOST>:<IS_PORT>/carbon)
Since we are going to configure the JIT provisioning and we need to authenticate users in the Identity Provider level to access API Manager portals, we need to create 2 custom roles and 2 user profiles by assigning those.
- Click on the Add button under the Users and Roles section on the left navigation.
- Then click on the Add New Role button.
- We can create 2 new roles (Eg: TEST_PUBLISHER_ROLE, TEST_SUBSCRIBER_ROLE) without assigning permissions.
- After that, we can create 2 user profiles (Eg: subscriber_user, publisher_user) and assign the below roles.
subscriber_user -> TEST_SUBSCRIBER_ROLE
publisher_user -> TEST_PUBLISHER_ROLE
Now let’s create a service provider for the SSO purpose.
- Click on the Add button under the Service Providers section.
- Put a name in the Service Provider Name field. (Eg: APIM_SSO)
- Expand the Claim Configuration section.
- Now we need to get the groups claim and username claim from the IDP side through the authentication response to provision the user based on the mapped roles and names. For that, we need to select the groups claim as a mandatory one under the Requested Claims table and the username claim as the subject claim URI as below. (But if you are using the WSO2 Identity Server 5.11.0 version, you need to select the roles claim instead of the groups claim)
- Expand the Inbound Authentication Configuration section and expand the OAuth/OpenID Connect Configuration section.
- Click on the Configure button.
- For the Callback URL, you can add the commonauth URL of the API Manager server. (Eg: https://<APIM_HOST>:<APIM_PORT>/commonauth)
- Then click on the Update button to register the service provider.
- Once you register, you can get the consumer key and the consumer secret of the service provider. This will be used to make the OIDC SSO connection from the API Manager level.
- Then click on the List under the OIDC Scopes section on the left navigation.
- Click on the Add claims under the openid section.
- Then click on the Add OIDC Claim, select groups claim, and click on the Add button.
Now we came closer to completing the flow. FEW MORE STEPS TO GO 🤓
Getting the groups claim (OIDC flow) and then doing the role mapping
- Go to the API Manager’s carbon management console and log in by using the tenant’s admin credentials.
- Click on the Add button under the Identity Providers section on the left navigation.
- For the Identity Provider Name field, put a name (Eg: WSO2_IS)
- Expand the Claim Configuration -> Basic Claim Configuration section.
- On that page, select the Define Custom Claim Dialect option.
- Under the Identity Provider Claim URI field in the table, add groups. Because the WSO2 Identity Server will send all the roles of the user in the OIDC flow via the groups claim.
- Under the Local Claim URI section, select role claim.
- For the Role Claim URI selection, select groups.
- Now expand the Role Configuration section and click on Add Role Mapping.
Since we are going to map the user roles in the WSO2 Identity Server side (External IDP) with the API Manager roles, we need to configure the role mapping with those values. We are going to map the TEST_PUBLISHER_ROLE on the Identity Server side to the Internal/publisher role on the API Manager side and TEST_SUBSCRIBER_ROLE on the Identity Server side to the Internal/subscriber role on the API Manager side.
- Now expand the Federated Authenticators -> OAuth2/OpenID Connect Configuration section.
- Put a tick to Enable OAuth2/OpenIDConnect.
- For the Client ID and Client Secret fields, you need to put the consumer key and secret which was taken from the service provider in the WSO2 Identity Server side.
- For the rest of the fields, the values should be as below.
Authorization Endpoint URL: https://<IS_HOST>:<IS_PORT>/oauth2/authorize
Token Endpoint URL: https://<IS_HOST>:<IS_PORT>/oauth2/token
Callback Url: https://<APIM_HOST>:<APIM_PORT>/commonauth
Userinfo Endpoint URL: https://<IS_HOST>:<IS_PORT>/oauth2/userinfo?schema=openid
Logout Endpoint URL: https://<IS_HOST>:<IS_PORT>/oidc/logout
Additional Query Parameters: scope=openid
Now almost all the things are completed. 🤓 Let’s enable the JIT provisioning.
- Expand the Just-in-Time Provisioning section.
- Select Always provision to User Store Domain PRIMARY with the Provision silently option.
- Click on the Update button at the bottom of the page to save all the configurations.
Now we have completed the IDP configurations. Let’s assign this IDP to the devportal and publisher service providers.
- Click on the List under the Service Providers section.
- You will be able to see the apim_devportal and apim_publisher service providers if you try to load the tenant portal logins previously.
- Click on the Edit button of one of the service providers and then expand the Local & Outbound Authentication Configuration section.
- Select Federated Authentication option under the Authentication Type section and select the created IDP (WSO2_IS)
- Put a tick to Assert identity using mapped local subject identifier option. Please note that this is a mandatory one to perform the role mapping properly.
- Then click on the Update button.
You can do the same steps for the other service provider to enable the external IDP SSO authentication.
FINAL STEP — Exchange certificates
For this, you need to shut down the API Manager server.
- Then go to the <IS_HOME>/repository/resources/security directory and execute the below keytool command to export the public certificate of the TLS keystore at the Identity Server level.
FORMAT
keytool -export -alias <ALIAS_NAME> -file PUB_CERT.crt -keystore <TLS_KEYSTORE> -storepass <STORE_PASSWORD> -noprompt
EXAMPLE
keytool -export -alias wso2carbon -file PUB_CERT.crt -keystore wso2carbon.jks -storepass wso2carbon -noprompt- Then you can execute the below command by pointing to the truststore of the API Manager and the exported public certificate (PUB_CERT.crt)
FORMAT
keytool -import -trustcacerts -alias <ALIAS_NAME> -file PUB_CERT.crt -keystore <APIM_TRUSTSTORE> -storepass <TRUSTSTORE_PASSWORD> -noprompt
EXAMPLE
keytool -import -trustcacerts -alias IS_CERT -file PUB_CERT.crt -keystore client-truststore.jks -storepass wso2carbon -noprompt- Finally, you can start the API Manager server.
TESTING PHASE
Now we have completed all the steps to configure the SSO for publisher and devportal tenant-wise. Let’s test it.
- Go to the https://dptenant1.wso2.com/ URL. This will route to the tenant1.com’s devportal via the Nginx load balancer.
- Then click on the SIGN-IN button. This will load the login page of the Identity Server as below.
- Once you provide the credentials of the subscriber_user, you can log into the portal as below. Also, you can able to see the tenant1.com domain name at the end of the username.
- That means, the user was able to log into the tenant1.com’s devportal as expected. Let’s check whether the subscriber_user got provisioned to the tenant1.com tenant. You can check this by listing down all the users under tenant1.com’s carbon management console of the API Manager.
You can check the same login process of the tenant’s publisher portal after configuring the WSO2_IS IDP as the federated authenticator via the tenant’s carbon management console and you could able to see a similar kind of below page once the publisher_user logs into the system.
SO YEAH!!!, THE SOLUTION IS WORKING AS EXPECTED 😎😎😎
Congratulations!!! Now you have successfully configured the OIDC SSO flow in tenant-wise publisher and devportal. Therefore, you can configure different OIDC SSO flows with external IDPs for different tenants by going through this. 😎😎😎
Happy Provisioning!!! 😁😁😁
[1] https://wso2.com/api-manager/previous-releases/
[2] https://updates.docs.wso2.com/en/latest/
[5] https://wso2.com/identity-and-access-management/previous-releases/
