Configuring Identity Server as External IDP using SAML

The Single Sign-On with SAML 2.0 feature in the API Manager is implemented according to the SAML 2.0 browser-based SSO support that is facilitated by WSO2 Identity Server. This feature is available in any WSO2 IS version from 4.1.0 onwards. WSO2 IS 5.10.0 is used in this guide. WSO2 Identity Server acts as an identity Service Provider of systems enabled with single sign-on, while the Web applications act as SSO Service Providers. Using this feature, you can configure SSO with SAML 2.0 across the API Publisher and Developer Portal. After configuring, you can access the Developer Portal or API Publisher in a single authentication attempt.


  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


    To use WSO2 IS as the Key Manager, download the WSO2 Identity Server 5.10.0 as a Key Manager pack, with pre-packaged Key Manager features as follows:

    1. Access the previous WSO2 API Manager related releases.
    2. Select version 3.1.0.
    3. Click on the Identity Server as a Key Manager download option.


    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 WSO2 Identity Server

Step 1.1 - Configure the Service Provider

  1. Sign in to the Management Console of IS server.

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

  3. Edit the created Service Provider:

    1. Expand the Inbound Authentication Configuration section and configure SAML2 Web SSO Configuration by providing the following information:

      Issuer Specify the Issuer
      Assertion Consumer URLs https://{apim-ip}:9443/commonauth
      Response Signing Algorithm
      Enable Response Signing true
      Enable Signature Validation in Authentication Requests and Logout Requests true
      Enable Single Logout true
      Enable Attribute Profile true
      Include Attributes in the Response Always true

      The following image shows the sample values for SAML2 Web SSO configuration:

      SAML configuration in service provider

      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.


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

      Claim configuration in service provider for SAML2 SSO

    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.


      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.

  4. Upload the public certificate of the API Manager by selecting Select SP Certificate Type.

    Upload certificate in SP for SAML2 SSO

Step 1.2 - Create users and roles

  1. Create the required users and roles in Identity Server. Let's assume that the following users are created in Identity Servers with the given roles.

    User Role
    api_publisher publisher_role
    api_user user_role

Step 2 - Configure WSO2 API Manager

Step 2.1 - Configure the Identity Provider

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

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

    1. Upload the public certificate of Identity Server under the Upload IDP certificate.

    2. Expand the Federated Authenticators section and add the following configurations under SAML2 Web SSO Configurations:

      Enable SAML2 Web SSO true
      Service Provider Entity ID It depends on the Issuer value defined in the Service Provider configured in Identity Server above
      Identity Provider Entity ID localhost
      SSO URL https://{is-ip}:9444/samlsso
      Signature Algorithm RSA with SHA256
      Single Logout profile true
      Enable Authentication Request Signing true
      Enable Authentication Response Signing true
      Enable Logout Request Signing true
      Enable Logout true

      The following image shows the sample values for SAML2 Web SSO configurations:

      SAML configuration in Identity Provider


      Make sure your Service Provider configurations in the Identity Server and the Identity Provider configurations in API Manager reflect each other.


      • If the Response Signing Algorithm in Identity Server is rsa-sha256, then the Signature Algorithm in API Manager should be RSA with SHA256.
      • If you enabled Enable Single Logout in the Service Provider created in the Identity Server, then enable Single Logout Profile in the Identity Provider created in API Manager.
    3. Enable Just-in-Time Provisioning to provision the users in API Manager.

      JIT provisioning for SSO

    4. 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 Publisher portal and Developer portal named as apim_publisher and apim_devportal. Edit the apim_publisher Service Provider.


      You will have to log into the Developer Portal and Publisher at least once for the two Service Providers to appear as it is created during first login.

    2. Expand the Local & Outbound Authentication Configuration section, select Federated Authentication as Authentication Type, and select the name of the Identity Provider you created and 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.


    To learn more about Single Sign-On with WSO2 Identity Server, see SAML 2.0 Web SSO in the WSO2 Identity Server documentation.