Skip to main content
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
For more information on roles, please see the guide.

​
Integrations

For SAML or OIDC integrations, the following attributes/claims from the identity provider are expected.
NameRequiredDescription
nametrueUsed as the profile name
emailtrueUsed as a unique identifier
gr4vy_rolesfalseUsed 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.