Skip to main content
The following is a generic guide for setting up SSO through Google Workspace as a custom SAML app. The exact setup may differ depending on your Google Workspace configuration and your desired setup.

​
SAML app setup

Single sign-on with Google Workspace supports various configurations. The following is an example of a Google Workspace setup. You need super administrator access to the Google Admin console to complete it.
1

Create the custom user attributes

Google Workspace has no standard fields for roles or environments. Create a custom user attribute for each, so that they can be sent in the SAML assertion.
  1. Log in to the Google Admin console.
  2. Go to Directory → Users.
  3. Open the More options menu above the list of users and select Manage custom attributes.
  4. Click Add Custom Attribute and enter a category name, for example Gr4vy.
  5. Add the following custom fields, each with the type Text:
    • gr4vy_roles, with Number of values set to Multi-value.
    • gr4vy_environments, with Number of values set to Multi-value.
    • full_name, with Number of values set to Single value. This field is optional. Add it only if you want users’ full names as their profile names, as described in the attribute mapping step.
  6. Click Add.
The number of values can’t be changed from multi-value to single value after the attribute is created.
2

Create the custom SAML app

  1. Go to Apps → Web and mobile apps.
  2. Click Add App and select Add custom SAML app.
  3. Enter an app name, for example Gr4vy Dashboard Sandbox, and click Continue.
Sandbox and production are configured separately. Create a separate Google Workspace SAML app for each environment, each with its own values as shown below.
3

Download the identity provider details

On the Google Identity Provider details page, click Download Metadata and keep the XML file. You send it to the support team in a later step. Then click Continue.
4

Configure the service provider details

On the Service provider details page, fill in the following for the environment you are setting up. The instance_id is the name of your Gr4vy instance.
  • ACS URL: https://auth.gr4vy.com/login/callback?connection={instance_id}-sandbox-saml&organization={instance_id}
  • Entity ID: urn:auth0:gr4vy:{instance_id}-sandbox-saml
Leave the Start URL empty and Signed response unchecked. Keep the default Name ID format and Name ID, which is the primary email. Click Continue.
5

Map the attributes

On the Attribute mapping page, click Add mapping and map the following Google Directory attributes to the app attributes.The name attribute is required and is used as the user’s profile name in the dashboard. Google Workspace has separate first name and last name fields rather than a single full name, so choose one of the following:
  • First name: Map the First name attribute to name. This needs no extra setup, and the dashboard shows each user’s first name only.
  • Full name: Map the full_name custom attribute to name. This shows each user’s full name, but you need to enter the value for every user, as described in Users access.
Click Finish.
6

Turn on the app

  1. Select the app and open User access.
  2. Set the service status to On for everyone, or turn it on for specific organizational units or access groups.
  3. Click Save.
7

Provide the connection details

Send the metadata XML file you downloaded earlier to the support team so they can enable the connection.
The exact value of the attribute mapping may depend on your setup.

​
Users access

Once an app is set up, make sure the right users have access to it. This can be configured for everyone, per organizational unit, or through access groups. Whichever approach you use, set the gr4vy_roles and gr4vy_environments custom attributes on the intended users. If you mapped the full_name custom attribute to name, set it on each user as well. Custom attribute values are set per user. Open the user in Directory → Users, go to User information, and enter the values under the custom category. They can’t be uploaded in bulk with a CSV file. Changes in Google Workspace can take up to 24 hours to apply, but usually apply more quickly. The sign-in email of each user needs to match their Google Workspace email.

​
Roles and environments

By default, users are restricted to the analyst role in the sandbox environment. To assign roles and environments, set the gr4vy_roles and gr4vy_environments custom attributes on the relevant users. These are sent in the assertion through the attribute mapping configured in the preceding step.

​
Roles

The gr4vy_roles attribute controls the roles a user has. It must contain 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 attribute controls which environments a user can access. It must contain one or more of the following values. If not set, it defaults to sandbox.
  • production
  • sandbox