SAML Protocol

After you connect your existing identity provider to Immuta, users can authenticate to the Immuta application through the SAML protocol.

Beyond authentication, you can configure SCIM or an external user info endpoint so that Immuta can ingest groups and attributes already assigned to your users. Then, you can use that user metadata to author access control policies.

This reference guide outlines details about the configuration options available for SAML.

Configuration options

The following options are available when setting up an identity provider that uses the SAML 2.0 protocol.

• Allow identity provider initiated single sign-on: When enabled, users authenticate once in their identity provider and can log in to Immuta.

• Allow identity provider initiated single logout: When enabled, users can log out of Immuta or their identity provider and simultaneously log out of other applications. Additional configuration settings will appear when this checkbox is selected:

  • Logout URL: The URL of your single sign-on application that will be redirected to after you log out of Immuta, as some identity providers differentiate between the logout and authorization URLs.

  • SLO binding URL: The URL Immuta displays that you can add to your identity provider to specify where to send requests or responses to Immuta's SLO requests.

• Allow Immuta attributes to be applied to SAML users and groups: Attributes created in Immuta can be added to your users and groups in your identity provider.

• Allow SAML users to be added to Immuta groups: This allows you to create groups in Immuta and add SAML users to those groups.

• Attribute schema: Map SAML attributes into Immuta after you enable sync attributes from SAML to Immuta.

• Decryption private key: The private key for decrypting attribute assertions from the identity provider.

• Encryption private key: An optional private key to encrypt requests.

• Entry point: The URL of your single sign on application that the Immuta login page will redirect to.

• External groups and attributes endpoint: Immuta uses this REST endpoint to retrieve a user's groups and attributes from an external IAM service.

  • Sync REST attributes: Ingest user attributes from the external IAM service into Immuta.

  • Sync REST groups: Ingest user groups from the external IAM service into Immuta.

  • Use authentication: Provide credentials Immuta will use to connect to the external IAM service.

  • Enable SSL: Use SSL to protect credentials during login.

• Issuer: The URL of the identity provider that issues assertions for authentication.

• Migrate users: Migrate users from a previously configured identity provider to the current identity provider being configured in Immuta.

• Profile schema: Map attributes from your identity provider to automatically fill in a user’s Immuta profile.

• SCIM support: When enabled, your identity provider automatically creates new users in Immuta and updates existing user accounts, whether or not users log in to Immuta. When you click this checkbox, Immuta generates a SCIM API key.

• Signing certificate: Your identity provider's public signing certificate.

• Sync attributes from SAML to Immuta: Allows attributes added in your identity provider to be synced with Immuta.

  • Attribute delimiter: The character used to split values in a string of attributes. After enabling sync attributes, providing delimiters for attributes is required.

  • Attribute prefix: The prefix used for attribute keys.

• Sync groups from SAML to Immuta: Allows groups added in your identity provider to be synced with Immuta.

  • Group attribute: The attribute that contains the user's group.

• User ID attribute: The attribute that contains the user's username.

SCIM support

When configuring an identity provider that uses the SAML protocol, you can enable SCIM support. SCIM support allows Immuta to

• Automatically create new users in Immuta as they are created in your identity provider

• Keep existing users up-to-date in your identity provider

See the Identity managers overview for details about SCIM support.

Attribute mapping

If you enable sync attributes from SAML to Immuta, you will configure the attribute schema to define how attributes are mapped in Immuta.

When configuring the attribute schema for SAML (with SCIM disabled), you define the attribute key prefix, the attribute delimiter, and (optionally) the Immuta attribute key that maps to the IAM attribute.

The table below illustrates a sample attribute schema mapping for Taylor, who has the following attribute key-value pairs:

• role:Managers

• dept:Engineering

• location:Washington

Immuta attribute key prefix	Immuta attribute key	IAM attribute	Taylor's resulting attribute key-value pair in Immuta
immutaAuth.	Title	role	immutaAuth.Title:Managers
immutaAuth.	Department	dept	immutaAuth.Department:Engineering
immutaAuth.	OfficeLocation	location	immutaAuth.OfficeLocation:Washington

Once these attributes are pulled into Immuta, policy authors can create global policies using these attributes to automatically enforce access controls for users based on their attributes. Consider the following example:

Only show rows where user possesses an attribute in immutaAuth.OfficeLocation that matches the value in column tagged OfficeLocation on all data sources.

Then, Taylor would only see rows that include the value of her office location (Washington) in the column tagged OfficeLocation.

Attribute mapping with SCIM enabled

For SCIM attribute mapping with SCIM enabled, the attribute prefix is mapped to the relevant SCIM schema.

The Immuta attribute prefix will be prepended to all attribute keys included in that schema. For example, if the SCIM schema urn:immuta:schemas:extension:custom:2.0:User included the attributes Title, employeeNumber, and AccessLevel and was mapped to the Immuta attribute prefix Immuta, the attribute key-value pairs would be pulled into Immuta like this:

