Using OKTA As An External IDP With OIDC

In the following document we will explain how to connect OKTA as a third party Identity provier to WSO2 API-Manager. Before we start first make sure you have all the pre-requisites mentioned below.


  1. Create an account in
  2. Download the latest API-Manager distribution from
  3. Unzip the distribution and open the deployment.toml file located in <APIM_HOME>/repository/conf/ and add the following configuration
    enable_email_domain= true
    This is needed since OKTA uses the email as the username by default, therefore to use the email as the username in WSO2 API-Manager we have to enable it since it not enabled by default. Once enabled both email as username and normal usernames can be used.
  4. Start the Server.

Setup OKTA

  1. Go to the OKTA admin portal and navigate to Applications -> Add Application

  2. Select type web and use the following details

    3. Next we need to add a new attribute to the default user profile of OKTA to epresent the user role. Navigate to Users -> Profile Editor and click on the pencil icon to edit the default profile

  3. Enter the following details and click save

  4. Next we need to add the claims that needs to be returned from the ID Token in okta. These are the claims we will be used to map the user details to WSO2 API-Manager side. Navigate to API -> Authorization Servers and select the default server

  5. Add the following two claims

  6. Go to Users -> People and click on your profile name. And navigate to the profile edit page as shown below

    add the following role value. This will be used in the API-Manager to map an internal role to user that will be provisioned.

Setup API-Manager

  1. Login in to https://localhost:9443/carbon.

  2. First we need to create a role that needs to be assinged to users that will be provisioned from okta. click on add in Users and Roles section and add a new role.

    Assign the following permissions to the role and save

  3. Login to https://localhost:9443/admin and navigate to Role Permissions section under the Settings tab in the left menu bar.

    Click on the Add role permission button in the above screen and a popup dialog will be opened as shown below. Enter okta_role in the Provide role name field and click on Next button.

    Now, under the Select permissions section, click on Custom permissions radio button and start assigning the permissions as shown below.

    Now, click on Save button. (These permissions will allow a user having the okta_role to login to Publisher and Developer Portals)


    If you want your user to do analytics based tasks, you should add the okta_role to the required analytics scopes according to your choice. You can follow the below steps as an example.

    • Login to https://localhost:9443/carbon.
    • Navigate to Main > Resources > Browse.
    • Enter /_system/config/apimgt/applicationdata/tenant-conf.json as the location and click Go to browse the registry and locate the required resource.
    • Update the RESTAPIScopes JSON field by adding okta_role to the Roles field under the corresponding Name fields as shown below for the analytics related scopes.
          "Name": "apim_analytics:api_analytics:view",
          "Roles": "admin,Internal/creator,Internal/publisher,okta_role"
          "Name": "apim_analytics:application_analytics:view",
          "Roles": "admin,Internal/subscriber,okta_role"
    • Click on Save Content button.
  4. Login in to https://localhost:9443/carbon & Click on add in identity providers section. Enter Identity Provider Name.

    Expand Federated authenticators -> OAuth2/OpenID connect configuration add the following details.

    Field Sample value
    Enable OAuth2/OpenIDConnect True
    Client id Can be found in the okta application you created
    Client secret Can be found in the okta application you created
    Authorization Endpoint URL https://your_okta_url/oauth2/default/v1/authorize
    Token Endpoint URL https://your_okta_url/oauth2/default/v1/token
    callback url https://localhost:9443/commonauth
    Userinfo Endpoint URL https://your_okta_url/oauth2/default/v1/userinfo
    Logout Endpoint URL https://your_okta_url/oauth2/default/v1/logout
    Additional Query Parameters scope=openid%20profile

  5. Expand Claim configuration -> Basic claim configuration and add the following claim configurations

  6. Expand Role configuration and add the following role. Here we check if the user that is being logged in has the role any and assign him the local role okta_role

  7. Enable Just in time provisioning so that the user will be saved in the API-Manager user store

  8. Navigate to Service providers -> list as shown below. There are two service providers created apim_publisher, apim_devportal. Click on edit on apim_publisher.


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

    Expand local and outbound authentication configuration and under federated authentication select the name of the identity provider you created.

    Repeat the same for apim_devportal service provider.

Now you are able to login to the Publisher & Developer Portal using OKTA.