Okta Connector

The Okta connector provides identity mappings for each user based on the apps that they use.

Note: As part of Atolio Configuration, this connector should be selected as Identity Provider if it is used to resolve app-user mappings.

Service Account and Required Permissions

Okta API tokens inherit the permissions of the user that creates them, so we recommend creating a dedicated service account rather than using a personal admin account. The connector only performs read operations against Okta (users, groups, applications, application users, and the System Log).

Assign one of the following to the service account:

• Read-only Administrator (built-in role) — the simplest option, and the lowest-privilege built-in role that covers everything the connector needs.
• A custom admin role with these read permissions, scoped to all users, all groups, and all apps:
  • okta.users.read
  • okta.groups.read
  • okta.apps.read
  • okta.logs.read
  • okta.reports.read

Note: The connector tolerates per-request 403 Forbidden responses and continues processing other events, so an under-scoped token will produce incomplete data rather than a hard failure. If you scope the role to a subset of users, groups, or apps, anything outside that scope will silently be missing from search results.

Creating an API Token

Sign in as the service account and create the token at https://example.okta.com/admin/access/api/tokens (replacing example.okta.com with your Okta domain). See Okta’s Create an API token guide for full details. Copy the token value when it is shown, since Okta displays it only once. You’ll provide it as described in Required Configuration Values.

Note: Okta revokes API tokens after 30 days of inactivity. The connector polls Okta continuously and keeps the token active during normal operation, but if the connector is paused or disabled for an extended period the token will need to be regenerated.

Manager Resolution

By default, user managers are resolved using the following hierarchy to build reporting structures:

1. The manager linked object primary relationship, when your org defines one.
2. The managerId profile attribute, as a fallback when the linked object is absent or the lookup fails.

Some organizations populate neither of these and may sync manager identifiers to custom profile attributes. For these cases, an optional managerResolution configuration resolves managers from a user’s profile attribute:

managerResolution:
  # Attribute on the user's profile holding the manager reference.
  managerAttribute: managerEmail
  # Attributes on the manager's own profile the reference is matched against.
  matchAttributes:
    - email
    - login

With this example configuration:

        user                                        manager
┌──────────────────────────┐          ┌──────────────────────────────┐
│ profile:                 │          │ id: 00u4abc123               │
│   managerEmail: ─────────┼─────────▶│ profile:                     │
│    jane.doe@atolio.com   │  matches │   email: jane.doe@atolio.com │
└──────────────────────────┘          │   login: jdoe@atolio.com     │
     managerAttribute                 └──────────────────────────────┘
                                             matchAttributes
                                                   │
                                 user's manager ◀──┘ (id: 00u4abc123)

If the attribute on the user’s profile already contains the manager’s Okta user ID, simply specify the attribute which should be used for lookup:

managerResolution:
  managerAttribute: managerIdSynced

Required Configuration Values

Enter these values in the Atolio Admin console (v4.24 and later), or send them to Atolio Support (your Deployment Engineer).

Keep secrets secure: Share values marked “Yes” in the Secret column only through a password-manager share (e.g. 1Password) or another secure channel agreed with Atolio Support. Never send them in plain email, chat, or support tickets.

Configuration Example

Add this block to connector-values.yaml. Replace each <PLACEHOLDER> with the matching value from the table above, and remove any line marked “Only if” that doesn’t apply.

connectors:
  okta:
    default:
      okta:
        connector: okta
        instance: default
        source: okta
        common:
          enabled: true
          identity-provider: true  # Set to false if Okta isn't used to resolve app-user mappings
        secrets:
          token:
            value: "<API_TOKEN>"
        configuration:
          hostname: "<HOSTNAME>"
          managerResolution:  # Only if managers are stored in custom profile attributes
            managerAttribute: "<MANAGER_ATTRIBUTE>"
            matchAttributes:
              - "<MATCH_ATTRIBUTE>"