> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.instabase.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.instabase.com/_mcp/server. # Configuring SAML SSO for single-tenant AI Hub > Configure SAML-based single sign-on for single-tenant AI Hub. Enterprise Single-tenant Single-tenant AI Hub environments can use security assertion markup language (SAML)-based authentication to manage AI Hub access. Using SAML-based single sign-on (SSO) lets you leverage your organization's existing SSO identity provider (IdP) to automatically create new AI Hub user accounts upon initial login. AI Hub supports IdPs that use SAML 2.0, including: * Active Directory Federation Services (AD FS) * Auth0 * JumpCloud * Microsoft Entra ID * Okta * OneLogin * PingFederate ## Customer requirements Enabling SSO for your single-tenant AI Hub environment involves working closely with your support team. Your support team performs the configuration steps on the AI Hub side, but it's your responsibility to review this documentation and ensure the following customer requirements are met: * You've created an app registration in your IdP according to the [IdP configuration requirements](#idp-configuration-requirements). As part of this requirement, ensure that: * You've followed the [app registration requirements](#app-registration-requirements) and can provide the SP entity ID, SP name, and ACS URL values used in your app registration. * You've met the [attribute mapping](#attribute-requirements) requirements and all user accounts have an email address set under the `email` attribute. * You've reviewed optional attributes. If intending to use [group mapping](/admin/group-management#group-mapping), you've included a `groups` attribute. If intending to define organization admins at the IdP level, you've included an `is_admin` attribute. * You can provide the [IdP metadata XML](#idp-metadata-xml-requirements) for your app registration, either as a file or metadata-server endpoint. ## IdP configuration requirements The SSO integration flow begins with registering your single-tenant AI Hub environment as a service provider in your IdP. When creating your app registration, there are requirements that must be met, including required values and attribute mappings. > **Info** > > The term *app registration* refers to registering your single-tenant AI Hub environment as a service provider in your IdP. The same concept has a different name in various IdPs, such as an application, a relying party trust, an app integration, an SP connection, and so on. ### App registration requirements When creating your app registration, there are suggested and required values for some fields, such as the redirect URL after a user authenticates. The table outlines any required or suggested values, and the name of the corresponding field in select IdPs. > **Note** > > The accuracy of the **Corresponding IdP field** column isn't guaranteed as external product user interfaces aren't closely monitored. | **Field** | **Value** | **Corresponding IdP field** | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | SP entity ID | The suggested value is your AI Hub base URL, such as `https://customer.aihub.com`. | The SP entity ID value is set in the following IdP fields: • **AD FS** -- Relying Party Trust Identifier • **Auth0** -- The `audience` attribute within the SAML assertion > **Note** > > When using Auth0 as your IdP, the SP entity ID value in AI Hub corresponds to the `audience` attribute in the SAML assertion. By default the `audience` value is the same as the Auth0 `issuer`. You must edit the `audience` value to match your AI Hub base URL (or whatever value you're using as the SP entity ID). See the Auth0 [customize SAML assertions](https://auth0.com/docs/authenticate/protocols/saml/saml-configuration/customize-saml-assertions) documentation for details. • **JumpCloud** -- Audience/Entity ID • **Microsoft Entra ID** -- Identifier (Entity ID) • **Okta** -- Audience URI (SP Entity ID)/Audience Restriction • **OneLogin** -- Audience (EntityID) • **PingFederate** -- Partner’s Entity ID (Connection ID) | | SP name | The suggested value is `AIHubSP`, though any alphanumeric value is supported. | The SP name value is set in the following IdP fields: • **AD FS** -- Display name • **Auth0** -- Name (Application name) • **JumpCloud** -- Display label • **Microsoft Entra ID** -- Application name • **Okta** -- Application label • **OneLogin** -- Display name • **PingFederate** -- Connection name | | Assertion consumer service (ACS) URL | The required value is `https://{YOUR-AI-HUB-BASE-URL}/account/sso/saml2`. For example, `https://customer.aihub.com/account/sso/saml2`. | The ACS URL value is set in the following IdP fields: • **AD FS** -- Relying Party SAML 2.0 SSO service URL • **Auth0** -- Application Callback URL • **JumpCloud** -- ACS URLs • **Microsoft Entra ID** -- Reply URL (Assertion Consumer Service URL) • **Okta** -- Single Sign On URL • **OneLogin** -- ACS (Consumer) URL • **PingFederate** -- Assertion Consumer Service URL | ### Attribute requirements Your app registration can include the following attributes, some of which are required. Attribute names in your IdP must match the names listed below. For example, you can't replace the required attribute `email` with the similarly named attribute `emailAddress`. > **Note** > > When configuring attributes (claims) in Microsoft Entra ID, don't define a **Namespace** value for the claim. | **Attribute name** | **Required** | **Description** | **Sample valid values** | **Notes** | | ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `email` | Required | A unique email address that maps to the user's corporate email address. The `email` value must be unique among all users. | `jane.doe@company.com`, `john_doe@company.co.uk` | If a user’s email address changes, their AI Hub account from the previous address must be manually migrated to the new address. | | `groups` | Optional | The group ID of an IdP-defined group to which the user belongs. When your environment is available, an admin can [create group mappings](/admin/group-management/#group-mapping) to manage AI Hub group membership at the IdP level. | The group ID as defined in the IdP. | Each AI Hub group can map to multiple IdP-defined group, and each IdP-defined group can be mapped to multiple AI Hub groups. Upstream changes in your IdP aren't immediately applied and instead take effect with the member's next AI Hub login. For example, if a member is removed from a group in your IdP, upon next login that change of status syncs and the member is removed from the mapped AI Hub group. | | `is_admin` | Optional | A boolean value defining the user as an admin, typically set in the user profile. | `true`, `false` If set to `true`, the member is assigned the AI Hub *Admin* role upon next login. If set to `false`, the organization role is set to *Member*. If absent or undefined, the member's organization role isn't changed. | The `is_admin` attribute value takes precedence over any changes made using the AI Hub interface. You can still manually assign the *Admin* role to a member, but their role resets on next login based on the `is_admin` value. Admins have [wide-ranging permissions and access](/admin/roles/), so minimize the number of admins. | ## IdP metadata XML requirements To complete the SSO configuration on the AI Hub side, your support team requires the IdP metadata XML for your app registration. AI Hub supports two methods of referencing the IdP metadata XML: * **Local** -- Referencing a static `metadata.xml` file. This file is stored as a Kubernetes secret. * **Remote** -- Referencing a metadata-server endpoint where the XML file is hosted on the SAML provider metadata server. This table outlines where you can find the local or remote access value in select IdPs. > **Note** > > The accuracy of this table isn't guaranteed as external product user interfaces aren't closely monitored. | **IdP** | **Local access value** | **Remote access value** | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | AD FS | Download the federation metadata as an XML file from the federation metadata URL. Typically found at **AD FS** > **Service** > **Endpoints** > **Metadata URL path**. For example: `{Your host name}/FederationMetadata/2007-06/FederationMetadata.xml`. | | | Auth0 | Download the **Identity Provider metadata** file. Found on the application details page under **Addons** > **SAML 2 Web App** > **Usage**. | Share the **SAML metadata URL** link. Found on the application details page under **Advanced Settings** > **Endpoints**. | | Microsoft Entra ID | Download the **Federation metadata XML** file. Found on the application’s **Single sign-on** page. | Share the **App Federation Metadata Url** link. Found on the application’s **Single sign-on** page. | | Okta | Download the **Identity Provider metadata** file. Found on the application details page under **Sign on** > **Settings**. | Share the **Identity Provider metadata** link. Found on the application details page under **Sign on** > **Settings**. | | PingFederate | Download the metadata as an Identity Provider from the **Metadata Export** tab. | | | JumpCloud | Download by clicking **Export Metadata**. Found on the application details page under **SSO**. | Click **Copy Metadata URL**. Found on the application details page under **SSO**. | | OneLogin | Download the **SAML Metadata** file. Found at **Applications** > **SSO** > **More Actions** > **SAML Metadata**. | |