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

# Single Sign-On with Okta

The following is a generic guide for setting up SSO through Okta as a SAML app.
The exact setup may differ depending on the version of Okta and desired setup.

# SAML app setup

Single sign-on with Okta supports various configurations. The following is an example of an Okta setup.

1. Log into the Okta dashboard
2. Head over to **Applications** -> **Applications** in the left-hand sidebar
3. Click the **Create App Integration** button
4. Select **SAML 2.0** in the menu
5. Fill in the **General Settings** with any values
6. On the Configure SAML step, fill in the following:
   * **Single sign-on URL:** `https://auth.gr4vy.com/login/callback?connection={instance_id}-{environment}-saml&organization={instance_id}` where
     `gr4vy_id` unique ID of the instance and `environment` is either `sandbox` or `production`. In some cases this
     ID may be slightly different when setting it up.
   * **Audience URI (SP Entity ID):** `urn:auth0:gr4vy:{instance_id}-{environment}-saml`
   * Add the following **Attribute Statements** with an **Unspecified** name format
     * `name` -> `user.displayName`
     * `email` -> `user.email`
     * `gr4vy_roles` -> `user.gr4vy_roles`
     * `gr4vy_environments` -> `user.gr4vy_environments`
7. Finish the app setup

The exact value of the profile attribute mapping may depend on the setup.

<Warning>
  Before continuing, please ensure the app has been set up.
  Please reach out to the support team to get this enabled.
</Warning>

# Users access

Once an app is set up, it's important to make sure the right users have access to the app. This is something that can be configured
on the user profile, through a group, or through app properties. In either setup, it's important to apply the following profile properties to the
intended users.

# Profile properties

With the preceding steps, the connection should work, but no roles or environments are assigned to any user. By default, users
are restricted to the analyst role in the sandbox environment. To set this up properly, adding two new
custom variables to all profiles is recommended.

## Roles

The `gr4vy_roles` property is used to control the roles a user has. This needs to be an array with the following values.
If not set this defaults to `analyst`.

* `analyst`
* `administrator`
* `customer-support`
* `pii-viewer`
* `system-manager`
* `system-support`
* `user-manager`
* `report-manager`
* `report-viewer`

## Environments

The `gr4vy_environments` property is used to control the environments a user has access to. This needs to be an array
with one or more of the following values. If not set this defaults to `sandbox`.

* `production`
* `sandbox`