Skip to main content
The following is a generic guide for setting up SSO through Azure AD (Microsoft Entra ID) as a SAML app. The exact setup may differ depending on your version of Azure AD and your desired setup.

​
SAML app setup

Various configurations for Azure AD are supported. The following is an example of an Azure setup.
1

Create the enterprise app

  1. Open portal.azure.com.
  2. Go to Microsoft Entra ID → Add → Enterprise Application.
  3. Select the option to create your own app and choose the non-gallery type.
  4. Enter a name for the app. A descriptive name is recommended so it can be easily identified later, for example Gr4vy Dashboard Sandbox/Production.
  5. Click Create.
Sandbox and production are configured separately. Create a separate enterprise app for each environment, each with its own values as shown below.
2

Configure SAML single sign-on

Select Single sign-on in the left menu, then choose SAML as the method. Edit the Basic SAML Configuration for the environment you are setting up:
  • Identifier (Entity ID): urn:auth0:gr4vy:{instance_id}-sandbox-saml
  • Reply URL: https://auth.gr4vy.com/login/callback?connection={instance_id}-sandbox-saml&organization={instance_id}
Click Save.
3

Retrieve the connection details

  1. Download the Base64 Certificate from the SAML Signing Certificate section.
  2. Copy the Login URL.
  3. Provide both to the support team so they can enable the connection.

​
Users access

Once the app is set up, make sure the right users have access to it. Assign users or groups to the enterprise app under Users and groups. Whichever approach you use, apply the roles and environments below to the intended users.

​
Roles and environments

By default, users are restricted to the analyst role in the sandbox environment. To assign roles and environments, the gr4vy_roles and gr4vy_environments attributes must be included in the SAML assertion. In Azure AD these are most commonly driven by group membership.

​
Mapping Azure AD groups to Gr4vy roles

  1. Create an Azure AD group for each Gr4vy role you need (up to nine). Only create the roles you actually use. If you want different roles across sandbox and production, create separate groups for each environment.
  2. In the enterprise app, go to Single sign-on → Attributes & Claims and add a group claim.
  3. Enable Customize the name of the group claim and set the name to gr4vy_roles.
  4. Use the group claim’s regular expression transformation to convert each Azure group name into the matching Gr4vy role name. For example: Azure-ABS12123123-Tst_P_Administrator-AAD-Apps → Administrator.
  5. Role names are matched case-insensitively, as long as the transformed value matches a Gr4vy role name.
This approach relies on group names containing the Gr4vy role in a consistent, predictable format. Environments can be delivered in the same way, using a gr4vy_environments claim.

​
Roles

The gr4vy_roles property controls the roles a user has. This needs to be an array with one or more of the following values. If not set, it defaults to analyst.
  • analyst
  • administrator
  • customer-support
  • pii-viewer
  • system-manager
  • system-support
  • user-manager
  • report-manager
  • report-viewer

​
Environments

The gr4vy_environments property controls which environments a user can access. This needs to be an array with one or more of the following values. If not set, it defaults to sandbox.
  • production
  • sandbox