## Enable SAML 2.0 for SSO

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

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

Use this guide if your identity provider supports SAML 2.0 and is not listed as a named integration in Atlan's SSO settings. Setup exchanges metadata in both directions: you copy Atlan's service provider details into a new SAML app in your IdP, then import your IdP's metadata back into Atlan.

If you are using PingFederate as your identity provider, see the dedicated [PingFederate (SAML)](https://docs.atlan.com/llms/governance/access-control/integration-with-pingfederate-using-saml/llms.txt) guide, which covers PingFederate-specific assertion URL requirements.

## Prerequisites

Before you begin, make sure you have:

- **Admin access in Atlan.** Only admins can configure SSO.
- **Administrator access in your identity provider** so you can create a SAML application 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 configuring the app in your identity provider, 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 **SAML 2.0**.

4. Enter an **Alias** for the connection. This is a unique name used in the SSO URL (for example, `my-company-saml`), then click **Next**.

5. Under _Service provider metadata_, copy both values: you will paste them into your IdP in the next step:

 - **Atlan SAML Assertion URL** (the ACS URL)
 - **Atlan Audience URI (SP Entity ID)**

Keep this tab open. You will return here to finish setup.

## Configure in your identity provider

The exact steps vary by identity provider, but the configuration is the same for any SAML 2.0-compliant IdP.

In your identity provider's admin console:

1. Create a new SAML 2.0 application and name it `Atlan`.

2. Set the **Entity ID** or **Issuer** to the **Atlan Audience URI (SP Entity ID)** value you copied from Atlan.

3. Set the **ACS URL** or **Assertion Consumer Service URL** to the **Atlan SAML Assertion URL** value you copied from Atlan.

4. Assign the users and groups that should have access to Atlan.

5. Configure the application to return the following attributes in the SAML assertion:

 - `firstName`
 - `lastName`
 - `email`
 - `memberOf` (optional, but required if you plan to [sync IdP groups to Atlan groups](#sync-idp-groups-to-atlan-groups))

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

6. Export the IdP's SAML metadata as an XML file, or note the **SSO URL** and **x.509 certificate** for manual entry.

 :::warning
 The SSO URL must be accessible from Atlan via the internet.
 :::

## Connect your IdP to Atlan

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

1. Under _Identity provider metadata_, provide the metadata from your IdP one of two ways:

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

2. (Optional) Under **Attribute Mapper**, update the attribute name mappings if your IdP uses different names for the standard attributes. For example, if your IdP sends email as `mail` instead of `email`, update the mapping here.

3. (Optional) Under **Customize**, enter a **Sign in button text** to display a custom label for this provider on the Atlan login page.

4. Click **Save**.

Your users can now sign in to Atlan using your identity provider. By default, they can still sign in with a local Atlan account too. To require IdP sign-in, enable **Enforce SSO** (see below).

## Enforce SSO (optional)

Once SSO is working, you can disable local email-and-password sign-in so everyone authenticates through your IdP:

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

2. Enable **Enforce SSO**.

After enforcing SSO, have your IdP administrator manage access from your identity provider 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 IdP groups to Atlan groups (optional) {#sync-idp-groups-to-atlan-groups}

Map your IdP's groups to Atlan groups so users are placed in the right teams automatically on every sign-in.

:::warning Before you start
- Configure the `memberOf` attribute in your IdP's SAML application. Group sync will not 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 in Atlan.
:::

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

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

3. For each Atlan group, under the _SSO Groups_ column, type the name of the matching group from your IdP (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 your IdP, 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.
:::

## 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 your IdP, 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).

---