Okta

Copy Okta system-log events into the Aegis audit log.

The Okta connector reads your Okta organisation's system log (Okta's record of sign-ins, MFA challenges, password changes, user lifecycle and application access events) and writes each event into the Aegis audit log. You can then search identity activity next to everything else that happened in Aegis. The connector only reads from Okta; it never changes users, groups or policies there. It is separate from signing in to Aegis with Okta, which you set up under single sign-on.

At a glance

Direction Into Aegis.
What it brings in Okta system-log events, the last 24 hours by default, up to 100 events per sync.
Where it lands The audit log. Each event's action reads okta. followed by the Okta event type, for example okta.user.session.start.
Credentials and permissions Either an Okta API token with the okta.logs.read scope, or an OAuth app in your Okta organisation (then sign in with the connector's Authorize with Okta button). Aegis's authorisation request asks for okta.logs.read and okta.users.read, so grant the app both.
Owner of imported records Audit-log entries have no owner. Each entry is attributed to the Aegis user whose email matches the Okta actor; when there is no match, it is attributed to the person who ran the sync.
When it runs On demand with Sync System Log or the API. There is no scheduled sync.
Set it up /connectors/okta, by people allowed to configure connectors, on a plan that includes the connector.

Who uses it

The page checks your role on the server before it renders. Admin and Manager can save the configuration, authorise, test the connection and run a sync. Contributor and Viewer are redirected to the /unauthorized page. Authorising, testing and syncing also need the Okta connector to be switched on for your organisation; if it is not, those buttons return an error rather than reaching Okta. Saving the configuration goes through the shared connector-settings service, which checks the connector licence separately.

What's on this screen

No screenshot of this page is included in this edition of the guide; the description below follows the page as the current product builds it.

Prepare Okta

Choose one mode. OAuth 2.0 is the page's recommended option; an API token is quicker to set up.

OAuth 2.0

  1. In the Okta Admin Console, go to Applications > Applications and select Create App Integration. The integration wizard opens.
  2. Choose OIDC - OpenID Connect and Web Application. Okta asks for the application's settings.
  3. Set the sign-in redirect URI to the exact address the Aegis page prints under step 5 of its OAuth setup instructions (your Aegis address followed by /api/connectors/okta/callback); copy it from there rather than typing it. Okta saves the app and shows its credentials.
  4. Copy the Client ID and Client Secret. Keep them ready for the Aegis form.
  5. Under the app's Okta API scopes, grant okta.logs.read and okta.users.read. The app can now be authorised by Aegis.

API token

  1. In the Okta Admin Console, go to Security > API > Tokens and select Create Token. Okta asks for a name.
  2. Name the token and confirm. Okta shows the token value once only; copy it straight away.

Configure the connector

  1. Open /connectors/okta, or select the Okta tile in the connector catalogue. The page opens with the Connection Status panel at the top and the Configuration form below.
  2. Enter the Organization URL, your Okta organisation's base address such as https://company.okta.com, with no trailing path.
  3. Choose the Authentication Mode: OAuth 2.0 (Recommended) or API Token. The credential fields change to match: Client ID and Client Secret for OAuth, or a single API Token field.
  4. Fill in the credentials and select Save Configuration. The button stays disabled until the address and the credential for the chosen mode are present. A Configuration saved message appears and the status returns to Not Tested; in OAuth mode a yellow notice asks you to authorise.

Secrets are stored encrypted and never shown again; the fields then show ********. To keep a stored secret when you edit other settings, leave its field blank.

Authorise and test the connection

  1. In OAuth mode, select Authorize with Okta in the Connection Status panel. Your browser goes to your Okta sign-in and consent screen. If the button is not showing, select Test Connection first: when authorisation is missing it reports so and the button appears.
  2. Sign in to Okta and grant consent. You return to the Okta page with a green banner, and the status reads Connected. If Okta refuses, you come back with a red banner on this page or on the connector catalogue.
  3. Select Test Connection. The label changes to Testing.... On success a green box shows Connected to Okta, with the organisation name, the subdomain and System Log Access: Available. On failure the status reads Connection Failed with a short reason. In API token mode there is no consent step; test straight after saving.

The test result is saved on the connector. A failed test, or an OAuth authorisation that has expired, marks the connector as in error on the catalogue, so a stale Connected does not outlive the credential it was earned with.

Sync the system log

  1. With the status at Connected, select Sync System Log. The status changes to Syncing... while Aegis reads Okta.
  2. Read the Sync Results tiles that appear. Imported counts new audit-log entries; Skipped counts events already imported by an earlier sync, recognised by their Okta event ID. A red line counts any events that could not be stored.
  3. Open the audit log to search the imported events. Each one keeps Okta's message, timestamp, severity, outcome, client IP address and user agent. The sync itself is also recorded as a connector-sync entry.

Once the connector has synced, the page shows Last successful sync: with the date and time of the last completed sync, and it still does after a reload. The counts of a sync are shown only for the visit in which you ran it; the audit log records every sync.

Tips and limits

Where this connects

Imported events are searched in Audit log. The Connectors chapter covers the catalogue and shared rules. To let people sign in to Aegis with Okta, add Okta as a provider under Settings → Integrations → SSO; SSO with Entra ID walks that screen for Microsoft. It is a separate configuration and can run alongside this connector.