> ## 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.

### 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 should only be assigned if the user has either the `analyst` or `customer-support` assigned
as well.

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

<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.