> For the complete documentation index, see [llms.txt](https://help.rhythms.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rhythms.ai/workspace-settings-and-administration/team-users-and-access/configure-okta-for-sso.md).

# Configure Okta for SSO

This guide walks through connecting Okta to Rhythms as your SAML identity provider. You start from **Settings › Security** (titled **Security and Permissions**) › **Single Sign-On (SSO)** › **Setup**, which opens a setup portal powered by WorkOS. The portal gives you two values to paste into a new SAML app in Okta, and you paste Okta's metadata URL back into the portal. For what SSO changes for your users, who is exempt, and how to sign everyone out, see [Set up single sign-on (SSO)](/workspace-settings-and-administration/team-users-and-access/set-up-single-sign-on-sso.md).

## Before you start

* You must be a **Rhythms Admin** to open the SSO setup in Rhythms.
* You need an Okta administrator who can create and manage applications. If that is not you, ask Rhythms support to send the setup link directly to your Okta administrator.
* Rhythms matches users by email address, so the email Okta sends must match each user's email in Rhythms exactly.

The WorkOS portal shows its Okta steps in a numbered wizard. The order below follows that wizard; if your portal lists a step in a slightly different position, follow the order on screen.

## Step 1: Start SSO setup in Rhythms

1. Open **Settings** from the bottom of the left sidebar and choose **Security**.
2. In the **Single Sign-On (SSO)** section, click **Setup**. The WorkOS setup portal opens in a new tab.
3. On **Select your identity provider**, choose **Okta**.

![WorkOS setup portal with Okta selected in the identity provider list](https://4039886202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEGNgNGJOnocLzqT0TwtU%2Fuploads%2Fgit-blob-7efc29ddfd031f0bd7654dfff804300d8c268221%2Fb34e2191-6da3-4576-b68a-1827c7b361d2-32d54cf8a7626b78dda48_req_dSUgHsh_2BnIhWW_2FMW1HO4zbKtLQ3xeNm6UWruIQKrGhun8yQNYigpYWGu9XmJ_0AGeGE_0A.png?alt=media)

## Step 2: Create the SAML app integration in Okta

1. Sign in to the Okta admin console, expand **Applications** in the left menu and select the **Applications** tab.
2. Click **Create App Integration**.
3. Select **SAML 2.0** as the sign-in method and click **Next**.
4. Give the app a name such as "Rhythms" and click **Next**.

![Okta Create a new app integration dialog with SAML 2.0 selected](https://4039886202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEGNgNGJOnocLzqT0TwtU%2Fuploads%2Fgit-blob-681232bf0a665036eb90835a344e229ab1e8f8dd%2F6aec8f12-d85a-4e1a-a8c7-0045840b8d03-image.png?alt=media) ![Okta General Settings step with the app name field](https://4039886202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEGNgNGJOnocLzqT0TwtU%2Fuploads%2Fgit-blob-9d6a6537eeba0f9c4fcbed2f87688d6ec62dfa2d%2F68844634-8428-4f1e-b3ea-f39fb8eebb66-image.png?alt=media)

## Step 3: Configure SAML settings

1. In the WorkOS portal, find the **Single sign-on URL** and the **Audience URI (SP Entity ID)**. Copy the actual values from your portal; the ones in the screenshot are an example.
2. In Okta's **Configure SAML** screen, paste the Single sign-on URL into the **Single sign-on URL** field.
3. Paste the SP Entity ID into the **Audience URI (SP Entity ID)** field.
4. Scroll to the bottom and click **Next**.

![WorkOS portal showing the Single sign-on URL and Audience URI (SP Entity ID) to copy](https://4039886202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEGNgNGJOnocLzqT0TwtU%2Fuploads%2Fgit-blob-6e7d5505841539537d8c6721aef4f87f322ddf2a%2F3ee98a29-9ed0-44fd-839c-b93360ebbfcf-image.png?alt=media) ![Okta Configure SAML screen with the Single sign-on URL and Audience URI fields](https://4039886202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEGNgNGJOnocLzqT0TwtU%2Fuploads%2Fgit-blob-3224da5ccde1f7d712636f438c1fdd7d90b89356%2Fec7c9f51-5b81-4cd1-9f4b-31cdc1da62bb-image.png?alt=media)

## Step 4: Submit application feedback

On Okta's **Feedback** step, select **This is an internal app that we have created** and click **Finish**.

![Okta Feedback step with the internal app option selected](https://4039886202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEGNgNGJOnocLzqT0TwtU%2Fuploads%2Fgit-blob-32a21255e4564281e8e123daa0d660f720a2b087%2F74a65b37-7007-48e7-ad7d-16b9eabb0d14-image.png?alt=media)

## Step 5: Set the identity provider metadata

1. In your new Okta app, open the **Sign On** tab. In the **Metadata details** section, copy the **Metadata URL**.
2. In the WorkOS portal, paste it into the **Identity provider metadata URL** field on the **Set Identity Provider Metadata** step and continue.

![Okta Sign On tab showing the Metadata URL to copy](https://4039886202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEGNgNGJOnocLzqT0TwtU%2Fuploads%2Fgit-blob-ffbd4b47a81a0d0e4ab149b1f6be67eb5ff0f236%2Fb072ab8d-511d-44a1-b7d8-e53b4c045fbb-image.png?alt=media)

## Step 6: Configure SAML attribute statements

1. In the Okta app, open the **General** tab, find **SAML Settings** and click **Edit**.
2. Scroll to **Attribute Statements (Optional)** and add the four attributes the portal lists: `id`, `email`, `firstName` and `lastName`, each mapped to the matching Okta user profile value. The name format can stay unspecified.
3. Click **Next**, then **Finish**.

Depending on which features are enabled in your Okta org, the attribute settings may live in a slightly different place; the WorkOS portal step shows where.

![Okta Attribute Statements section with id, email, firstName and lastName mapped](https://4039886202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEGNgNGJOnocLzqT0TwtU%2Fuploads%2Fgit-blob-a306ad497acb2fc5d80bc85852e2906fbf725eb8%2Ffc4f7377-72cd-4c31-b27b-120e97bc245a-752bf3f6-2c95-4789-94ea-18c172e3303e.webp?alt=media)

## Step 7: Assign people and groups in Okta

1. In the Okta app, open the **Assignments** tab.
2. Click **Assign** and choose **Assign to People** or **Assign to Groups**.
3. Select the users or groups who should be able to sign in to Rhythms and complete the assignment.

Only people assigned to the Okta app can sign in through SSO. Assignment does not create Rhythms users; for that, set up Directory Sync (SCIM) as well.

![Okta Assignments tab with the Assign dropdown open](https://4039886202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEGNgNGJOnocLzqT0TwtU%2Fuploads%2Fgit-blob-75f222167bbf084e89078dc718c2d0797c60ce0b%2F7926cf61-4a9e-4e4c-9d76-e25713dd10bd-image.png?alt=media)

## Step 8: Test single sign-on

1. Sign out of Rhythms.
2. Go to app.rhythms.ai and enter your work email address.
3. Rhythms redirects you to Okta. Authenticate there.
4. You land back in Rhythms, signed in. In **Settings › Security**, the SSO card now shows **Okta** with an **active** badge and your email domain.

## What changes for your users

Once the Okta connection is active, everyone whose email is on your workspace domain must sign in through Okta; Rhythms redirects other sign-in attempts to Okta. Guests and external users on other domains, including rhythms.ai support accounts, are not affected. Enabling SSO does not end existing sessions and Rhythms sets no fixed session timeout; to make everyone re-authenticate immediately, use **Logout all users** under the SSO section. If users will launch Rhythms from their Okta dashboard, copy the RelayState value from **IdP-Initiated SSO Configuration** in Settings › Security into the Okta app's Default RelayState.

## Troubleshooting

* **Authentication errors.** Re-copy the Single sign-on URL and Audience URI (SP Entity ID) from the portal into Okta; a single stray character breaks the connection. Confirm the user is assigned to the Rhythms app on Okta's Assignments tab.
* **A user sees an error that their account does not have access to the product.** The email in the SAML assertion does not match a Rhythms user. Check the `email` attribute statement maps to the user's primary work email, and that the user exists in Rhythms under exactly that address.
* **Attribute mapping not working.** Check the spelling and case of `id`, `email`, `firstName` and `lastName` in Attribute Statements, and that your test users' Okta profiles have values for all four.

## FAQ

**What do I need from Rhythms to configure Okta?** Two values shown in the WorkOS setup portal: the Single sign-on URL (ACS URL) and the Audience URI (SP Entity ID). Step 3 shows where to find them.

**Which attribute statements are required?** Four: `id`, `email`, `firstName` and `lastName`. Step 6 covers them.

**Where do I get the metadata URL?** Okta generates it after the app is created. Step 5 shows where it is on the app's Sign On tab and where to paste it in the portal.

**Does this also provision users from Okta?** No. SSO only controls sign-in. To create, update and deactivate Rhythms users from Okta, set up Directory Sync (SCIM) separately; see [Set up SCIM user provisioning](/workspace-settings-and-administration/team-users-and-access/set-up-scim-user-provisioning.md).

**I am not the Okta administrator.** Ask Rhythms support to send the setup link directly to your Okta administrator.

## Related articles

* [Set up single sign-on (SSO)](/workspace-settings-and-administration/team-users-and-access/set-up-single-sign-on-sso.md)
* [Set up SCIM user provisioning](/workspace-settings-and-administration/team-users-and-access/set-up-scim-user-provisioning.md)
* [Enterprise User Management in Rhythms](/workspace-settings-and-administration/team-users-and-access/users-teams-and-access-overview.md)
* [User Management in Rhythms](/workspace-settings-and-administration/team-users-and-access/add-and-manage-users.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.rhythms.ai/workspace-settings-and-administration/team-users-and-access/configure-okta-for-sso.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.