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.
-
Breadcrumb and header:
Connectors / Oktaat the top links back to the catalogue. Below it sits the titleOkta Connectorand a one-line description. - Sign-in result banner: After you return from Okta, a green banner confirms the connection, or a red banner explains why authorisation failed.
-
Connection Status panel: A coloured dot and label show the state:
Not Tested,Testing...,Connected,Connection FailedorSyncing.... Until the configuration is saved, the panel readsConfigure settings below to connect.Once it is saved, the panel holdsTest Connection, plusAuthorize with Oktawhen OAuth still needs consent andSync System Logwhen the connection is live. Unlike most connector pages, this panel sits above the form. -
Sync Results: After a sync, two tiles show how many events were
ImportedandSkipped, with a line counting any errors. -
Configuration: The form with
Organization URL,Authentication Modeand the credential fields for the chosen mode, and aSave Configurationbutton. - Setup Instructions and Sync Features: Two boxes at the bottom: step lists for preparing Okta in each mode, and a short list of what the sync does.
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
-
In the Okta Admin Console, go to
Applications > Applicationsand selectCreate App Integration. The integration wizard opens. -
Choose
OIDC - OpenID ConnectandWeb Application. Okta asks for the application's settings. -
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. - Copy the Client ID and Client Secret. Keep them ready for the Aegis form.
-
Under the app's Okta API scopes, grant
okta.logs.readandokta.users.read. The app can now be authorised by Aegis.
API token
-
In the Okta Admin Console, go to
Security > API > Tokensand selectCreate Token. Okta asks for a name. - Name the token and confirm. Okta shows the token value once only; copy it straight away.
Configure the connector
-
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. -
Enter the
Organization URL, your Okta organisation's base address such ashttps://company.okta.com, with no trailing path. -
Choose the
Authentication Mode:OAuth 2.0 (Recommended)orAPI Token. The credential fields change to match:Client IDandClient Secretfor OAuth, or a singleAPI Tokenfield. -
Fill in the credentials and select
Save Configuration. The button stays disabled until the address and the credential for the chosen mode are present. AConfiguration savedmessage appears and the status returns toNot 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
-
In OAuth mode, select
Authorize with Oktain the Connection Status panel. Your browser goes to your Okta sign-in and consent screen. If the button is not showing, selectTest Connectionfirst: when authorisation is missing it reports so and the button appears. -
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. -
Select
Test Connection. The label changes toTesting.... On success a green box showsConnected to Okta, with the organisation name, the subdomain andSystem Log Access: Available. On failure the status readsConnection Failedwith 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
-
With the status at
Connected, selectSync System Log. The status changes toSyncing...while Aegis reads Okta. -
Read the
Sync Resultstiles that appear.Importedcounts new audit-log entries;Skippedcounts events already imported by an earlier sync, recognised by their Okta event ID. A red line counts any events that could not be stored. - 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
- When the Okta address changes after authorising, the stored token is not sent to the new address: authorise again.
-
A stored client secret or API token stays bound to the address it was
entered for. To save a new
Organization URL, enter the secret again in the same save; otherwise the save is refused with a general error message and the refusal is audited. -
Each sync reads at most 100 events from the last 24 hours. A busy
organisation produces more than that in a day, so sync often; repeated syncs
skip what they already hold. A wider or different window is available only
through the API's
sincedate. -
The
Sync System Logbutton only shows while the status isConnected. If the page showsNot Tested, test the connection first. -
A sync that imports nothing usually means the credential lacks
okta.logs.read, or there was no activity in the window. -
The page's own OAuth setup steps mention only
okta.logs.read; grantokta.users.readas well, because Aegis asks for both. - Okta events become audit records, not incidents or evidence. Raise an incident yourself when an event needs one; Aegis does not do it for you.
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.