Okta Activity Logs
The Emanate Security Platform supports direct log ingestion and user directory ingestion from Okta
Overview
Emanate uses two methods for ingesting logs and directory records.
Data Retrieval APIs: Periodic (scheduled) and on-demand requests for data originating in the Emanate platform set to pull information from Okta.
Event Hooks: Real time outbound calls from Okta, sent when specified events occur in your org.
Data Retrieval Configuration
Okta offers an API endpoint that allows external services to request tenant information from Okta.
Access Setup
Log in to the Okta console and Browse to the Security > API section of the User Interface.
Under Authorized Servers, click Add Authorization Server and fill out the form.
Name: Emanate Security API Access
Audience: api://default
Description: Readable description referring to this as the access point for Emanate Security Services
Save the form
Provide the configured information to Emanate Security
Provide the “Issuer URI” value to Emanate Security
The API URL has a client specific sub-domain that must be provided to Emanate. The API endpoint url after the domain is fixed.
Example Issuer URI: https://dev-51174099.okta.com/oauth2/default
Example Okta API url: https://dev-51174099.okta.com/api/v1/users
Generate an Authentication Token
To generate a new persistent token to enable access, browse to the Security > API page and then the Tokens tab.
Click the Create Token button.
Name the token something descriptive to its purpose, such as Emanate Access Token, click ok.
Copy the resulting Token Value by clicking the copy button. Provide this token value to Emanate to use for access. Click ok to close the window.
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.
By default, the new token is granted access to the Okta API for Users, Logs, Groups, and User authentication processing. No additional scopes are needed for standard Emanate processing.
User Profile Format Alignment
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.
Event Hook Configuration
Okta's Event hooks to ingest security events captured by Okta. Event hooks take the form of HTTPS REST calls to a URL you specify, encapsulating information about the events in JSON objects in the request body.
How to Integrate Okta with Emanate Security
Okta supports a ‘push’ mechanism to publish/push event logs to an HTTP endpoint. In order to configure your Okta environment to send these events to the Emanate Security Platform, please follow the below steps:
Step 1: Navigating Okta
Login to the Okta Administrative Interface.
Navigate to Workflow -> Event Hooks
Step 2: Create an Event Hook
Click ‘Create Event Hook’
Enter the required values according to the below instructions:
Name: Select a friendly & recognizable name for this integration. Something like Emanate Security Event Stream usually works well.
URL: Enter the following URL for the Emanate Security Platform API Gateway. This is the endpoint that will receive the Okta event logs.
Custom Header Fields: Within Custom header fields, create a field titled tenant_UUID. Contact your Emanate Security Account Representative for the tenant_UUID value that corresponds to your Emanate Security Subscription.
Step 3: Add Event Subscriptions
In the Subscribe to events section, add the following events:
Authentication of user via MFA
User sign in attempt
A User's admin privileged changed
User's MFA factor activated
User's MFA factor updated
User's MFA factor deactivated
These events will support Emanate Security's complete library of automated response functions. In order to support future automations, additional event subscriptions may be needed.
Select Save & Continue
Step 4: Verify Ownership
Select the Verify button to complete your integration.
If the APIGW integration is setup correctly, Okta will now start pushing the specified events to your account in the Emanate Security Platform.
Questions
Please email any questions to support@emanatesecurity.com
Last updated
