# OpenID Connect Protocol

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

Beyond authentication, you can [configure SCIM](#user-content-fn-1)[^1] 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 OpenID Connect.

## Configuration options

The following options are available when [setting up an identity provider that uses the OpenID Connect protocol](/saas/configuration/people/section-contents/how-to-guides/openid-connect/openid-connect-protocol.md).

* [**Allow identity-provider-initiated single sign-on**](#single-sign-on): When enabled, users authenticate once in their identity provider and can log in to Immuta.
* **Allow Immuta attributes to be applied to OpenID users and groups:** Attributes created in Immuta can be added to your users and groups in your identity provider. SCIM must be enabled or you must configure an external user info endpoint for this option to be available.
* [**Attribute schema**](#attribute-mapping): Map OpenID Connect attributes into Immuta after you enable **SCIM**.
* **Authorization endpoint:** The URL of the authorization server. The user will be redirected to this URL to authenticate when they log in to Immuta. If the **Discover URL** is provided, this field will be disabled.
* **Client ID:** The unique string identifier assigned to the OpenID Connect application you created in your identity provider. See your identity provider's documentation for details.
* **Client secret:** Client secret the OpenID Connect application uses to verify its identity with the authorization server. See your identity provider's documentation for details.
* **Discover URL:** URL of the identity provider's discovery endpoint. If this URL is provided, the fields for manually specifying the endpoint will be disabled.
* **Enable SSL:** Use SSL to protect user credentials, identity tokens, and profile data during login.
* **End session endpoint:** The URL of the identity provider's end session endpoint, which will trigger single logout.
* [**External groups and attributes endpoint**](/saas/configuration/people/section-contents/reference-guides/index.md#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.
* **Group permissions:** Once you enable group permissions, you can define a mapping of groups to Immuta permissions. Users who belong to one of the given groups will be granted the listed permissions automatically. *SCIM must be enabled or you must configure an external user info endpoint for this option to be available.*
* **Issuer:** The identity provider's URL. If the **Discover URL** is provided, this field will be disabled.
* **JWKS URI:** URL of the identity provider's JSON Web Key set. This is configured in the authorization server. If the **Discover URL** is provided, this field will be disabled.
* [**Migrate users**](/saas/configuration/people/section-contents/reference-guides/index.md#migrating-users): Migrate users from a previously configured identity provider to the current identity provider being configured.
* [**Profile schema**](/saas/configuration/people/section-contents/reference-guides/index.md#profile-schema-mapping)**:** Map attributes from your identity provider to automatically fill in a user’s Immuta profile.
* [**SCIM support**](/saas/configuration/people/section-contents/reference-guides/index.md#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. The majority of the profile schema fields will be hidden and automatically synced from the SCIM response. When you click this checkbox, Immuta generates a SCIM API key to use to configure provisioning in your identity provider. After the configuration is saved, this API key will be hashed, and a new key can be regenerated here if the old key is ever lost.
* **Scopes:** The scopes sent when a user authenticates. Scopes authorize access to a user’s profile details, like name and email.
* **Supported ID token signing algorithms:** A list of supported signing algorithms for verifying ID token signatures. If the **Discover URL** is provided, this field will be disabled.
* **Token endpoint:** URL of the identity provider's endpoint that returns access tokens or ID tokens. If the **Discover URL** is provided, this field will be disabled.
* **User info endpoint:** URL of the identity provider's user info endpoint. Complete this field if you will add custom scopes. If the **Discover URL** is provided, this field will be disabled.
* **User ID claim:** This key (primarily the `sub` (subject) claim) of the claim holds a unique identifier for the end user assigned by the identity provider.

## SCIM support

When configuring an identity provider that uses the OpenID Connect protocol, you can enable SCIM support to allow updates to user profiles and metadata to be made automatically in Immuta when updates are made in your identity provider. Without SCIM enabled, users would have to log in to Immuta for updates in your identity provider to be reflected in Immuta.

The columns below illustrate the differences between these two protocols and how they complement each other.

{% columns %}
{% column %}
**OpenID Connect**

* Allows users to log in to Immuta
* Updates user profiles and metadata when users log in to Immuta
  {% endcolumn %}

{% column %}
**SCIM**

* Automatically creates users in Immuta
* Pushes user updates automatically without users logging in to Immuta
* Allows Immuta attributes to be added to OpenID users and groups
* Allows Immuta users to be added to OpenID groups
  {% endcolumn %}
  {% endcolumns %}

See the [SCIM protocol reference guide](/saas/configuration/people/section-contents/reference-guides/scim-protocol.md) for details about how SCIM works in Immuta.

## Syncing groups and attributes

If you enable [SCIM](/saas/configuration/people/section-contents/reference-guides/scim-protocol.md) for OpenID Connect, Immuta will ingest the attributes and groups configured in your identity provider.

For groups and attributes to sync in Immuta, no additional configuration is required beyond enabling SCIM. However, you can define how user attributes are mapped into Immuta. See the [attribute mapping section](#attribute-mapping) for details.

### Attribute mapping

To configure attribute mapping for OpenID Connect, SCIM must be enabled. Once enabled, you can complete the attribute schema, which defines how attributes are mapped in Immuta.

For SCIM attribute mapping, 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`.

## Single sign-on

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

[^1]: When SCIM is configured, user entitlements are synced with Immuta automatically without users needing to log in.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.immuta.com/saas/configuration/people/section-contents/reference-guides/openid-connect-protocol.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.