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

# Okta

> Connect Okta to Hyperstack with SAML or OIDC, so your team signs in with their Okta account.

This guide connects Okta to your Hyperstack organization. You need an administrator in Hyperstack and an administrator in Okta. Keep both open side by side.

> [!NOTE]
>
> Single sign-on is on the Enterprise plan. Read the [overview](https://thehyperstack.com/docs/tutorials/single-sign-on.md) first to see who can sign in.

## SAML or OIDC?

We recommend **SAML**. With SAML, the Okta tile opens Hyperstack, and a new Okta certificate reaches us by itself from the metadata URL. Use OIDC if your company's rules ask for it.

## Start in Hyperstack

Go to **Settings → Single sign-on** and click **Okta**. Then choose **SAML (recommended)** or **OIDC**.

## SAML set-up

**1. Create the app in Okta**

In the Okta Admin Console, open **Applications → Create App Integration**, pick **SAML 2.0** and click **Next**. Name the app **Hyperstack** and click **Next**.

**2. Copy our values into Okta**

Step 2 of the Hyperstack page, **Add Hyperstack to Okta**, shows each value with a copy button. Paste them in Okta under **Configure SAML**:

| Okta field | Value from Hyperstack |
| - | - |
| **Single sign-on URL** | Copy **Single sign-on URL**. Also tick **Use this for Recipient URL and Destination URL**. |
| **Audience URI (SP Entity ID)** | Copy **Audience URI (SP Entity ID)**. |
| **Default RelayState** | Leave it empty. |
| **Name ID format** | **EmailAddress** |
| **Application username** | **Email** |

![Step 2 in Hyperstack: the Single sign-on URL and the Audience URI with copy buttons](https://mintcdn.com/hyperstack/TA62Nx2wusH3dKmj/images/sso-okta-values.webp?fit=max\&auto=format\&n=TA62Nx2wusH3dKmj\&q=85\&s=954e7f2c20c14452870701df3409492b)

**3. Add the attribute statements**

Under **Attribute Statements**, add these three:

| Name | Value |
| - | - |
| `email` | `user.email` |
| `firstName` | `user.firstName` |
| `lastName` | `user.lastName` |

Click **Next**, then **Finish**.

**4. Assign people to the app**

Open the app's **Assignments** tab. Assign yourself and your team, or a group of them.

Assigned people still need to be on your Hyperstack team, or have an invitation. See [Who can sign in with SSO](https://thehyperstack.com/docs/tutorials/single-sign-on.md#who-can-sign-in-with-sso).

**5. Copy the Metadata URL into Hyperstack**

In Okta, open the app's **Sign On** tab and copy the **Metadata URL**.

In Hyperstack, step 3 **Connect Okta**, paste it in **Metadata URL** and click **Save connection**. You see **Connected to Okta** with the issuer and the date the certificate ends.

![Step 3 in Hyperstack: the Metadata URL saved and Connected to Okta](https://mintcdn.com/hyperstack/TA62Nx2wusH3dKmj/images/sso-okta-connect.webp?fit=max\&auto=format\&n=TA62Nx2wusH3dKmj\&q=85\&s=2b3baa3f73748305de60e76324b57ce8)

We read the metadata URL every day, so a new Okta certificate reaches us by itself, within 24 hours after Okta publishes it. After Okta makes a new certificate active, click **Refresh certificates** on **Settings → Single sign-on** to add it at once. SSO stays on.

Can't use the metadata URL? Click **Enter the details by hand instead** and fill in **Sign-in URL (IdP SSO URL)**, **Issuer (IdP entity ID)** and **Signing certificate**. Okta shows them under **View SAML setup instructions**. You must then paste each new certificate yourself, and each new certificate turns SSO off until a new test passes. See [Change the connection](https://thehyperstack.com/docs/tutorials/single-sign-on/domains-and-enforcement.md#change-the-connection).

Next: [verify your domain, test and turn on](#finish-in-hyperstack).

## OIDC set-up

**1. Create the app in Okta**

In the Okta Admin Console, open **Applications → Create App Integration**. Pick **OIDC - OpenID Connect** and **Web Application**, then click **Next**. Name the app **Hyperstack**.

**2. Copy our values into Okta**

Step 2 of the Hyperstack page shows the values for OIDC:

| Okta field | Value from Hyperstack |
| - | - |
| **Grant type** | **Authorization Code** (Okta ticks it already). |
| **Sign-in redirect URIs** | Copy **Sign-in redirect URIs**. |
| **Login initiated by** | **Either Okta or App**. Tick **Display application icon to users** to show the tile. |
| **Initiate login URI** | Copy **Initiate login URI**. |

Hyperstack asks for the scopes **openid**, **email** and **profile**. Okta allows them for a new app.

![Step 2 in Hyperstack on the OIDC tab: Sign-in redirect URIs and Initiate login URI](https://mintcdn.com/hyperstack/TA62Nx2wusH3dKmj/images/sso-okta-oidc-values.webp?fit=max\&auto=format\&n=TA62Nx2wusH3dKmj\&q=85\&s=d521efa91e1f2814539f0aac8b8023f0)

**3. Assign people to the app**

Under **Assignments**, assign yourself and your team, then click **Save**. You can change this later on the app's **Assignments** tab.

**4. Copy the client values into Hyperstack**

In Okta, the app's **General** tab shows the **Client ID** and the **Client secret**.

In Hyperstack, step 3 **Connect Okta**, fill in:

* **Issuer URL**: your Okta address, such as `https://acme.okta.com`.
* **Client ID**
* **Client secret**

Click **Save connection**. Hyperstack never shows the secret again. To change it later, click **Replace secret**.

## Finish in Hyperstack

**1. Verify your email domain**

Add your domain, such as `acme.com`, and add the TXT record that Hyperstack shows to your DNS. See [Verify a domain](https://thehyperstack.com/docs/tutorials/single-sign-on/domains-and-enforcement.md#verify-a-domain).

**2. Click Test sign-in**

A new tab opens Okta. Sign in there. The test doesn't change your account or sign you in.

When the test passes, you see **Test passed** with the email, the name and the Okta ID that Okta sent. If the email is yours, you also see **Your account is now linked to Okta.**

![Test passed with the email, name and Okta ID that came back](https://mintcdn.com/hyperstack/TA62Nx2wusH3dKmj/images/sso-test-passed.webp?fit=max\&auto=format\&n=TA62Nx2wusH3dKmj\&q=85\&s=ed454a3614f92771f613799f1d01a878)

If the test fails, the page says what is wrong and which value to change. See [Test sign-in results](https://thehyperstack.com/docs/tutorials/single-sign-on/domains-and-enforcement.md#test-sign-in-results).

**3. Click Turn on SSO**

You see **SSO is on. Your team can sign in with Okta.** Passwords keep working until you [enforce SSO](https://thehyperstack.com/docs/tutorials/single-sign-on/domains-and-enforcement.md#enforce-sso).

## Questions

> [accordion] The test says I'm not assigned to the app in Okta
>
> Open the app's **Assignments** tab in Okta and assign yourself. Then click **Test again**.

> [accordion] The test says no email came back
>
> For SAML, add the attribute statement `email` with the value `user.email`. For OIDC, check that the app allows the **email** scope.

> [accordion] Does the Okta tile work?
>
> Yes, with SAML. With OIDC, set **Login initiated by** to **Either Okta or App** and fill in **Initiate login URI**.

> [accordion] Can I change the connection after SSO is on?
>
> Yes. On **Settings → Single sign-on**, click **Edit connection**. A change applies at once and asks for a new test sign-in. A change to the metadata URL, the sign-in URL, the issuer, the certificate, the client ID or the secret also turns SSO off until a new test passes. See [Change the connection](https://thehyperstack.com/docs/tutorials/single-sign-on/domains-and-enforcement.md#change-the-connection). To see our values again, click **Show the values for Okta**.


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