Okta Logs
The Emanate Security Platform supports the ingestion of the Okta System Logs and user directory.
Overview
This guide walks you through connecting your Okta tenant to the Emanate Security Platform. The integration uses an Okta API token (SSWS token) to securely retrieve identity data and audit logs.
The setup requires:
Creating a Custom Read-only Admin Role
Creating a Resource Set
Creating a Service Account
Assigning the Custom and Read-only Administrator role
Generating an Okta API Token (SSWS token)
Adding your Okta API Token into the Emanate Security UI.
The entire process takes approximately 10–15 minutes.
Creating a dedicated service account for this integration is optional but strongly recommended. Okta SSWS API tokens inherit the permissions of the administrator account that creates them, so using a separate service account helps isolate the token’s access and avoids tying the integration to a personal administrator account. This approach follows Okta’s recommended best practice for managing API tokens and supports a least-privilege security model.
Required Permissions
The integration requires read-only access to the following data elements:
Users and user attributes
Groups and group membership
Applications and integrations
Administrative roles and assignments
Identity and Access Management configuration
System Logs (sign-in events and audit logs)
Write access is not required.
Step 1: Create a Custom Admin Role
First create a custom role that allows read-only access to identity configuration and administrative assignments.
Navigate to the Okta Admin Console and Select Security and then Administrators from the left navigation pane.
Once on the Administrators page open the Roles tab and click 'Create new role'.
Add a memorable Role Name like the one below
Add the following permissions:
User
View users' profile attributes
View users and their details
View API tokens
Group
View groups and their details
Application
View applications and their details
Identity and Access Management
View roles, resources, and admin assignments
Agents
View agents
When you're done, the Role Preview should look like this. Save the role.
Step 2: Create a Resource Set
Next create a resource set will be used to scope the role to data that covers your entire organization.
On the Administrators page navigate to the Resources tab and click 'Create new resource set'.
Add a memorable resource set name like the one below.
Add the following resources:
Users: All users
Applications: All applications
Groups: All groups
Identity and Access Management: All IAM resources
When you've added the correct resources, your resource set should look like the screenshot below. Click 'Create' to finalize the resource set.
Step 3: Create a Service Account
The API token should be generated from a dedicated service account rather than a personal administrator account. Follow the instructions to create a new dedicated service account.
In the Okta Admin console, navigate to Directory and then People in the left navigation pane.
Once you're on the People page, create a new account by selecting the 'Add person' button.
When creating this account up, be sure to:
Select the 'I will set password' check box and enter a strong password. If you don't do this, Okta will send a registration email to the email address you've included and you won't be able to access this account without retrieving that email.
Enroll at least one MFA factor.
Exclude the account from any unintelligent automated de-provisioning processes.
Step 4: Assign Administrative Roles
Now assign the required admin roles to the service account.
Navigate back to the Administrators page by selecting Security and Administrators in the left navigation pane.
On the Administrators page, go to the Admins tab and click 'Add administrator'
Select the service account you created earlier.
Assign Roles
Assign the custom role you created:
Select the resource set:
Assign Read-only Administrator Role
Add a second role:
This role provides read-only access to Okta System Logs, as well as the ability to create API Tokens, which are required to retrieve sign-in activity and audit events and complete setup of the integration.
When you're done the configuration screen should look something like the screenshot below. Select 'Save changes' to proceed.
Step 5: Generate an Okta API Token (SSWS Token)
Sign out of your personal Admin account and sign in as the service account, using the password you created in step 3, and generate an API token.
Once signed in, navigate to the API page by selecting Security and API in the left navigation pane.
On the API page, go to the Tokens tab and click on the 'Create token' button.
Create a memorable name for your new Token. Something like the one below.
Select 'Any IP' in the call origination setting drop-down. Click 'Create token'.
Copy the generated token immediately. It will not be displayed again.
If the token value is not copied at this point, it cannot be retrieved later. If not copied, you will need to repeat the process to generate a new token. The token value is not the same as the Token ID displayed on the page.
Verify the Token
Verify the token is listed as Active with a green lit icon on the Tokens screen or click the Edit Token icon and verify the token is listed as Active just under the token name in the resulting page.
The token will stay active as long as it is used within a 30-day period and is not manually deactivated by the client. If either of these conditions change, the token becomes invalid, and Emanate systems will not be able to access the API.
Step 6: Provide the Token to Complete the Integration
Sign into the Emanate Security console and add the required details.
Once inside the console, navigate to Integrations and Data Sources in the left navigation pane.
Once on the Data Sources page, enter your Okta Domain and the API Token you created in Step 5.
Okta Domain
If you don't know your okta domain, you can find it in the top right corner of the Okta console by expanding on your signed in user record.
API Token
Paste the SSWS token generated in the previous step.
Security Notes
The token provides read-only access only.
No configuration changes can be made by the integration.
The token inherits the permissions of the service account.
We strongly recommend using a dedicated service account rather than a personal administrator account.
Integration Complete
Once the token is validated, the platform will begin ingesting:
Sign-in activity
Identity lifecycle events
Administrative changes
Application access
Privilege assignments
Initial data synchronization starts with a 90-day rear view lookup and will take several days.
User Profile Format Alignment (optional)
Okta supports a simple “Base” set of user profile attributes, but your organization may have added some custom attributes that you'd like to ingest into Emanate. If custom user fields have been added that are required for Emanate to retrieve and store, it is helpful for clients to provide an example to streamline the mapping process.
To retrieve the user profile format, navigate to the Directory > Profile Editor page.
Select the User Type that will be applicable for Emanate user profile information. This is typically the OKTA User (default) profile type.
Go to the Attributes list on the Profile Editor page.
Select the All option in the filters to view all attributes configured within the profile.
Copy all of the resulting elements from the page to a document or spreadsheet and provide to your Emanate Security representative.
Unfortunately, at present time Okta does not provide an export function, so this is a manual copy/paste process.
Once completing the above steps, and providing the necessary information to your Emanate Security representative, you have finished the API Pull Request setup. Please move on to the Event Hook configuration.
Questions
Please email any questions to [email protected]
Last updated