Skip to content

Configuring external IDP using OIDC for Multi tenancy

WSO2 API Manager uses the OIDC Single Sign-On feature by default. This document explains how to connect WSO2 Identity Server (or WSO2 Identity Server as a Keymanager) as a third party Identity provider to API-Manager for multi tenant work flows.

Info

To use the multi-tenant SSO feature, you need to update your WSO2 API Manager pack to update level 4.5.0.63 or later.

Note

If do not require multi tenancy, you can follow this document: Configuring Identity Server as External IDP using OIDC

prerequisites

  • Download the API Manager distribution from https://wso2.com/api-management/.

  • Download the Identity Server distribution from https://wso2.com/identity-and-access-management/.

    Tip

    For testing purposes if you want to run both the WSO2 API Manager and WSO2 Identity Server on the same server, go to the <IS_HOME>/repository/conf/deployment.toml file and offset the port by 1 as by adding following configuration:

    [server]
offset=1

  • Start the servers using the following commands:

    wso2server.bat --run

    sh wso2server.sh

Configure the Identity Server

Step - 1 Create new Organization

  1. Sign in to the Management Console of WSO2 IS by browsing the following URL: 

    https://{is-ip}:9444/console

  2. Click on Root Organization and Click Manage Root Organization

    IS 7 dashboard

  3. Then click New Root Organization button and fill this form to create new organization

    IS 7 register new org

  4. Log into the new organization. (https://localhost:9444/t/asd.com/console)

    Note

    Here asd.com is the sample tenant domain name. replace it with proper tenant domain name

Step - 2 Configure the Service Provider

  1. Create a Service Provider:

    a. Go to Applications → New Application and select Traditional Web Application.

    b. In the popup, provide the following details and click Create:

    Protocol OpenID Connect
    Authorized Redirect URL https://localhost:9443/t/asd.com/commonauth

    Create Traditional Web Application

    c. In the configuration page, select User Attributes and enable the Groups attribute.

    Select Groups user attribute

    d. In the same tab, under the Subject section, select Assign alternate subject identifier and from the dropdown list select Username.

    Assign alternate subject identifier

    e. Under the Protocol tab, copy the Client ID and Client Secret.

    Info

    For each tenant you have to create new application

Step - 3 Create users and roles

  1. Create the required users and groups in Identity Server. Assume, following users are created in Identity Servers with the given groups.

    User Groups
    Sam publisher
    Karen devportal

Configure the API Manager

Note

You need to enable tenant synchronization to create IS tenants on the APIM side. Please follow this guide to enable tenant synchronization. Since this topic is outside the scope of this discussion, I won’t go into further detail here.

Step - 1 Import the Identity Server Certificate to WSO2 API Manager

Import the Keymanager certificate to the WSO2 API Manager client-truststore.jks using the following steps.

  1. Export the WSO2 IS certificate.

    echo -n | openssl s_client -connect localhost:9444 -servername wso2is7 | openssl x509 > is7.cert

    openssl s_client -connect localhost:9444 -servername wso2is7 < NUL | openssl x509 > is7.cert

  2. Import this certificate to the client-truststore.jks located in <AM_HOME>/repository/resources/security/.

    keytool -import -alias wso2is7cert -file is7.cert -keystore client-truststore.jks -storepass wso2carbon

Step - 2 Additional deployment.toml changes

[tenant_context]
enable_tenant_qualified_urls = true
enable_tenanted_sessions = true
skip_tenant_validation_for_oauth_endpoints = true
session_manager= "org.apache.catalina.session.StandardManager"

[event.default_listener.jit_provisioning_handler]
enable = false

[[event_listener]]
id = "org_jit_provisioning_handler"
type="org.wso2.carbon.identity.core.handler.AbstractIdentityHandler"
name = "org.wso2.carbon.identity.outbound.organization.auth.OrganizationJITProvisioningHandler"
# Same value as "event.default_listener.jit_provisioning_handler.priority": "20",
order = 20
Config Description
tenant_context.enable_tenant_qualified_urls Enable tenant qualified URLs.
tenant_context.enable_tenanted_sessions Enable tenanted sessions
tenant_context.skip_tenant_validation_for_oauth_endpoints Enable this if you are using resident key manager
tenant_context.session_manager You can skip this if you are using external key manager
event.default_listener.jit_provisioning_handler.enable To disable default JIT provisioning handler
event_listener This adds custom JIT provisioning handler

Step - 3 Configure Federated Authenticators

  1. Configure Super Tenant IdP

    • Purpose: Capture tenant details and proxy tenant-specific users to the appropriate service providers within their respective tenants, while also handling users from the carbon.super tenant.
    • First log in to the carbon portal (https://{apim-ip}:9443/carbon) using the admin account.
    • Then, from the left navigation menu, go to the Identity Providers section and click the Add button.

    • Add the following claim mapping under the Claim Configuration section.

      Identity Provider Claim URI Local Claim URI
      groups http://wso2.org/claims/role

      Also select groups as the Role Claim URI.

    Claim mapping for sso

    • Add the following role mapping under the Role Configuration section:

      Identity Server Roles Roles Mapped in API Manager
      devportal Internal/Subscriber
      publisher Internal/publisher

      Tip

      Instead of using the default internal roles, you can also create new roles in API Manager and map it to the provisioned users.

    • Select Multi Tenant Authenticator Configuration under the Federated Authenticators section:

      Configuration Value Description
      Enable true Set true to enable the authenticator
      Tenant Selection Page URL https://{apim-ip}:9443/select-tenant/ You can customize this page as required, default page will be avaiable on the above location
      Common Service Provider Name commonsp In each tenant (including super tenant), you have to create a service provider from this name
      Scopes openid

      Other fields are self explanatory. Refer the image below if you need more clarity.

      Multi Tenant Authneticator Configs

    • Enable Just-in-Time Provisioning to provision the users in API Manager:

    • Finally click Register to save the changes

Step - 4 Configure Common Service Provider

  • From the left navigation menu, go to the Service Providers section and click the Add button.

  • The SP name should match the one you define in the super tenant IdP, under 'Common Service Provider Name'.

    Multi Tenant Common SP

  • Next, you need to configure the claim settings to pass user details to the super tenant custom authenticator.

    • Expand the Claim Configuration and expand the Basic Claim Configuration section.
    • In the 'Requested Claims' section, click 'Add Claim URI' and add the following claims.
      • http://wso2.org/claims/username
      • http://wso2.org/claims/roles
    • Then, select http://wso2.org/claims/username as the Subject Claim URI.

    Multi Tenant SP Claim Configs

  • Next, expand the Inbound Authentication Configurations, and expand Oauth/OpenID connect configuration and click configure. Then set the Callback Url to https://localhost:9443/commonauth amd click update.

    Multi Tenant SP OIDC Configs

  • Next, expand the Local & Outbound Authentication Configurations, Select the previously created IdP as the Federated Authenticator, and check the following configurations:

    Multi Tenant SP Outbound Configs

Step - 5 Configure Tenanted IdP

  • Log into carbon portal as an teanted admin

  • Follow the same steps in step - 3, But this time instead of Multi Tenant Authenticator Configuration select OAuth2/OpenID Connect Configuration

    Info

    Here you need to connect to the IS tenanted Application you created in the first section

Step - 6 Configure Tenanted Common Service Provider

  • Log into carbon portal as an teanted admin
  • Follow the same steps in step - 4

Step - 7 Configure the IDP for the Portals

  • Now, In carbon portal, again log as super admin.
  • Click on the List under the Service Providers section.
  • We can see the apim_devportal, apim_publisher and apim_admin_portal service providers as below.
  • 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_IS7)

  • 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.

    Multi Tenant Portal SPs Configs

Verifying

  • Now you are good to go, go the publisher portal https://{apim-ip}:9443/publisher you will see a tenant selection page

    Tenant Selection Page

Tips

This approach is not limited to WSO2 IS 7.x, you can connect any third party identity provider using this method