• Immuta.Title:x

• Immuta.employeeNumber:x

• Immuta.AccessLevel:x

The table below illustrates a sample attribute schema mapping with SCIM enabled for Taylor, who has the following attribute key-value pairs:

• "role": "Manager"

• "dept": "Engineering"

SCIM schema	IAM Immuta attribute prefix	Taylor's resulting attribute key-value pair in Immuta
urn:immuta:schemas:extension:custom:2.0:User	Title	Title.role:Manager
urn:ietf:params:scim:schemas:core:2.0:User	Immuta	Immuta.dept:Engineering

Once these attributes are pulled into Immuta, policy authors can create global policies using these attributes to automatically enforce access controls for users based on their attributes. Consider the following example:

Only show rows where user possesses an attribute in Immuta.dept that matches the value in column tagged LOB on all data sources.

Then, Taylor would only see rows that include the value of her department (Engineering) in the column tagged LOB.

Group mapping

If you enable sync groups from SAML to Immuta, you will configure the group schema to specify the SAML attribute that contains users' groups. This defines how groups are mapped in Immuta.

When configuring the group schema mapping for SAML (with SCIM disabled), you define the SAML attribute that contains the groups you want Immuta to ingest.

Consider the following SAML users:

• firstName:Taylor, role:Managers, dept:Engineering, location:Washington

• firstName:Alex, role:Intern, dept:Research, location:Ohio

• firstName:Sai, role:Managers, dept:Marketing, location:Oregon

The table below illustrates the groups that Immuta would ingest if an administrator configured the group schema mapping to use the dept SAML attribute to identify the groups to add to Immuta:

SAML user	Resulting group in Immuta
Taylor	Engineering
Alex	Research
Sai	Marketing

Once these groups are pulled into Immuta, policy authors can create global policies using these groups to automatically enforce access controls for users based on their groups. Consider the following example:

Only show rows where user is a member of a group that matches the value in column tagged Department on all data sources.

Then, Taylor would only see rows that include the value of her group (Engineering) in the column tagged Department.

Single sign-on

Immuta's SAML integration supports the identity-provider-initiated authentication flow single sign-on method.

SAML single logout

The SAML 2.0 single logout (SAML SLO) protocol allows identity providers to terminate sessions across a user's applications nearly simultaneously with a single logout request.

SAML SLO enabled in Immuta can minimize security risks by terminating abandoned sessions after a timeout event occurs or after a user logs out of their identity provider or another application. Once users are logged out of Immuta, they must re-authenticate to log back in.

Immuta's SAML SLO support has been tested with the following identity providers:

• Key Cloak

• Microsoft Entra ID

• Okta

See your identity provider's documentation to determine whether or not your provider supports SAML SLO. For a list of identity providers and protocols supported by Immuta, see the identity management support matrix.

Logout processes

Immuta cannot ensure that other service providers will log out, as Immuta has no control over those applications.

There are two logout processes for SAML SLO:

• Application-initiated logout: A user logs out from a service provider.

• Identity-provider-initiated logout: A user logs out from their identity provider.

User initiates logout from Immuta

SAML SLO protocol	Example
1. The principal requests to log out of the service provider, or a timeout event initiates a logout request.	1. User logs out of Immuta.
2. The service provider sends a logout request to the session authority.	2. Immuta sends a logout request to Okta and terminates the user's Immuta session.
3. The session authority validates the signature and data in the request and sends a logout request to all the service providers for the current authenticated session (except the service provider from which the logout was initiated).	3. Okta validates the signature and data in the request and sends a logout request to all the other applications the user is logged in to.
4. The service providers terminate the sessions and send logout responses to the session authority indicating that the user has been logged out.	4. The other applications validate the signature and the data in the request and terminate the user's sessions in their application.
5. The session authority ends its own session with the principal.	5. Okta terminates its own session with the user.
6. The session authority sends a logout response message to the service provider from which the logout was initiated.	6. Okta sends a logout response message to Immuta.

User initiates logout from the identity provider

SAML SLO protocol	Example
1. The principal requests to log out of the session authority, or a timeout event initiates a logout request.	1. User logs out of Okta.
2. The session authority validates the signature and data in the request and sends a logout request message to all the service providers for the current authenticated session.	2. Okta validates the signature and data in the request and sends a logout request to all applications the user is logged in to.
3. The service providers validate the signature and data in the request and terminate the sessions.	3. Immuta and other applications validate the signature and data in the request and terminate the user's sessions.
4. The service providers terminate the sessions and send logout responses to the session authority indicating that the user has been logged out.	4. Immuta and other applications send a logout response to Okta to indicate the user has been logged out.
5. The session authority ends its own session with the principal.	5. Okta terminates its own session with the user.