Linking OKTA to Chronicle SecOps Platform
Following on from the previous post on linking Azure IDP to Chronicle SecOps, in this blog post I provide step by step instructions on how to configure authentication to the Chronicle SecOps platform using OKTA IDP.
These instructions can be used for existing Chronicle SIEM customers migrating to BYOID, or for new Chronicle SecOps customers.
It is expected that with the prerequisites in place it will take 30 to 60 minutes to complete the setup. This does not however account for delays that may be a result of organizational requirements, such creating a GCP Project, or enabling a new Cloud service, and such pre-requisites should be reviewed before starting.
Prerequisites Checklist
- If you are a new Google Cloud Platform customer please contact your GCP Account before starting this process as pre-configuration steps are required to be made by Google on the SaaS side
- You have linked a GCP Project to your Chronicle SecOps tenant.
- For the OKTA setup stage you will need to be logged into your OKTA console as a user with permissions to create a new Application, and Group(s).
- For the Chronicle SecOps setup stage you will need to be logged into your GCP console as a user with permissions to setup Workforce Identity Federation, and set IAM Principals in the GCP Project bound to your Chronicle SecOps tenant.
- You have decided upon a GCP Workforce Identity Federation (WIF) Pool ID and Provider ID. These will be needed to create the ACS and Entity ID URL in the OKTA Application, and as part of the WIF setup which is performed after the OKTA Application setup steps.
OKTA IDP Setup
Creating Groups
It is best practice to use Groups rather than individual User accounts for access management to your Chronicle SecOps tenant. These Groups will be assigned to the OKTA Application as part of the setup, and used for Feature RBAC authorization in Chronicle SecOps.
Below are the default Roles available in Chronicle SecOps, and suggested OKTA Group mappings:
| Chronicle SecOps Role | OKTA Group (Suggested) |
|-----------------------|-------------------------|
| Chronicle API Admin | chronicle_secops_admins |
| Chronicle API Editor | chronicle_secops_editor |
| Chronicle API Viewer | chronicle_secops_viewer |📝 Note, Group names are created using underscores instead of spaces as otherwise you cannot assign the Group in GCP IAM in later steps using the GUI. If you do have Groups with spaces follow the steps for using the gcloud command line utility.
To create Groups within the OKTA console navigate to “Directory”, “Groups”
Click “Add Group”
Under “Name” enter the Name of the group(s) to be used in Chronicle SecOps, and optionally a “Description”
Click “Save”
Decide upon WIF Pool and Provider ID values
See Configure Chronicle with a third-party identity provider for a detailed explanation of Workforce Identity Federation workings, and prerequisites, but for the scope of these setup instructions the important elements are to decide upon a Pool ID and Provider ID value, as these will be required in order to create your OKTA Application, and the same values must be used later on during the WIF setup in GCP.
It is recommended to use a naming syntax that matches your Organizational requirements, but for the purpose of these instructions the format of tenanturl-component will be used. Where you see the below placeholder variables in further steps replace as required to match your environment.
WORKFORCE_POOL_ID=thatsiemguy-okta-pool
WORKFORCE_PROVIDER_ID=thatsiemguy-okta-provider📝 Note, the Pool IP and Provider ID must be consistently applied in both OKTA and GCP, and can’t be changed once deployed!
OKTA Application Setup
Within OKTA sign in as an administrative user with the permission to create a new Application.
Click the “Create App Integration” button
Under “Create a new app integration” select “SAML 2.0” and click “Next”
Within the “Create SAML Integration” page, under “1 General Settings”, enter:
- App name: <Your OKTA App name, e.g., ACME Chronicle SecOps>
- App logo: <optional>
- App visibility: <configure as needed>
💡 Tip, you can get a Chronicle Logo from this URL: https://marketplace-api.looker.com/block-icons/chronicle.png
Under “2 Configure SAML” configure the input fields as follows:
- Under “Single sign-on URL” enter the ACS URL that matches your Chronicle SecOps tenant, e.g.,
https://auth.backstory.chronicle.security/signin-callback/locations/global/workforcePools/<WORKFORCE_POOL_ID>/providers/<WORKFORCE_PROVIDER_ID>- Under “Audience URI” enter the SP Entity ID that matches your Chronicle SecOps tenant, e.g.,
https://iam.googleapis.com/locations/global/workforcePools/<WORKFORCE_POOL_ID>/providers/<WORKFORCE_PROVIDER_ID>- “Default RelayState” should be the URL of your Chronicle tenant, and is required for IDP initiated login
- Under “Name ID format” select “EmailAddress”
- Under “Application username” select “Email”
Under “Attribute Statements“ configure the Name and Value pairs as follows:
| Name | Name Format | Value |
|--------------|-------------|-------------------------------------|
| subject | Unspecified | user.email |
| emailaddress | Unspecified | user.email |
| name | Unspecified | user.firstName " + + " user.lastName|
| first_name | Unspecified | user.first_name |
| last_name | Unspecified | user.last_name |Under “Group Attributes Statements” add a Name and Filter value that matches your configured Groups in OKTA Directory.
| Name | Name Format | Filter | |
|--------|-------------|----------|------------------|
| groups | Unspecified | Contains | chronicle_secops |Optionally, you can “Preview the SAML Assertion”, otherwise click “Next”
💡Tip, previewing the SAML Assertion can be used to verify the mappings are working as intended, and removes the need for performing a manual SAML trace with your web browsers inspect utility.
Under “Help Okta Support understand how you configured this application” select “I’m an Okta customer adding an internal app”, and under “App type” select “This is an internal app that we have created”.
Click “Finish”
From the Sign-on tab in your newly created OKTA Application for Chronicle SecOps, under “Settings” open the “Metadata URL” in a new tab, and download the XML file. This is needed for creating a WIF Pool and Provider in the next section.
Assign Users & Groups to the Application
Grant Users or Groups access to the Application from the “Assignments” tab.
Click “Assign”, select “Assign to Groups”, and Search for the Groups that should be assigned.
Click “Assign” from the results to assign the Group(s) to the Application.
Click “Done” when finished.
Creating the Workforce Identity Federation (WIF) Integration for Chronicle SecOps
GCP WIF Setup
Logged in as an Administrator user in the GCP console, click “Menu”, “IAM & Admin”, and “Workforce Identity Federation”
If you see the prompt “Page not viewable for projects. This feature requires an organization” click “SELECT” for your GCP Organization name.
Click “CREATE POOL”
Under “Name” enter a name for your WIF Pool.
⚠️ Note, this must match that value you specified earlier on when creating your OKTA Application, and must be less than 32 characters in length.
Optionally, under “Description” enter a description of the Pool, e.g, what it is for, who set it up, and when.
Optionally, under “Session Duration” change the session duration to 12 hours. This will impact how often an authentication refresh occurs when using the Chronicle SecOps user interface.
Leave “Enabled Pool” as on.
Click “Next”
A WIF Pool will be created, which can take several minutes.
Under “Select a provider” choose “SAML”, and click “SUBMIT”
Under “1 Create a pool provider” enter a “Name”
⚠️ Note, this must match that value you specified earlier on when creating your OKTA Application, and must be less than 32 characters in length.
Optionally, under “Description” enter a description of the Pool Provider, e.g, what it is for, who set it up, and when.
Upload the OKTA Application XML file download from the OKTA console in a prior step.
Click “Continue”
Under “2 Configure provider”, within the “Attribute Mapping” section complete as follows:
| Google X (where X is a number) | SAML x (where X is a number) |
|-------------------------------- |------------------------------------ |
| google.subject | assertion.subject |
| google.display_name | assertion.attributes.name[0] |
| google.groups | assertion.attributes.groups |
| attribute.first_name | assertion.attributes.first_name[0] |
| attribute.last_name | assertion.attributes.last_name[0] |
| attribute.user_email | assertion.attributes.emailaddress[0]|Use the “ADD MAPPING” button to add new mapping pairs.
Note, the groups and subject entries should not have an ordinal value, e.g., [0], but all other entries should end in [0].
Click “SUBMIT”
The provider will be created and this process will take a few seconds to complete.
The setup for GCP WIF is now complete.
Setup Authorization in GCP IAM
The authorization for which Features or Data a User or Group can access is set by the IAM (Identity & Access Management) Roles configured in the GCP Project bound to your Chronicle SecOps tenant.
| OKTA Group (Suggested) | Type | Principal Set |
|--------------------------|-------|----------------------------------------------------------------------------------------------------------------------|
| chronicle_secops_admins | Group | principalSet://iam.googleapis.com/locations/global/workforcePools/<WORKFORCE_POOL_ID>/group/chronicle_secops_admins |
| chronicle_secops_editors | Group | principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID>/group/chronicle_secops_editor |
| chronicle_secops_viewers | Group | principalSet://iam.googleapis.com/locations/global/workforcePools/<WORKFORCE_POOL_ID>/group/chronicle_secops_viewers |📝 Note, if you are unsure of how the Group names are returned see the section on performing a SAML trace to verify the correct Group name format.
In your GCP Console navigate to the Menu button, “IAM & Admin”, and “IAM”
Click “GRANT ACCESS”
Under “Add Principals” paste the Principal Set value for each Group and Role combination.
⚠️ Note, as soon as you paste text into the GUI field it becomes uneditable, so you need to have the correct principal value before pasting into the UI
Under “Assign roles” click the “Role” field, search for “Chronicle API <role>”, e.g., Chronicle API Admin, and click the result to select it
Click the “Save” button.
Repeat the above process for the remaining Group and roles you wish to assign to your Chronicle SecOps instance, i.e., Editors and Viewers.
Adding Groups & Users using gcloud (Group names with Spaces)
If your OKTA Group Names include a space you will need to use the gcloud command line utility via the GCP Cloud Shell console to add AIM access permissions. ️
⚠️️️️ The GCP IAM UI does not support adding Groups with spaces at the time of writing
Before running any WIF commands in Cloud Shell you must run the following command, remembering to change to use your GCP Project ID:
gcloud config set billing/quota_project <GCP_PROJECT_ID>To assign a Group, remembering to change to use your GCP Project ID, specify the appropriate IAM Role, and updated principalSet value:
gcloud projects add-iam-policy-binding <GCP_PROJECT_ID> \
--role roles/chronicle.<ROLE> \
--member "principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP NAME"
This will successfully add a Group to GCP IAM including a Space.
Finalize Setup
Once you have completed the above step to create a GCP WIF Pool and Provider, either:
- Proceed to complete the onboarding Wizard as provided to you by your Chronicle account team
- If you have an existing Chronicle SecOps tenant, provide your Chronicle account team or Chronicle Partner the WORKFORCE POOL ID and WORKFORCE PROVIDER ID so they can complete the final part of the setup process.
You will not be able to login until this step is completed.
Verification
To verify the setup is working go to your Chronicle SecOps tenant in a web browser
- Verify you are able to login
- Click “Settings”, “Profile” and view the Group(s) returned by your IDP match as expected
- If you see “No groups assigned” under “IDP Groups” please refer to the Troubleshooting section. This could mean either you have no IDP groups configured, or a configuration issue relating to your IDP groups in OKTA or WIF.
An example of where no IDP groups are returned into Chronicle SecOps
Troubleshooting
While you can use a Chrome or Edge extension to perform a SAML trace, as documented at the bottom of this prior blog post, you can use the Preview Assertions in the OKTA app.
App Not Assigned
If you see App Not Assigned check you have assigned a user or group to the OKTA application.
Target Service Indicated by Audience Parameter is invalid
The SP Entity or ACS URL has an invalid value in the Workforce Pool or Workforce Pool Provider. Verify Workforce Pool values under “Single sign-on URL” and “Audience URI” in your OKTA Application.
400 Request is malformed
This can happen if launching the application from within OKTA and you have not configured a “Default RelayState” value, i.e., your Chronicle Tenant URL
Summary
If you have feedback, questions, notice any errors, or want to provide feedback on the above please send a message or post a comment.
