Skip to main content

Okta

This section will guide you through the configuration of the Okta authentication provider.

The provider will use the Okta endpoint to authenticate users; users and groups must exist, and can be fetched using one of the other integrations proposed.

Authentication Provider​

First of all, to add Okta authentication, you must create an Application from Okta:

  1. Log into Okta (e.g. company.okta.com)
  2. Navigate to Menu >> Applications >> Applications >> Create App Integration
  3. Fill out the Create a new app integration form:
  • Sign-in method: Okta Connect
  • Application type: Web Application
  • Click Next
  1. Fill out the New Web App Integration form:
  • App integration name: Witboost (or your custom app name)
  • Grant type: Authorization Code & Refresh Token
  • Sign-in redirect URIs: https://your-witboost.com/api/auth/okta/handler/frame (this will be the URL of your Witboost instance)
  • Sign-out redirect URIs: https://your-witboost.com (this will be the URL of your Witboost instance)
  • Controlled access: (select as appropriate)
  • Click Save

Then, to configure the Okta authentication provider, you need to provide the following configuration:

auth:
  environment: default
  providers:
    okta:
      default:
        clientId: <clientId>
        clientSecret: <clientSecret>
        audience: <audience>
        authServerId: <authServerId> # Optional
        idp: <idp> # Optional
        additionalScopes: <additionalScopes> # Optional
        signIn:
          resolvers:
            - resolver: emailMatchingUserEntityProfileEmail

where:

  • clientId is the client ID that you generated on Okta, e.g. 3abe134ejxzF21HU74c1
  • clientSecret is the client secret shown for the Application.
  • audience is The Okta domain shown for the Application, e.g. https://company.okta.com. If you are using custom domains, you can find the current domain by clicking on your name in the top right corner of the Okta top bar.
  • authServerId (Optional) is the authorization server ID for the Application
  • idp (Optional) is the identity provider for the application, e.g. 0oaulob4BFVa4zQvt0g3
  • additionalScopes (Optional) is a string of space separated scopes, that will be combined with the default scope value of openid profile email offline_access to adjust the scope sent to Okta during OAuth. This will have an impact on the dependent claims returned. For example, setting the additionalScopes value to groups will result in the claim returning a list of the groups that the user is a member of that also match the ID token group filter of the client app.

All the values referenced above are found on the Application page on your Okta site.

Organization Provider​

This integration will be used to fetch the users and groups information.

To enable this type of integration, you will need to grant your application at least the okta.groups.read and okta.users.read scopes. To do so, you will need to go to the Okta Admin Console, navigate to the Applications section, and edit the application you created for Witboost. Then, go to the Okta API Scopes tab, and assign the okta.groups.read and okta.users.read scopes to the application.

Then, you will need to create an API token to be used by Witboost:

  1. In the Admin Console, go to Security > API
  2. Click the Tokens tab.
  3. Click Create token.
  4. In the What do you want your token to be named? field, enter a token name (like "Witboost")
  5. From the API calls made with this token must originate from dropdown list, select an option to specify where you allow connections to come from.
  6. Click Create token.
  7. Click Copy to clipboard (Copy token) and paste the token in a secure location, such as a password manager. The only time you can view and copy the token is during the creation process. After the token is created, it's stored as a hash for your protection.

Then you can configure the Okta organization provider, by providing the following configuration:

catalog:
  providers:
    okta:
      default:
        orgUrl: <orgUrl>
        token: <apiToken>
        userFilter: profile.department eq "engineering" # Optional
        groupFilter: profile.name eq "Everyone" # Optional
        hierarchyConfig: # Optional
          key: profile.orgId
          parentKey: profile.parentOrgId
        schedule:
          frequency: { hours: 5 }
          timeout: { minutes: 10 }
          initialDelay: { minutes: 1 }

where:

  • orgUrl is the URL of your Okta organization, e.g. https://company.okta.com
  • apiToken is the API token you created in the previous steps
  • userFilter (Optional) is a filter to apply to the users fetched from Okta
  • groupFilter (Optional) is a filter to apply to the groups fetched from Okta
  • hierarchyConfig (Optional) is a configuration to define the hierarchy of the groups. The key is the property that will be used as the group ID, while the parentKey is the property that will be used as the parent group ID.
  • schedule is used to define the frequency and timeout of the fetching process. The frequency represents the time between two fetches, while the timeout represents the maximum time the fetching process can take.
note

Try to keep the initialDelay value around 1 minute to avoid any issues with the initial fetch, since the Okta service may take some time to setup to the first interaction.