> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anglpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Single Sign-On with Google Workspace

> Configure Google Workspace as a SAML identity provider for the Gr4vy dashboard.

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](https://admin.google.com).
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**.

> [!NOTE]
>
> 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**.

> [!NOTE]
>
> 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.

**Sandbox**

* **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`

**Production**

* **ACS URL:** `https://auth.gr4vy.com/login/callback?connection={instance_id}-production-saml&organization={instance_id}`
* **Entity ID:** `urn:auth0:gr4vy:{instance_id}-production-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.

| Google Directory attribute | App attribute |
| - | - |
| First name, or `Gr4vy` → `full_name` | `name` |
| Primary email | `email` |
| `Gr4vy` → `gr4vy_roles` | `gr4vy_roles` |
| `Gr4vy` → `gr4vy_environments` | `gr4vy_environments` |

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](#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`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.