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

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

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

## SAML app setup

The following is an example of a OneLogin setup using the SAML Test Connector.

<Steps>
  <Step title="Add the app">
    1. Log in to the OneLogin administrator dashboard.
    2. Go to **Apps** → **Add Apps**.
    3. Search for **SAML** and select **SAML Test Connector (IdP w/attr)**.
    4. Set the **Display Name** to anything recognizable, for example `Gr4vy Dashboard`.
    5. Click **Save**.

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

  <Step title="Configure the SAML settings">
    On the **Configuration** tab, 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">
        * **Audience:** `urn:auth0:gr4vy:{instance_id}-sandbox-saml`
        * **Recipient:** `https://auth.gr4vy.com/login/callback?connection={instance_id}-sandbox-saml&organization={instance_id}`
        * **ACS (Consumer) URL:** same as **Recipient**
        * **ACS (Consumer) URL Validator:** `[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&//=]*)`
      </Tab>

      <Tab title="Production">
        * **Audience:** `urn:auth0:gr4vy:{instance_id}-production-saml`
        * **Recipient:** `https://auth.gr4vy.com/login/callback?connection={instance_id}-production-saml&organization={instance_id}`
        * **ACS (Consumer) URL:** same as **Recipient**
        * **ACS (Consumer) URL Validator:** `[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&//=]*)`
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add the attribute parameters">
    On the **Parameters** tab, add a parameter for each attribute below. The steps are the same for
    every parameter:

    1. Click the **+** to add a parameter.
    2. Enter the **Field name**, check **Include in SAML assertion**, and click **Save**.
    3. Open the parameter and set its **Value** to the corresponding OneLogin value, then save.

    | Field name           | Value                                                                                             |
    | -------------------- | ------------------------------------------------------------------------------------------------- |
    | `name`               | Set the value type to **Macro** and enter `{firstname} {lastname}`                                |
    | `email`              | The **Email** field                                                                               |
    | `gr4vy_roles`        | The value holding the user's roles (see [Roles and environments](#roles-and-environments))        |
    | `gr4vy_environments` | The value holding the user's environments (see [Roles and environments](#roles-and-environments)) |

    `name` and `email` map to standard OneLogin fields. `gr4vy_roles` and `gr4vy_environments`
    carry the user's role and environment assignments — see
    [Roles and environments](#roles-and-environments) for how these are sourced and the accepted values.
  </Step>

  <Step title="Retrieve the connection details">
    On the **SSO** tab, copy the following and send them to the support team so they can enable the
    connection:

    * **SAML 2.0 Endpoint (HTTP)** — the sign-in URL.
    * **X.509 Certificate** — click **View Details** and download the certificate.
  </Step>
</Steps>

Once support confirms the connection is enabled, users can sign in. At this stage, every user is
assigned the default role and environment until you complete the steps below.

## Users access

Make sure the right users have access to the app in OneLogin. Access can be granted by assigning the
app directly to individual users, or automatically through OneLogin roles or mappings. Only users
with the app assigned can sign in to the dashboard.

## Roles and environments

By default, users are restricted to the `analyst` role in the `sandbox` environment. To assign
roles and environments, send the `gr4vy_roles` and `gr4vy_environments` attributes in the SAML
assertion, populated per user from custom user fields (or from OneLogin roles or group membership).

If a user needs more than one role or environment, enable the **Multi-value parameter** flag on the
parameter so each value is sent as a separate SAML attribute value.

<Note>
  If roles or environments are not applied as expected, reach out to the support team.
</Note>

### Roles

The `gr4vy_roles` property 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` property 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`