Configuring Identity Server as External IDP using OIDC

WSO2 API Manager uses the OpenID Connect Single Sign-On (OIDC SSO) feature by default. This document explains how to connect WSO2 Identity Server (or WSO2 IS-KM) as a third party Identity Provider to API-Manager.


  1. Download the API Manager 3.1.0 distribution.

    1. Access the previous WSO2 API Manager related releases.
    2. Select version 3.1.0.
    3. Download the API Manager.
  2. Download the Identity Server 5.10.0 distribution from


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

  3. Start the servers using the following commands:

    wso2server.bat --run

Step 1 - Configure the Identity Server

Step 1.1 - Configure the Service Provider

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

  2. Navigate to the Service Providers section under MainIdentity and create a new Service Provider.

  3. Edit the created Service Provider:

    1. Expand the Claim Configuration section and add as a mandatory claim.

      Claim Configuration in Service Provider

    2. Expand the Inbound Authentication Configuration section and configure the OAuth/OpenID Connect Configuration with the callback URL - https://{apim-ip}:9443/commonauth

      Enable a tenant-specific SSO for the Publisher and Developer Portal

      To enable a tenant-specific SSO with IS 5.10.0 for Publisher and the Developer Portal, enable the Use tenant domain in local subject identifier option under the Local & Outbound Authentication Configuration section.

      SAML configuration in service provider

    3. Update the Service Provider configurations.

      In Multi-tenanted environments

      Carry out the instruction given below for all the tenants to be able to sign in to the API-M Web applications in a multi-tenanted environment.

      1. Click the SaaS Application option that appears after registering the Service Provider.

      saas configuration in service provider

      If you do not select the SaaS Application option, only users in the current tenant domain will be allowed to sign in to the portals. You will need to register separate Service Providers for portals from each tenant.

Step 1.2 - Create users and roles

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

    User Role
    api_publisher publisher_role
    api_user user_role

Step 2 - Configure the API Manager

Step 2.1 - Configure the Identity Provider

  1. Sign in to the Management Console of API Manager.

  2. Navigate to the Identity Providers section under MainIdentity and create a new Identity Provider.

    1. Expand the Federated Authenticators section and add the following configurations under the OAuth2/OpenIDConnect Configuration section:

      Enable OAuth2/OpenIDConnect True
      Client Id Client ID of the Service Provider created in the Identity Server.
      Client Secret Client Secret of the Service Provider created in the Identity Server.
      Authorization Endpoint URL
      Token Endpoint URL
      Callback Url
      Userinfo Endpoint URL
      Logout Endpoint URL

      The following image shows the sample values for the OAuth2/OpenIDConnect Configurations:

      Identity Provider Configuration for SSO

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

      JIT provisioning for SSO

    3. Add the following role mapping under the Role Configuration section:

      Identity Server Roles Roles Mapped in API Manager
      user_role Internal/Subscriber
      publisher_role Internal/publisher

      Role mapping for SSO


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

Step 2.2 - Configure the Service Provider

  1. Navigate to the Service Providers section and list the Service Providers.

    There are two Service Providers created for the Publisher Portal and Developer Portal that are named as apim_publisher and apim_devportal. Edit the apim_publisher Service Provider.


    You need to sign in to the Developer Portal and Publisher at least once for the two Service Providers to appear because it is created during the first login.

  2. Expand the Local & Outbound Authentication Configuration section, select Federated Authentication as Authentication Type, select the name of the Identity Provider you created in Step 2.1, and click Update.

    Local and outbound authentication configuration for SSO

  3. Repeat the same step for the apim_devportal Service Provider as well.

Now you will be able to sign in to Publisher and Developer Portal using the users in WSO2 Identity Server.


When using the Identity Server as an external IdP, the following error can be observed in API Manager, when signing in to the Portals.

invalid_request, The client MUST NOT use more than one authentication method in each

This is because the MutualTLS authenticator is enabled by default from IS 5.8.0 onwards. As the OIDC specification does not allow the use of more than one authentication, the login fails with the above error. In order to resolve this issue, add the following configuration in the deployment.toml resides in <IS_HOME>/repository/conf directory to disable the MutualTLS authenticator in IS.

id = "mutual_tls_authenticator"
type = "org.wso2.carbon.identity.core.handler.AbstractIdentityHandler"
name = "org.wso2.carbon.identity.oauth2.token.handler.clientauth.mutualtls.MutualTLSClientAuthenticator"
order = "158"
enable = false