Skip to content
WarpStream Documentation
Start Free

Enable SAML Single Sign-on (SSO)

This page explains how to configure WarpStream's SAML / SSO functionality.

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

Section titled “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

Section titled “Prerequisites”
  • You must have an existing SAML-based identity provider, such as Okta, OneLogin, or Microsoft Entra ID.

Enable SSO using WarpStream Console

Section titled “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 to unlock it.

Supported SAML NameID formats

Section titled “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

Section titled “SAML SSO Group Role Mapping”

SSO can be configured to map groups returned by SAML to WarpStream Roles, 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

Section titled “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:

<?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>

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.