Having recently completed a complex SAML 2.0 integration for our Chronicle instance to onboard a large analyst team, I found the official documentation somewhat lacking in the nuanced, practical details required for proper role mapping. The core challenge wasn't enabling SSO itself, but ensuring that our pre-defined Chronicle roles (Viewer, Investigator, Administrator, etc.) were correctly assigned based on attributes passed from our Identity Provider (in our case, Okta). Here is a detailed breakdown of the process and the critical configurations.
**Key Prerequisite: Chronicle Role Setup**
First, ensure your Chronicle roles are configured within the Google Cloud Console under IAM & Admin > IAM. Chronicle-specific roles follow the pattern `chronicle.` (e.g., `roles/chronicle.viewer`). You must have the Organization Admin role in Chronicle to map these.
**Identity Provider Configuration (Okta Example)**
The IdP must be configured to send a SAML assertion with the necessary attributes. The pivotal attribute for role mapping is ` https://schemas.google.com/Chronicle/Role`. Its value must be the full IAM role path.
*Okta SAML Attribute Statements Configuration:*
```xml
roles/chronicle.investigator
{{user.email}}
{{user.login}}
```
**Chronicle Side Configuration via Google Cloud IAM**
This is the most nuanced step. You are not configuring SSO within Chronicle's UI directly, but rather creating a SAML 2.0 provider in Google Cloud IAM for your organization and mapping the incoming attribute.
1. In Google Cloud Console, navigate to **IAM & Admin > Identity Platform**.
2. Create a new SAML 2.0 provider for your organization. Upload your IdP's metadata XML.
3. In the **Attribute Mapping** section, you must map the `Attribute name` from your SAML response (e.g., ` https://schemas.google.com/Chronicle/Role`) to the Google-internal field named `role`.
4. Crucially, the mapping must be `role=[ATTRIBUTE_NAME]`. The `[ATTRIBUTE_NAME]` is the exact name of the attribute in your SAML assertion.
**Common Pitfalls & Validation**
- **Attribute Format:** The role value must be the *full* IAM role path. Sending just "investigator" will fail.
- **Multiple Roles:** If an analyst needs multiple roles, the SAML attribute should contain multiple `` elements, one for each role path.
- **Default Role:** Consider assigning a baseline, low-privilege role (like `roles/chronicle.viewer`) via a default mapping in Google Cloud IAM for users who lack the attribute, as a safety measure.
- **Testing:** Use the "Test SAML login" feature in the Google Cloud IAM SAML provider configuration extensively. Inspect the returned attribute mapping before going live.
The integration has now automated the provisioning and de-provisioning of analyst access with precise, auditable role assignments, significantly reducing administrative overhead. The key was treating this not just as an SSO project, but as a role-based access control (RBAC) automation project where SAML attributes serve as the carrier for role assignments.
API first.
IntegrationWizard
Your focus on the ` https://schemas.google.com/Chronicle/Role` attribute is spot on. I've seen implementations fail because they used a shorthand or just the role name, but as you point out, the full IAM path is mandatory.
One nuance I'd add is that the attribute statement in Okta must be configured with a `Format` of `Unspecified`, not `Basic` or `URI`. Some IdPs default to a format that SAML validators accept, but Chronicle's SP side can be strict and will reject the assertion if the format is incorrectly set, even if the value looks right. Your XML snippet appears to be truncated mid tag, which is a common copy paste error from the Okta UI that can lead to frustration.
Also, remember that these role assignments are not dynamic after the initial SAML handoff. If you need to change a user's Chronicle role, you must update the attribute value in Okta and the user must re initiate the SSO flow; a simple refresh within Chronicle won't re evaluate their permissions.
null
Your point about the `Format` being `Unspecified` is critical. I've traced several support tickets back to that exact IdP configuration mismatch, where the attribute value was transmitted but silently dropped due to a format mismatch, leaving the user with a default, often insufficient, role.
The static nature of the role assignment post handshake is a significant architectural consideration. It means your provisioning logic in the IdP must be the single source of truth for access control, and any role change requires a documented process forcing a fresh SAML flow. For larger teams, we automated this by setting a short lived, forced re authentication policy in Okta for users whose role attribute was changed, ensuring the new permissions were picked up at their next login without manual intervention.
One additional caveat on the attribute value: while the full IAM path like `roles/chronicle.investigator` is required, some teams have tried to pass multiple roles in a single assertion, hoping for a union of permissions. Chronicle's SP does not support this; it will typically take the first value it finds or fail. If a user needs multiple pre defined roles, a custom role combining those permissions must be created in Google Cloud IAM first and then assigned via the SAML attribute.
—BJ