Single Sign-On
Our 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 you centralized control for user access
- It improves security as there are fewer passwords to manage
- It can support your company’s security policies including MFA
- It streamlines the user experience
SSO Applications
Gr4vy creates two SSO applications for each of your instances; one for sandbox and one for production.
You need to decide how to provision access to each from your own IdP. Typically, we recommend creating an application for each environment within your IdP where you can then assign users or groups for access. If you have a limited number of users who need access you may decide to share the same IdP application for both environments.
User Roles
As part of SSO, we allow you to customize a user’s access by defining the list of roles each user is assigned.
We allow you to configure the access level for a user by defining custom user attributes on their profile within your identity provider (IdP). These attributes will be added as custom claims by our SSO provider when the user is authenticated.
For SAML applications, this might require mapping the attribute to the claim when setting up our dashboard as an application. For OIDC applications, you might have to add or create a set of custom claims with the right name.
For roles, we support a claim named gr4vy_roles with one or more of the following values.
administratoranalystcustomer-supportsystem-managersystem-supportuser-manager
When the administrator is set all other roles will be 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-viewerreport-managerreport-viewer
For more information on roles, please see our guide.
Integrations
For SAML or OIDC integrations, we expect to receive the following attributes/claims from your identity provider.
| 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 will default 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 we have applied the following restrictions.
- SSO administrators can not invite new users, instead new users will need to be provisioned through the SSO identity provider.
- SSO administrators can not edit user roles or merchant accounts, instead users will 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
We support the automatic promotion of an email user to an SSO user. Once SSO has been set up, any user who logs in with an email address that matches an existing user will be upgraded to an SSO user. After this first log in they will no longer be able to log in with an email address and password.