Using Okta as an External IDP with OIDC

Follow the instructions below to connect Okta as a third-party Identity Provider to WSO2 API Manager.

Pre-requisites

Before you begin, make sure you do the following.

  1. Create an account in https://developer.okta.com/
  2. Download API Manager version 4.0.0 distribution from https://wso2.com/api-management/
  3. Unzip the distribution and open the deployment.toml file located in <API-M_HOME>/repository/conf/ directory. Add the following configuration.
    [tenant_mgt]
    enable_email_domain= true
    You need to enable this because Okta uses the email as the username by default. To use the email as the username in WSO2 API Manager you have to enable it as it is not enabled by default. Once enabled, you can use your email or a normal username as your username.
  4. Start the WSO2 API Manager server.

Step 1 - Configure Okta

  1. Navigate to the Okta Admin Portal.

  2. Click Applications and then click Add Application.

    Add new application in Okta

  3. Select the type as web and use the following details.

    Add new web application in Okta

    Add new application details in Okta

  4. Add a new attribute to the default user profile of Okta to represent the user role.

    1. Navigate to Users -> Profile Editor.

    2. Click Profile to edit the default profile.

      Add new attribute in Okta

      You will be able to see the user attributes in the Profile Editor.

    3. Click Add Attribute to add new user attributes.

      See newly added attribute in Okta

    4. Enter the user role details and click Save.

      Add new attribute details in Okta

  5. Add the claims that need to be returned from the ID Token in Okta.

    These claims will be used to map the user details with WSO2 API Manager.

    1. Navigate to API -> Authorization Servers and select the default server.

      Add new claims in Okta

    2. Add the following two claims as shown in the images below.

      Add new claims user in Okta

      Add new claims role in Okta

  6. Enable WSO2 API Manager to map an internal role to a provisioned user.

    1. Go to Users -> People and click on your profile name.

      Edit profile in Okta

    2. Navigate to the profile edit page as shown below.

    3. Add any as the role value as shown below.

      This will be used by API Manager to map an internal role to a provisioned user.

      Edit Okta profile

Step 2 - Configure API Manager

  1. Sign in to the WSO2 API-M Management Console.

    https://localhost:9443/carbon.

  2. Create a role that needs to be assigned to users that will be provisioned from Okta.

    1. Go to Users and Roles.

    2. Click Add to add a new role.

      Add role for Okta in API-M

    3. Assign the following permissions to the role and click Save.



  3. Add role permissions via the WSO2 API Manager Admin Portal.

    1. Sign in to the WSO2 API Manager Admin Portal.

      https://localhost:9443/admin

    2. Click Settings and then click Role Permissions.

      Okta API-M role pemission mapping

    3. Click Add role permission.

    4. Enter okta_role in the Provide role name field and click Next.

      Edit Okta API-M role pemission mapping

    5. Go to Select permissions, click Custom permissions, and start assigning the permissions as shown below.

      These permissions will allow a user having the okta_role to login to Publisher and Developer Portals.

      Okta API-M role pemission mapping

      Okta API-M role pemission mapping

      Okta API-M role pemission mapping

      Okta API-M role pemission mapping

      Okta API-M role pemission mapping

      Okta API-M role pemission mapping

    6. Click Save to save your changes.

    Note

    If you want your user to perform analytics-based tasks, you should add the okta_role to the required analytics scopes according to your preference. The steps below are given as an example.

    1. Sign in to the API-M Management Console. https://localhost:9443/carbon

    2. Navigate to Main > Resources > Browse.

    3. Enter /_system/config/apimgt/applicationdata/tenant-conf.json as the location and click Go to browse the registry and locate the required resource.

    4. 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"
      },

    5. Click Save Content.
  4. Add an Identity Provider.

    1. Sign in to the WSO2 API-M Management Console.

      https://localhost:9443/carbon.

    2. Click Main and then click Add under Identity Providers.

    3. Enter the Identity Provider's Name.

      Add an IDP for Okta SAML

    4. Expand Federated authenticators -> OAuth2/OpenID Connect Configuration and add the following details.

      API-M IDP OIDC details

      Field Sample value
      Enable OAuth2/OpenIDConnect True
      Client id You can find this value from the Okta application that you created.
      Client secret You can find this value from the Okta application that 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. Add the claim configurations as shown in the image below.

      Okta API-M IDP claims details

    6. Expand Role configuration and add okta_role as shown below.

      You can check if the user logged in has the role any and assign the local okta_role.

    7. Enable Just-in-Time Provisioning for the user to be saved in the API Manager user store.

    Info

    When Just-In-Time Provisioning is enabled, the user details will be saved in the API Manager user store. User profile details will be updated via the federation following each login event. To preserve the user profile details without any changes you need to enable SystemRolesRetainedProvisionHandler.

    Add the following to the <API-M_HOME>/repository/conf/deployment.toml file and restart the server.

    [authentication.framework.extensions]
    provisioning_handler = "org.wso2.carbon.identity.application.authentication.framework.handler.provisioning.impl.SystemRolesRetainedProvisionHandler"
  5. Update the Service Providers.

    1. Click Service Providers -> List in the WSO2 API-M Management Console.

      There are two service providers available by default; apim_publisher and apim_devportal.

    2. Click Edit to edit apim_publisher.

      Warning

      You need to have signed in to the Developer Portal and Publisher at least once for the two service providers to appear, as it is created during the first sign in.

      Okta API-M role OIDC SP

    3. Expand Local & Outbound Authentication Configuration under Federated Authentication and select the identity provider you created.

      Okta API-M role OIDC SP outbound

    4. Repeat the latter mentioned two steps for apim_devportal.

Now you will be able to Sign in to the Publisher and Developer Portal using Okta.

Top