## Enable Okta for SSO

URL: https://docs.atlan.com/product/integrations/identity-management/sso/how-tos/enable-okta-for-sso

> Configure SAML 2.0 single sign-on between Okta and Atlan so your users sign in to Atlan with their Okta credentials. Exchange service provider and identity provider metadata, assign users in Okta, and optionally sync Okta groups to Atlan.

Configure SAML 2.0 single sign-on so your users sign in to Atlan with their existing Okta credentials. Setup moves metadata in both directions: you copy Atlan's service provider details into a new SAML app in Okta, then import Okta's identity provider metadata back into Atlan.

Start in Atlan, build and configure the app in Okta, then return to Atlan to finish. Group sync is optional and covered at the end.

## Prerequisites

Before you begin, make sure you have:

- **Admin access in Atlan.** Only admins can configure SSO.
- **Administrator access in Okta** so you can create a SAML app and assign users.
- A decision on the **default role** new users receive on first sign-in (Admin, Member, or Guest). Set it in [Set default role for SSO users](https://docs.atlan.com/llms/governance/access-control/set-default-user-roles-for-sso/llms.txt). Most workspaces use Member.

## Get Atlan's service provider details

Before setting up the app in Okta, get the values Atlan provides.

1. In your Atlan workspace, click **Settings** from the left menu.

 If you are using the **Old UI (Classic)**, from the left menu, click **Admin**.

2. Click **SSO**.

3. Click **New**, then select **Okta** as the provider.

4. Under _Service provider metadata_, copy both values: you'll paste them into Okta in the next step:

 - **Single sign on URL**
 - **Audience URI (SP Entity ID)**

Keep this tab open. You'll return here to finish setup.

## Configure in Okta

All the app setup happens in the Okta admin console: create the application, collect the IdP metadata, and assign users.

### Create SAML application

In the Okta admin console:

1. In the left menu, expand **Applications** and click **Applications**.

2. Click **Create App Integration**.

3. Select **SAML 2.0** as the sign-in method, then click **Next**.

4. Under _General Settings_, enter a name for the app (for example, `Atlan`), then click **Next**.

5. Under _Configure SAML_, enter the values you copied from Atlan:

 - **Single sign-on URL**: paste Atlan's _Single sign on URL_. Keep **Use this for Recipient URL and Destination URL** enabled.
 - **Audience URI (SP Entity ID)**: paste Atlan's _Audience URI (SP Entity ID)_.

6. Under _Attribute Statements (optional)_, add the following mappings. For each one, set the _Name format_ to **Basic**, enter the **Name** on the left, and enter the **Value** on the right:

 - `firstName` → `user.firstName`
 - `lastName` → `user.lastName`
 - `email` → `user.email`

 :::info
 For users provisioned through SSO, the Atlan username comes from this mapping. If no username is mapped, Atlan uses the email prefix by default, which users can change when they first register.
 :::

7. (For group sync) Under _Group Attribute Statements (optional)_, add one mapping so Okta sends each user's group membership to Atlan:

 - **Name**: `memberOf`
 - **Name format**: Unspecified
 - **Filter**: Matches regex `[\s\S]+`

 This is required only if you plan to [sync Okta groups to Atlan groups](#sync-okta-groups-to-atlan-groups). For tighter filtering, see [Okta's guidance on group attribute statements](https://support.okta.com/help/s/article/How-to-send-certain-groups-that-the-user-is-assigned-to-in-one-Group-attribute-statement?language=en_US).

8. Click **Next**.

9. Under _Help Okta Support understand how you configured this application_, select **I'm an Okta customer adding an internal app**, then enable **This is an internal app that we have created**.

10. Click **Finish**.

### Download identity provider metadata

Once the app is created, Okta opens its settings page. Grab the metadata from the Sign On tab:

1. On the app's page, open the **Sign On** tab.

2. Under _SAML Signing Certificates_, find the active certificate and click **Actions** in its row.

3. Click **View IdP metadata**. The metadata opens in a new tab.

4. Save the file as XML. If it displays as plain text, save the page as a `.xml` file.

### Assign users and groups

Only users assigned to the app in Okta can sign in to Atlan. Still on the app's page in Okta:

1. Open the **Assignments** tab.

2. Click **Assign**, then choose **Assign to People** or **Assign to Groups**.

3. Assign each user or group you want to give access to, confirm the details, and click **Save and Go Back**.

4. When you're done, click **Done**.

:::info Restrict who gets auto-provisioned
By default, any Okta user who can authenticate and reach Atlan is automatically given an account on first sign-in. Controlling assignments here is also how you prevent that: users not assigned to this app are rejected at sign-in and no Atlan account is created for them.
:::

## Connect Okta to Atlan

With the app configured in Okta, go back to Atlan to finish. Open your Atlan SSO settings (the **Okta** provider you started earlier) and:

1. Under _Identity provider metadata_, provide the metadata you downloaded from Okta one of two ways:

 - **Import from XML** (recommended): click **Import from XML** and select the metadata file you saved from Okta.
 - **Enter manually**: paste the **SAML SSO URL** and the **x.509 certificate** from Okta into their respective fields.

2. Click **Save**.

Your users can now sign in to Atlan with Okta. By default, they can still sign in with a local Atlan account too: to require Okta, enable **Enforce SSO** (see below).

## Enforce SSO (optional)

Once Okta SSO works, you can disable local email-and-password sign-in so everyone authenticates through Okta:

1. In Atlan, go to **Settings → SSO** and open your Okta provider.

2. Enable **Enforce SSO**.

After enforcing SSO, have your Okta administrator manage access from Okta rather than [inviting users directly in Atlan](https://docs.atlan.com/llms/governance/access-control/invite-new-users/llms.txt). Assigned users are provisioned automatically on their first sign-in.

## Sync Okta groups to Atlan groups (optional) {#sync-okta-groups-to-atlan-groups}

Map Okta groups to Atlan groups so users land in the right teams automatically on every sign-in.

:::warning Before you start
- Configure the `memberOf` group attribute statement in Okta when you create the SAML app. Group sync won't work without it.
- [Create the Atlan groups](https://docs.atlan.com/llms/governance/access-control/manage-groups/llms.txt) you want to map to first: you can only map to groups that already exist.
:::

1. In Atlan, go to **Settings → SSO** and open your Okta provider.

2. Switch to the **Groups Mapping** tab.

3. For each Atlan group, under the _SSO Groups_ column, type the name of the matching Okta group (for example, `Data Engineering`), then click **Save** on that row.

Group membership syncs every time a user signs in. If you rename a group in Okta, update the mapping in Atlan to match. For sync issues, see [Troubleshooting SSO](https://docs.atlan.com/llms/governance/access-control/troubleshooting-sso/llms.txt).

:::info
You can add a mapped group to a [persona](https://docs.atlan.com/llms/governance/access-control/create-a-persona/llms.txt) or [purpose](https://docs.atlan.com/llms/governance/access-control/create-a-purpose/llms.txt) to auto-assign permissions as users sign in. To fully automate user and group lifecycle, [configure SCIM provisioning in Okta](https://docs.atlan.com/llms/governance/access-control/enable-okta-for-scim-provisioning/llms.txt).
:::

## Need help?

If users can't sign in or aren't landing in the right groups, see [Troubleshooting SSO](https://docs.atlan.com/llms/governance/access-control/troubleshooting-sso/llms.txt). Contact [**Atlan Support**](https://docs.atlan.com/support/submit-request) if the issue persists.

## Next steps

Now that users can sign in through Okta, finish setting up access:

- [Set default role for SSO users](https://docs.atlan.com/llms/governance/access-control/set-default-user-roles-for-sso/llms.txt): Choose whether new users land as Member, Guest, or Admin.
- [Restrict auto user creation](https://docs.atlan.com/llms/governance/access-control/limit-sso-automatically-creating-users-when-they-log-in/llms.txt): Limit sign-in to only the users your identity provider assigns.
- [Configure SCIM provisioning](https://docs.atlan.com/product/integrations/identity-management/scim/how-tos/configure-scim-provisioning): Automate the full user lifecycle (optional).

---