# Enable SAML Single Sign-on (SSO)

WarpStream supports SAML-based single sign-on (SSO) for your identity provider.

You can enable SAML-based single sign-on (SSO) by following the steps below.

### Limitations

* The SAML Single Logout (SLO) Protocol, including the Single Logout URL, is not supported in WarpStream SSO.
* SSO connection names must be globally unique. If you have multiple WarpStream tenants, you cannot use the same SSO connection name for each tenant.
* Existing WarpStream Console users cannot be converted to use SSO as their login method. Once SSO is setup existing users should delete their account before trying to login with SSO for the first time.

### Prerequisites

* You must have an existing SAML-based identity provider, such as Okta, OneLogin, or Microsoft Entra ID.

### Enable SSO using WarpStream Console

1. Open the WarpStream Console and go to the **Team** page then click on **Configure SSO**.
2. 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:\
   `https://console.warpstream.com/login/sso/<sso-identifier>`\
   The SSO identifier (`<sso-identifier>`) must include only lowercase letters, integers, and hyphen (`-`) characters. Typically, the organization name is used.
3. In the **SAML Sign In URL** field, enter the SAML Protocol URL from your SSO provider. For example in Okta this is called the **SAML 2.0 Sign on URL**.
4. Open a separate brower window, go to your identity provider SAML settings and enter the generated values for the following SAML settings:
   1. **Assertion consumer service URL**\
      In Okta this is the **Single sign-on URL** field.\
      `https://console.warpstream.com/login/callback?connection=<sso-identifier>`
   2. **SAML Entity ID**\
      In Okta this is the **Audience URI (SP Entity ID)** field.\
      `urn:sso:saml:warpstream:<sso-identifier>`
5. In the **SAML Entity ID** field, enter the Enttity ID from your SSO provider. In Okta this is called the **SAML 2.0 Issuer**.
6. Upload the X509 Signing Certificate for your SSO Provider.
7. Set the default role that all SSO SAML users will have.
8. Click Save

You have successfully enabled SSO for the WarpStream Console. Users with access to your SSO application can now login to your WarpStream tenant using `https://console.warpstream.com/login/sso/<sso-identifier>` .

If you decide not to use the new settings, click **Disable**, this will remove all the SAML SSO settings and lock your existing **SSO Identifier** from future use. If you want to re-use the locked **SSO Identifier** please [contact us](https://www.warpstream.com/contact-us) to unlock it.

### 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. WarpStream supports the following formats for the SAML name identifier (`NameID`), :

* `nameid-format:emailAddress`\
  \
  The **Subject Name ID** value from the identity provider uses the email address format.\
  URI: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`

### SAML SSO Group Role Mapping

SSO can be configured to map groups returned by SAML to [WarpStream Roles](/warpstream/reference/manage-console-access/workspaces-and-access-controls.md), this can be enabled by checking the **Enable SSO Role Mapping** checkbox when modifying SSO configuration.

When enabled, user roles will be automatically assigned or unassigned based on SSO group\
membership.\
\
Before checking this box make sure that the proper SSO Role mappings are setup as explained bellow as an improper setup can lead to being locked out of the WarpStream Console.

#### Setup Group Role Mapping

Once SSO is configured group role mapping can be configured per WarpStream Role.

When creating or updating a WarpStream Role the path to the group in the SAML assertion can be specified in the following format `groups/my_group_name`.

When users sign in via SSO, if they are a member of this group, they will be assigned this user role.

For example, if your SSO provider sends group attributes with the name "groups" and the value "engineering", you would enter "groups/engineering" here.

An example SAML Assertion is bellow:

{% code expandable="true" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<saml2:Assertion ID="id-1234567890" IssueInstant="2026-01-23T17:40:26.586Z" Version="2.0"
    xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
    <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.example.com/v4vw48acw4pu89acw</saml2:Issuer>
    <saml2:Subject>
        <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">john@example.com</saml2:NameID>
        <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <saml2:SubjectConfirmationData NotOnOrAfter="2026-01-23T17:45:26.587Z" Recipient="https://console.warpstream.com/login/callback?connection=foo"/>
        </saml2:SubjectConfirmation>
    </saml2:Subject>
    <saml2:Conditions NotBefore="2026-01-23T17:35:26.587Z" NotOnOrAfter="2026-01-23T17:45:26.587Z">
        <saml2:AudienceRestriction>
            <saml2:Audience>urn:sso:saml:warpstream:foo</saml2:Audience>
        </saml2:AudienceRestriction>
    </saml2:Conditions>
    <saml2:AuthnStatement AuthnInstant="2026-01-23T17:26:32.534Z" SessionIndex="id1769190026585.1729600223">
        <saml2:AuthnContext>
            <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
        </saml2:AuthnContext>
    </saml2:AuthnStatement>
    <saml2:AttributeStatement>
        <saml2:Attribute Name="groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml2:AttributeValue
                xmlns:xs="http://www.w3.org/2001/XMLSchema"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Engineering
            </saml2:AttributeValue>
            <saml2:AttributeValue
                xmlns:xs="http://www.w3.org/2001/XMLSchema"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">All Employees
            </saml2:AttributeValue>
            <saml2:AttributeValue
                xmlns:xs="http://www.w3.org/2001/XMLSchema"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Skunk Works
            </saml2:AttributeValue>
        </saml2:Attribute>
    </saml2:AttributeStatement>
</saml2:Assertion>
```

{% endcode %}

In this example the user groups are listed under the `groups` SAML Attribute. It contains a list of three groups; `Engineering`, `All Employees`, `Skunk Works`. So one can use `groups/Engineering`, `groups/All Employees`, and `groups/Skunk Works` as valid group paths.


---

# Agent Instructions: 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 current page URL with the `ask` query parameter:

```
GET https://docs.warpstream.com/warpstream/reference/manage-console-access/enable-saml-single-sign-on-sso.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.