# Okta setup guide

Set up sign-in with Okta for your Mestra organisation. Single sign-on is part of Enterprise.

Let your people sign in to Mestra with your company's Okta. Single sign-on (SSO) is part of Enterprise, for contract and Network customers. It isn't part of Studio or the free trial. [Talk to us](https://withmestra.com/talk-to-us/) to add it. An owner of your Mestra organisation and an Okta admin set it up once, together or one after the other.

## Prerequisites

- A Mestra organisation on Enterprise (a contract, or Network). Talk to us to add SSO.
- An owner of that Mestra organisation.
- An Okta admin who can add apps and assign people.
- Access to your email domain's DNS, to add one TXT record.

## Supported features

- SP-initiated SSO: people sign in from Mestra's sign-in page.
- IdP-initiated SSO, through [third-party initiated login](https://openid.net/specs/openid-connect-core-1_0.html#ThirdPartyInitiatedLogin): people sign in from the Mestra tile on their Okta dashboard.

Mestra doesn't create accounts on first sign-in (no just-in-time provisioning). Each person must already be a member of your Mestra organisation, or have an open invite to it. Owners add people in Mestra under **Team**.

For more on these terms, see the [Okta Glossary](https://help.okta.com/okta_help.htm?type=oie\&id=ext_glossary).

## Configuration steps

### 1. Verify your email domain in Mestra

Okta can sign people in only at email domains your organisation has verified.

1. In Mestra, an owner opens **Settings** > **Sign-in**.
2. Under **Email domains**, enter your company's email domain, such as `acme.com`, and press **Add domain**.
3. Mestra shows a TXT record. Add it to your domain's DNS.
4. Back in Mestra, press **Verify**. DNS changes can take a while to show, so try again later if it isn't found yet.

Repeat for each email domain your people use.

### 2. Add Mestra in Okta

> **Note:** Mestra's listing in the Okta catalogue is on its way. Until it's there, add Mestra as your own OIDC web app instead: see [Sign in with Okta](https://withmestra.com/docs/account/sign-in/#sign-in-with-okta).

1. In the Okta Admin Console, go to **Applications** > **Applications**.
2. Select **Browse App Catalog**, search for **Mestra**, and select it.
3. Select **Add Integration**, give it a label if you like, and select **Done**.
4. On the **Sign On** tab, copy the **Client ID** and **Client secret**.
5. On the **Assignments** tab, assign the people or groups who use Mestra.

### 3. Connect Okta in Mestra

1. In Mestra, back in **Settings** > **Sign-in**, find **Okta**.
2. Enter your **Okta domain**, such as `acme.okta.com`, and the **Client ID** and **Client secret** you copied.
3. Press **Save**.

People assigned in Okta can now sign in, as long as they're members of your Mestra organisation (or invited) and their email is at a verified domain.

## SP-initiated SSO

1. Go to [app.withmestra.com/app/signin](https://app.withmestra.com/app/signin).
2. Enter your work email and press **Continue with Okta**.
3. Sign in to Okta if it asks. Mestra opens when you're done.

## IdP-initiated SSO

1. On your Okta dashboard, select the **Mestra** tile.
2. Mestra's sign-in page opens with one button for your company's Okta. Press **Continue with Okta**.

## Troubleshoot

| What you see                                                        | Why                                                                                              | What to do                                                                                          |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| "Okta sign-in isn't set up for that email. Try another option."     | The email's domain isn't verified in Mestra, or Okta isn't connected for your organisation.      | Check both under **Settings** > **Sign-in** in Mestra.                                              |
| "Mestra isn't set up for that Okta. Ask your organisation's owner." | The tile's Okta isn't connected to a Mestra organisation, or your organisation doesn't have SSO. | An owner checks the **Okta domain** in Mestra. On a free trial, sign in from Mestra's sign-in page. |
| "Enter your work email, then press Continue with Okta."             | More than one Mestra organisation uses this Okta.                                                | Enter your work email on the sign-in page.                                                          |
| "We couldn't find a Mestra account for that email."                 | The person isn't a member of the organisation and has no open invite.                            | An owner invites them under **Team**.                                                               |
| Okta says you're not assigned to the app.                           | The person isn't assigned to Mestra in Okta.                                                     | An Okta admin assigns them on the app's **Assignments** tab.                                        |

To have Okta add, change and remove your people in Mestra too, see the [SCIM provisioning setup guide](https://withmestra.com/docs/integrations/scim/).

Still stuck? Email <support@withmestra.com>.
