<a id="enable-sso"></a>

# Enable SAML SSO on Confluent Cloud

Enable single sign-on (SSO) for Confluent Cloud by configuring your identity
provider (IdP) in the Confluent Cloud Console, mapping user groups, and testing
authentication.
You can upload a SAML metadata file from your IdP
or enter settings manually.

Confluent Cloud supports [SAML-based SSO](overview.md#sso-saml) for your identity
provider. If your identity provider gives you a SAML metadata file, you can
simplify the configuration by uploading the file during configuration. For
more information, see the [Use the SAML metadata file for SSO configuration](#saml-metadata-for-sso-configuration) section.

IdP-initiated SSO is available for SAML SSO-enabled organizations on
Confluent Cloud. IdP-initiated SSO allows users to sign in to Confluent Cloud directly from
their IdP’s application catalog. For new SSO connections,
IdP-initiated SSO is enabled by default, but can be disabled during
configuration or at anytime on the **Single sign-on** page in the
Confluent Cloud Console.

<a id="sso-limitations"></a>

## Limitations

* The SAML Single Logout (SLO) Protocol, including the Single Logout URL,
  is not supported in Confluent Cloud SSO.
* SSO connection names must be globally unique. If you have multiple
  Confluent Cloud organizations, you cannot use the same SSO connection name for
  each organization.

<a id="enable-sso-prerequisites"></a>

## Prerequisites

* You must have an existing SAML-based identity provider, such as Okta,
  OneLogin, or Microsoft Entra ID.
* Only users granted the [OrganizationAdmin](../../../../access-control/rbac/predefined-rbac-roles.md#organizationadmin-role)
  role can view and modify SSO settings.

<a id="enable-sso-steps"></a>

## Enable SSO using Confluent Cloud Console

1. Open the Confluent Cloud Console and go to the **Single sign-on** page at
   [https://confluent.cloud/sso](https://confluent.cloud/sso).
   You can also get to this page by opening the sidebar menu and
   clicking **Single sign-on**.
2. On the **Single sign-on** page, click **Enable SSO**. The
   **Set SSO identifier** page displays.

<a id="set-sso-identifier"></a>

### Set the SSO identifier

1. In the **SSO identifier** field, enter the unique SSO identifier that
   will be used to identify your organization. The value you enter is
   appended to the single sign-on URL, like this:
   ```text
   https://confluent.cloud/login/sso/<sso-identifier>
   ```

   The SSO identifier (`<sso-identifier>`) must include only lowercase
   letters, integers, and hyphen (`-`) characters. Typically, the
   organization name is used. For example, if your organization name is Acme
   Inc., you might use `acme` as the SSO identifier. SSO users can then
   directly sign in to your organization’s Confluent Cloud account using
   `https://confluent.cloud/login/sso/acme` as the sign-on URL.

   Since organizations are [JIT-enabled](jit-user-provisioning.md#jit-user-provisioning) by
   default, new SSO users can then directly sign in to your organization’s
   Confluent Cloud account using `https://confluent.cloud/login/sso/acme` and
   automatically have their Confluent Cloud user account created on their first
   successful sign-in. SSO users with existing Confluent Cloud user accounts can
   also sign in at `https://confluent.cloud`.
2. Click **Next**. The **Configure identity provider** page appears with
   generated values to add to your identity provider SAML settings.

<a id="configure-identity-provider"></a>

### Configure the identity provider

1. Open a separate browser window, go to your identity provider SAML
   settings and enter the generated values for the following SAML settings:

   **Assertion consumer service URL**
   : The endpoint where the identity provider will send an SSO token
     after authenticating a user.
     <br/>
     `https://login.confluent.io/login/callback?connection=<my-sso-identifier>`

   **Entity ID**
   : The unique identifier for Confluent Cloud.
     <br/>
     `urn:auth0:confluent:<my-sso-identifier>`
2. After you update the SAML settings for your identity provider, click
   **Continue**. The **Configure SSO settings** page appears.

<a id="configure-sso-settings"></a>

### Configure SSO settings

1. Click **Upload** to upload the SAML metadata file from your identity
   provider, or click **Enter manually** to enter the values from your
   identity provider.

   For more information about using or finding the SAML metadata file for
   your identity provider, the [Use the SAML metadata file for SSO configuration](#saml-metadata-for-sso-configuration)
   section.

   ### Upload SAML metadata

   To upload the SAML metadata file:
   1. Click **Upload** and then click **Upload SAML metadata file**. A
      file selection dialog appears.
   2. Select the SAML metadata file and then click **Open**.
   3. The filename for the uploaded file appears on the page.

      #### IMPORTANT
      If you see the error message “Failed to create SSO connection:
      The SAML email mapping could not be identified from the
      metadata file. You can manually confirm the email mapping.”,
      the **Email mapping** entry field appears below the filename.
      Select the correct value from the **Recommended values** in the
      dropdown list, or manually enter the correct value.

      The **Recommended values** in the selection list are:

      `http://schemas.xmlsoap.org/ws/2005/05/identity/
      claims/emailaddress`
      [Default] The email address of the user.

      `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
      The unique name of the user.

      `http://schemas.xmlsoap.org/ws/2005/05/identity/
      claims/nameidentifier`
      The SAML name identifier of the user.
   4. (Optional) To disable IdP-initiated SSO, deselect
      **Enable IdP-initiated SSO**.

      Enabled by default, IdP-initiated SSO lets users sign in to
      Confluent Cloud directly from your identity provider’s application
      catalog.
   5. Click **Submit**.

   ### Enter manually

   To enter the SAML metadata manually:
   1. On the **Configure SSO settings** page, enter the following
      : information:

      **Upload signing certificate**
      : Browse to and select the signing certificate.

      **SAML sign-on URL**
      : Enter the identity provider sign-on URL, which must
        be reachable by the user’s web browser.

      **Email mapping**
      : To map an email address to a SAML attribute, select one of the
        following recommended values from the dropdown list, or
        manually enter the value.
        <br/>
        `http://schemas.xmlsoap.org/ws/2005/05/identity/
        claims/emailaddress`
        | [Default] The email address of the user.
        <br/>
        `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
        | The unique name of the user.
        <br/>
        `http://schemas.xmlsoap.org/ws/2005/05/identity/
        claims/nameidentifier`
        | The SAML name identifier of the user.
   2. (Optional) To disable IdP-initiated SSO, deselect
      **Enable IdP-initiated SSO**.

      Enabled by default, IdP-initiated SSO lets users sign in to
      Confluent Cloud directly from your identity provider’s application
      catalog.
   3. Click **Submit**.

<br/>

You have successfully enabled SSO for Confluent Cloud.

On the **Single sign-on** page, you can view your SSO settings. To edit
the settings, click **Edit settings**.

If you decide not to use the new settings, click **Disable SSO**.

<a id="verify-sso-config"></a>

## Verify your SSO configuration

To verify your SSO configuration, go to your new sign-in URL using the
sign-on link displayed in the Single Sign-On (SSO) summary
(`confluent.cloud/login/sso/<sso-identifier>`, which in this workflow
example is `https://confluent.cloud/login/sso/big-company`). You are
redirected to your organization’s sign-on page. After entering your identity
provider sign-in credentials, you are redirected back to the Confluent Cloud
application.

Interactions with the application are almost identical to the non-SSO
experience. The major difference is that you are unable to change your
password in the Confluent Cloud user interface or using the “Reset Password” flow
because your password is now managed by your identity provider.

<a id="saml-nameid-support"></a>

## Supported SAML NameID formats

When SAML-enabled applications process a SAML assertion, the SAML
`NameID` attribute is used to determine the username of the user signing
in. Confluent Cloud supports the following formats for the SAML name identifier
(`NameID`):

`nameid-format:emailAddress`
: [Recommended] The `Subject Name ID` value from the identity provider
  uses the email address format.
  <br/>
  The email address must match the email address specified in the
  Confluent Cloud user profile.
  <br/>
  URI: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`

`nameid-format:persistent`
: The `Subject Name ID` from the identity provider is a persistent opaque
  identifier that is specific to the combination of the identity provider
  and Confluent Cloud.
  <br/>
  The SAML response assertion must include the email address as a
  `saml:Attribute`.
  <br/>
  URI: `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`

`nameid-format:unspecified`
: The `Subject Name ID` value from the identity provider can be any
  format.
  <br/>
  The SAML response assertion must include the email address as a
  `saml:Attribute`.
  <br/>
  URI: `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified`

<a id="saml-metadata-for-sso-configuration"></a>

## Use the SAML metadata file for SSO configuration

Many identity providers provide you with a SAML configuration file, often
named the “Federation Metadata XML” or “IdP Metadata”, in XML data format
that includes the expected SAML configuration settings, certificate, and
sign-on URL.

If your identity provider provides you with a SAML metadata file, you can
use this file in [Enable SSO using Confluent Cloud Console](#enable-sso-steps) to simplify SSO configuration by
uploading this file.

Confluent Cloud uses the default email mapping SAML attribute set by your
identity provider in the SAML metadata file to locate the user email
address attribute. For example, for Microsoft Entra ID, Confluent Cloud sets the
email mapping to `emailAddress`. For Okta, the email mapping is set to
`NameID`.

With SSO through Azure Marketplace, the user identification is the
email address attribute in Microsoft Entra ID. If the email address
attribute is not available, the user identification is the user principal
name (UPN) attribute, which is used as the Confluent email address identifier.

If your identity provider uses a different SAML attribute for the user
email address than what Confluent Cloud has automatically configured from the SAML
metadata file, you can edit **Email mapping** to be a custom SAML
attribute. If Confluent Cloud is unable to identify the email address from the
metadata file, a request appears in Confluent Cloud Console for you to provide the
correct SAML attribute to use for mapping the email address.

If Okta is your identity provider, see
[How to Download the IdP Metadata and SAML Signing Certificates for a SAML App Integration](https://support.okta.com/help/s/article/Location-to-download-Okta-IDP-XML-metadata-for-a-SAML-app-in-the-new-Admin-User-Interface).
For Microsoft Entra ID, see
[Use a SAML 2.0 Identity Provider (IdP) for Single Sign On](https://learn.microsoft.com/en-us/azure/active-directory/hybrid/how-to-connect-fed-saml-idp#add-azure-ad-metadata).

<a id="update-saml-metadata-file-for-sso-configuration"></a>

## Update the SSO configuration

You can update your SSO configuration for Confluent Cloud by uploading a new
SAML metadata file or by manually updating the following SAML
configuration settings:

* X.509 signing certificate
* SAML sign-on URL
* email mapping

To update your Confluent Cloud SSO configuration:

1. Open the Confluent Cloud Console and go to the  **Single sign-on** page at
   [https://confluent.cloud/sso](https://confluent.cloud/sso).
   You can also get to this page by opening the sidebar menu and clicking
   “Single sign-on”.
2. On the **Single sign-on** page, click **Edit settings**. The
   **Set SSO identifier** page appears.
3. On the **Set SSO identifier** page, click **Next**. The
   **Configure identity provider** page appears.

   #### NOTE
   The **SSO identifier** cannot be changed while updating an existing SSO
   configuration. To change the identifier, you must disable and then
   re-enable SSO.
4. Copy the following generated values, which are required for your
   identity provider (IdP), and then click **Next**.
   * Assertion Consumer Service (ACS) URL
   * Entity ID
   * Single logout URL
5. On the **Configure SSO settings** page, either click the
   **Upload SAML metadata file** under the **Upload** tab, or click the
   **Manually input** tab and perform the following steps:

   #### IMPORTANT
   For Microsoft Entra ID identity providers, follow the steps in the
   **Manually input** tab to update the X.509 signing certificate.

   For more information about using or finding the SAML metadata file for
   your identity provider, the [Use the SAML metadata file for SSO configuration](#saml-metadata-for-sso-configuration)
   section.

   ### Upload SAML metadata

   To upload the SAML metadata file:
   1. Click **Upload** and then click **Upload SAML metadata file**. A
      file selection dialog appears.
   2. Select the SAML metadata file and then click **Open**.
   3. The filename for the uploaded file appears on the page.

      #### IMPORTANT
      If you see the error message “Failed to create SSO
      connection: The SAML email mapping could not be identified from
      the metadata file. You can manually confirm the email
      mapping.”, the **Email mapping** entry field appears below the
      filename. Select the correct value from the **Recommended
      values** in the dropdown list, or manually enter the correct
      value.

      The **Recommended values** in the selection list are:

      `http://schemas.xmlsoap.org/ws/2005/05/identity/
      claims/emailaddress`
      [Default] The email address of the user.

      `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
      The unique name of the user.

      `http://schemas.xmlsoap.org/ws/2005/05/identity/
      claims/nameidentifier`
      The SAML name identifier of the user.
   4. Click **Submit**.

   ### Enter manually

   To enter the SAML metadata manually:
   1. On the **Configure SSO settings** page, enter the following
      information:

      **Upload signing certificate**
      : Browse to and select the signing certificate. The signing
        certificate must be in PEM format with a `.pem` extension.

      **SAML sign-on URL**
      : Enter the identity provider sign-on URL, which must
        be reachable by the user’s web browser.

      **Email mapping**
      : To map an email address to a SAML attribute, select one of the following
        recommended values from the dropdown list, or manually enter the value.
        <br/>
        `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
        | [Default] The email address of the user.
        <br/>
        `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
        | The unique name of the user.
        <br/>
        `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier`
        | The SAML name identifier of the user.
   2. Click **Submit**.

You have successfully updated your SSO configuration for Confluent Cloud.

On the **Single sign-on** page, you can review your SSO settings. To edit
the settings, click **Edit settings**.

If you decide not to use the new settings, click **Disable SSO**.

## Next steps

After enabling SAML SSO, you can configure group mappings to map your
identity provider groups to Confluent Cloud roles. For more information, see
[Group Mapping on Confluent Cloud](group-mapping/overview.md#group-mapping).