Okta
Okta is an identity and single sign-on service. In order to collect data from Okta, you will need to authorize InsightIDR to access your Okta administrator account.
The event types that InsightIDR parses from this event source are:
- Cloud Service Activity
- Cloud Service Admin Activity
- Ingress Authentication
- Third Party Alert
- SSO
There are two ways to send data from your Okta account to InsightIDR; event collection through the Cloud or through an on-premises Rapid7 Collector.
Cloud event sources are being phased in from December 2023
InsightIDR is adding cloud event collection capabilities to a select number of supported event sources; this one is included. This will be a phased release, so if your environment is not yet displaying the Run on Cloud option, please be patient–your environment will update shortly.
To set up the Okta event source, complete these steps:
- Read the requirements and complete any prerequisite steps.
- Configure Okta to send data to InsightIDR.
- Configure InsightIDR to receive data from the event source.
- Test the configuration.
You can also:
Requirements
Before you start the configuration:
- Ensure you have Okta administrator privileges with 'Read-Only' permissions or higher.
- It is recommended that you create an Okta service account, so that you can create API tokens and assign the tokens the required privilege levels.
- Learn more about creating API tokens by visiting the Okta documentation at: https://developer.okta.com/docs/guides/create-an-api-token/main/
Configure Okta to send data to InsightIDR
To send data to InsightIDR, you must create an API token in Okta with a user account that is enrolled in multi-factor authentication (MFA).
Okta uses a bearer token for API authentication with a sliding scale expiration. Tokens are valid for 30 days and automatically refresh with each API call. Tokens that are not used for 30 days will expire. The token lifetime is currently fixed and cannot be changed for your organization. Deactivating a user account in Okta will simultaneously deprovision the associated API tokens.
To create an API token in Okta:
- Log in to Okta and select API from the Security menu.
- Click the Create Token button. The token inherits the permissions of the user account used to create the token.
- Follow the instructions that the Okta screen displays to finish creating the token.
- Record the Token value to enter later in InsightIDR.
Configure InsightIDR to receive data from the event source
After you complete the prerequisite steps and configure the event source to send data, you must add the event source in InsightIDR.
Task 1: Select Okta
- From the left menu, go to Data Collection and click Setup Event Source > Add Event Source.
- Do one of the following:
- Search for Okta in the event sources search bar.
- In the Product Type filter, select Cloud Service.
- Select the Okta event source tile.
Task 2: Set up your collection method
There are two methods of collecting data from Okta: through a cloud connection or through a collector.
New credentials are required for cloud event sources
You cannot reuse existing on-premise credentials to create a cloud connection with this event source. You must create new credentials.
Use the Cloud Connection method
- In the Add Event Source panel, select Run On Cloud.
- Name the event source. This will be the name of the log that contains the event data in Log Search. If you do not name the event source, the log name will default to Okta.
- Optionally choose to send unparsed data.
- Select your Account Attribution preference:
- Use short name attribution: The system first attempts to attribute data by email address, for example,
jsmith@myorg.example.com
. If the first attempt is unsuccessful, attribution is attempted by short name, for example,jsmith
. If the short name is unsuccessful, attribution is attempted by a user’s first and last name, for example,John Smith
. - Use fully qualified domain name attribution: The system first attempts to attribute data by email address, for example,
jsmith@myorg.example.com
. If the first attempt is unsuccessful, attribution is attempted by a user’s first and last name, for example,John Smith
. This option is best if your environment has collisions with short names.
- Use short name attribution: The system first attempts to attribute data by email address, for example,
- Optionally, in a multi-domain environment, use the dropdown menu to select your main Active Directory domain. See Deploy in Multi-domain Environments and Advanced Event Source Settings.
- Click Add a New Connection.
- In the Create a Cloud Connection screen, enter a name for the new connection.
- In the Domain field, enter your Okta domain. For example,
mydomain.okta.com
. - In the API Token field, add a new credential:
- Name your credential.
- Describe your credential.
- Select the credential type.
- Enter the API Token you created in Configure Okta to send data to InsightIDR.
- Specify the product access for this credential.
- Click Save Connection.
- Click Save.
Use the Collector method
- In the Add Event Source panel, select Run On Collector.
- Name the event source. This will be the name of the log that contains the event data in Log Search. If you do not name the event source, the log name will default to Okta.
- Select your collector.
- Optionally choose to send unparsed logs.
- Select your Account Attribution preference:
- Use short name attribution: The system first attempts to attribute data by email address, for example,
jsmith@myorg.example.com
. If the first attempt is unsuccessful, attribution is attempted by short name, for example,jsmith
. If the short name is unsuccessful, attribution is attempted by a user’s first and last name, for example,John Smith
. - Use fully qualified domain name attribution: The system first attempts to attribute data by email address, for example,
jsmith@myorg.example.com
. If the first attempt is unsuccessful, attribution is attempted by a user’s first and last name, for example,John Smith
. This option is best if your environment has collisions with short names.
- Use short name attribution: The system first attempts to attribute data by email address, for example,
- Optionally, in a multi-domain environment, use the dropdown menu to select your main Active Directory domain. See Deploy in Multi-domain Environments and Advanced Event Source Settings.
- Select your Okta credential or optionally create a new credential.
- Enter the refresh rate in minutes.
- Select your Okta domain.
- Click Save.
Test the configuration
The event types that InsightIDR parses for this event source are:
- Cloud Service Activity
- Cloud Service Admin Activity
- Ingress Authentication
- Third Party Alert
- SSO
To test that event data is flowing into InsightIDR:
- View the raw logs.
- From the Data Collection Management page, click the Event Sources tab.
- Find the event source you created and click View raw log. If the Raw Logs modal displays raw log entries, logs are successfully flowing to InsightIDR.
- Use Log Search to find the log entries. After approximately seven minutes, you can verify that log entries are appearing in Log Search.
- From the left menu, go to Log Search.
- In the Log Search filter, search for the new event source you created.
- Select the log sets and the log names under each log set. Okta logs flow into these log sets:
- Cloud Service Activity
- Cloud Service Admin Activity
- Ingress Authentication
- Third Party Alert
- SSO
- Set the time range to Last 10 minutes and click Run.
The Results table displays all log entries that flowed into InsightIDR in the last 10 minutes. The keys and values that are displayed are helpful when you want to build a query and search your logs.
Sample logs
In Log Search, the logs that are generated use the name of your event source by default. The logs appear under the log sets:
- Cloud Service Activity
- Cloud Service Admin Activity
- Ingress Authentication
- Third Party Alert
- SSO
To help you visualize the event logs that this event source generates, here are some sample logs:
Sample Cloud Service Activity log
1{2"actor": {3"id": "00usc691qiqVlkrGS4x6",4"type": "User",5"alternateId": "jdoe@rapid7.com",6"displayName": "John Doe",7"detailEntry": null8},9"client": {10"userAgent": {11"rawUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36 Edg/87.0.664.66",12"os": "Windows 10",13"browser": "CHROMIUM_EDGE"14},15"zone": "null",16"device": "Computer",17"id": null,18"ipAddress": "123.123.123.123",19"geographicalContext": {20"city": "Locust",21"state": "North Carolina",22"country": "United States",23"postalCode": "12345",24"geolocation": {25"lat": 12.3456,26"lon": 12.345627}28}29},30"authenticationContext": {31"authenticationProvider": null,32"credentialProvider": null,33"credentialType": null,34"issuer": null,35"interface": null,36"authenticationStep": 0,37"externalSessionId": "102lPQA_HRdTt-nJFsYZN8J2Q"38},39"displayMessage": "Evaluation of sign-on policy",40"eventType": "policy.evaluate_sign_on",41"outcome": {42"result": "ALLOW",43"reason": "Sign-on policy evaluation resulted in ALLOW"44},45"published": "2020-11-17T16:36:00.000Z",46"securityContext": {47"asNumber": 7018,48"asOrg": "rapid7 corp.",49"isp": "rapid7 services inc",50"domain": "rapid7.net",51"isProxy": false52},53"severity": "INFO",54"debugContext": {55"debugData": {56"deviceFingerprint": "8d7a281abc23d961872dfc3a0d129a9f",57"requestId": "X-Ji56SmJCbGJJK1G7K1XwAAC8A",58"requestUri": "/api/v1/authn",59"threatSuspected": "false",60"url": "/api/v1/authn?"61}62},63"legacyEventType": null,64"transaction": {65"type": "WEB",66"id": "X-Ji56SmJCbGJJK1G7K1XwAAC8A",67"detail": {}68},69"uuid": "cc40cc88-4e24-11eb-9c9a-2b8966420021",70"version": "0",71"request": {72"ipChain": [73{74"ip": "123.123.123.123",75"geographicalContext": {76"city": "Locust",77"state": "North Carolina",78"country": "United States",79"postalCode": "12345",80"geolocation": {81"lat": 12.3456,82"lon": 12.345683}84},85"version": "V4",86"source": null87}88]89},90"target": [91{92"id": "00pupqnz5ePXMPvcn4x5",93"type": "PolicyEntity",94"alternateId": "unknown",95"displayName": "Default Policy",96"detailEntry": {97"policyType": "OktaSignOn"98}99},100{101"id": "0prupqo0cxJHYa6B54x5",102"type": "PolicyRule",103"alternateId": "00pupqnz5ePXMPvcn4x5",104"displayName": "Default Rule",105"detailEntry": null106}107]108}