> ## 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

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

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 your desired setup.

## SAML app setup

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

<Steps>
  <Step title="Create the app integration">
    1. Log in to the Okta dashboard.
    2. Go to **Applications → Applications** in the left-hand sidebar.
    3. Click **Create App Integration**.
    4. Select **SAML 2.0** and click **Next**.
    5. Fill in the **General Settings** with any values (for example, an app name of `Gr4vy Dashboard`).

    <Note>
      Sandbox and production are configured separately. Create a separate Okta app
      for each environment, each with its own values as shown below.
    </Note>
  </Step>

  <Step title="Configure SAML">
    On the **Configure SAML** step, fill in the following for the environment you are setting up. The
    `instance_id` is the name of your Gr4vy instance.

    <Tabs>
      <Tab title="Sandbox">
        * **Single sign-on URL:** `https://auth.gr4vy.com/login/callback?connection={instance_id}-sandbox-saml&organization={instance_id}`
        * **Audience URI (SP Entity ID):** `urn:auth0:gr4vy:{instance_id}-sandbox-saml`
      </Tab>

      <Tab title="Production">
        * **Single sign-on URL:** `https://auth.gr4vy.com/login/callback?connection={instance_id}-production-saml&organization={instance_id}`
        * **Audience URI (SP Entity ID):** `urn:auth0:gr4vy:{instance_id}-production-saml`
      </Tab>
    </Tabs>

    Add the following **Attribute Statements** with an **Unspecified** name format:

    | Name                 | Value                     |
    | -------------------- | ------------------------- |
    | `name`               | `user.displayName`        |
    | `email`              | `user.email`              |
    | `gr4vy_roles`        | `user.gr4vy_roles`        |
    | `gr4vy_environments` | `user.gr4vy_environments` |
  </Step>

  <Step title="Finish and retrieve the connection details">
    1. Complete the app setup.
    2. On the app's **Sign On** tab, copy the **Identity Provider Single Sign-On URL** and
       download the **X.509 Certificate** (available via **View SAML setup instructions**).
    3. Provide the Sign-On URL and certificate to the support team so they can enable the connection.
  </Step>
</Steps>

The exact value of the profile 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 on the
user profile, through a group, or through app assignment. Whichever approach you use, apply the
profile properties 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, set the `gr4vy_roles` and `gr4vy_environments` profile properties on the
relevant users — these are sent in the assertion via the Attribute Statements configured in the preceding step.

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