Skip to main content

Okta

Visualize Okta users, groups, devices, applications, and services, map users to employees, and monitor changes through queries and alerts.

Installation​

The integration can authenticate to Okta in two ways. Pick one when you create the instance:

  • OAuth 2.0 Service App: an API Services app that signs in with a private key and gets short-lived, scoped access tokens.
  • Basic: an Okta API token.

The integration only reads from Okta. Whichever method you use, it needs the Read-Only Administrator role. That covers users, groups, group rules, applications, devices and the System Log.

note

Two things need the Super Administrator role, per Okta's admin role comparison:

  • Admin role assignments (the Okta User Roles data source). With a lower role, those steps are skipped and every other step still runs.
  • The Okta Support access setting. With a lower role, okta_account.supportEnabled is left empty.

The Authorization tab lists every Okta API endpoint the integration calls, the admin role each one needs and, for the OAuth method, the scope each one needs.

Option 1: OAuth 2.0 Service App​

These steps follow Okta's guide, Implement OAuth for Okta with a service app. Only a Super Administrator can grant API scopes to an app.

  1. In the Okta Admin Console, go to Applications > Applications, click Create App Integration, select API Services and give the app a name, such as JupiterOne.

  2. On the app's General tab, in Client Credentials, click Edit and set Client authentication to Public key / Private key. Add a key: either let Okta Generate new key and save the private key it shows (it is shown only once), or paste the public key of a key pair you created. Okta accepts RSA keys and EC keys on the P-256, P-384 and P-521 curves.

  3. In General Settings, clear Require Demonstrating Proof of Possession (DPoP) header in token requests. Okta turns it on for new service apps, and the integration does not support DPoP.

  4. On the Okta API Scopes tab, click Grant for each of these scopes:

    ScopeUsed for
    okta.users.readUsers and their MFA factors
    okta.groups.readGroups, group members and group rules
    okta.apps.readApplications and their user and group assignments
    okta.logs.readSystem Log events that record who created each application
    okta.roles.readAdmin role assignments of users and groups
    okta.orgs.readThe Okta Support access setting
    okta.devices.readDevices. Only needed when the Okta Devices data source is on

    If okta.devices.read is not granted, the integration requests a token without it and every other data source still runs.

  5. On the Admin Roles tab, click Edit assignments and assign Read-Only Administrator, or Super Administrator to also ingest admin role assignments and the Okta Support setting (see the note above). Without an admin role, every API call returns 403.

  6. Copy the app's Client ID from the General tab.

The private key goes into JupiterOne as a file. Save it as the JWK (JSON) that Okta generated, or as a PEM. If the app has more than one public key and you use a PEM, also note the key's KID from the General tab. A JWK already carries it.

Option 2: API token​

Create an API Token on Okta from an Okta account with admin permissions. Ensure that you are in admin-mode when creating the token by selecting the Admin button in the top right prior to creating the API Token.

An Okta API token carries the admin role of the user who created it, so create the token from a Read-Only Administrator account, or a Super Administrator one for the two items in the note above.

Per the Okta documentation: API tokens are valid for 30 days and automatically renew every time they are used with an API request. When a token has been inactive for more than 30 days it is revoked and cannot be used again. Tokens are also only valid if the user who created the token is also active.

info

For additional information regarding Okta API tokens, see their documentation for more information.

Configuration in JupiterOne​

To install the Okta integration in JupiterOne, navigate to the Integrations tab in JupiterOne and select Okta. Click New Instance to begin configuring your integration.

Creating an instance requires the following:

  • The Account Name used to identify the Okta account in JupiterOne. Ingested entities will have this value stored in tag.AccountName when the AccountName toggle is enabled.

  • Description to assist in identifying the integration instance, if desired.

  • Polling Interval that you feel is sufficient for your monitoring needs. You may leave this as DISABLED and manually execute the integration.

  • Choose the authentication method and enter the Organization URL unique to your Okta organization. Then:

    • For OAuth 2.0 Service App: the service app's Client ID, the Private Key file and, only if the app has several keys and the file is a PEM, the Key ID.
    • For Basic: your Okta API Key.

These settings are optional:

  • Additional user profile attributes: a comma-separated list of Okta user profile attributes to add to okta_user entities, such as custom attributes your admins created (for example: badgeNumber, building). Use the variable names shown in Okta's Profile Editor. Each attribute is added under its camelCased name (team_code becomes teamCode). Okta's standard profile attributes, such as title, department and employeeNumber, are ingested without being listed.

  • Ingest Admin Notes: adds each application's admin notes to okta_application.adminNotes.

The data sources section lets you turn off what you don't need: Okta Apps, User Groups, MFA Devices, User Roles and Group Rules are on by default. Okta Devices is off by default and requires the org to be on Okta Identity Engine. Turning a data source off stops its API calls and removes its entities from JupiterOne on the next run.

Click Create once all values are provided to finalize the integration.

Next steps​

Now that your integration instance has been configured, it will begin running on the polling interval you provided, populating data within JupiterOne. Continue on to our Instance management guide to learn more about working with and editing integration instances.