> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Single Sign-On

The dashboard supports login via Single Sign On (SSO) through various SAML and OpenID Connect (OIDC) identity providers.

There are a few key benefits to SSO over email and password logins.

* It gives centralized control for user access
* It improves security as there are fewer passwords to manage
* It can support company security policies including MFA
* It streamlines the user experience

## SSO apps

Two SSO apps are created for each instance; one for sandbox and one for production.

A decision needs to be made on how to provision access to each from the IdP. Typically, creating an
app for each environment within the IdP where users or groups can then be assigned for access is recommended. If there are a
limited number of users who need access, sharing the same IdP app for both environments may be decided.

### Adding users

When SSO is on, you manage access in your identity provider, not in the dashboard. To give someone access,
create the user in your identity provider and assign them to the dashboard app, or to a group that has access to it.
Administrators who sign in with SSO can't invite users from the dashboard. For details, see
[SSO administrator restrictions](#sso-administrator-restrictions).

Roles also come from your identity provider, through the `gr4vy_roles` claim described in [user roles](#user-roles).
To remove someone's access, remove them from the dashboard app in your identity provider.

### User roles

As part of SSO, customizing a user's access by defining the list of roles each user is assigned is allowed.

Configuring the access level for a user by defining custom user attributes on their
profile within the identity provider (IdP) is allowed. These attributes are added as custom claims by the SSO provider
when the user is authenticated.

For SAML apps, this might require mapping the attribute to the claim when setting up the dashboard as an app.
For OIDC apps, a set of custom claims with the right name might need to be added or created.

For roles, a claim named `gr4vy_roles` with one or more of the following values is supported.

* `administrator`
* `analyst`
* `customer-support`
* `system-manager`
* `system-support`
* `user-manager`

When the `administrator` is set, all other roles are ignored, as they are all implied by this role.
If no roles are provided, then users are given the `analyst` role by default.

The following roles extend `analyst` and `customer-support`, and should only be assigned alongside one of them.

* `pii-viewer`
* `report-manager`
* `report-viewer`

Roles are re-synced from the claim on every sign-in. If the claim resolves to a set that would leave the user
without usable access, such as `pii-viewer` on its own or `user-manager` on its own, the `analyst` role is added
to the set. The roles from the claim are kept, so the user gets the access the identity provider intended plus the
base role that makes it work.

<Info>
  For more information on roles, please see the
  [guide](../../dashboard/roles-and-permissions/roles).
</Info>

## Integrations

For SAML or OIDC integrations, the following attributes/claims from the identity provider are expected.

| Name | Required | Description |
| - | - | - |
| `name` | true | Used as the profile name |
| `email` | true | Used as a unique identifier |
| `gr4vy_roles` | false | Used to set permissions. If not set, this defaults to `analyst` |

## SSO administrator restrictions

Regular administrators can normally edit all users and invite new users. To stop an SSO administrator from
circumventing the identity provider, the following restrictions have been applied.

* SSO administrators can not invite new users; instead, new users need to be provisioned through the SSO identity provider.
* SSO administrators can not edit user roles or merchant accounts; instead, users need to be provisioned roles (and soon merchant accounts) through the SSO identity provider.
* SSO administrators can delete users, as this is currently the only way to clean up users who no longer have access.
* SSO administrators can edit all details of regular users.

Additionally, SSO users can not edit their own name or password.

## User upgrade to SSO

The automatic promotion of an email user to an SSO user is supported. Once SSO has been set up, any user who logs in
with an email address that matches an existing user is upgraded to an SSO user. After this first log in, they are
no longer able to log in with an email address and password.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.