> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainloop.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure your Identity Provider for SAML SSO
> How to configure your Identity Provider (IdP) to use SAML Single Sign-On with Chainloop Cloud
This feature is only available on Chainloop's platform [paid plans](https://chainloop.dev/pricing).
Chainloop Cloud supports SAML 2.0 Single Sign-On so your team can authenticate with your organization's Identity Provider (IdP). This guide walks you through configuring your IdP to work with Chainloop.
SAML SSO is set up in **concierge mode**: you configure your IdP using the values below, then share the IdP metadata with the Chainloop team to complete the integration.
## Chainloop Service Provider Details
When configuring a new SAML application in your IdP, you will need the following Chainloop Service Provider (SP) values:
| Setting | Value |
| ---------------------------------------- | -------------------------------------------------------- |
| **SP Entity ID** (Audience URI) | `https://api.app.chainloop.dev/auth/saml` |
| **Assertion Consumer Service (ACS) URL** | `https://api.app.chainloop.dev/auth/saml/acs` |
| **SP Metadata URL** | `https://api.app.chainloop.dev/auth/saml/metadata` |
| **ACS Binding** | `HTTP-POST` |
| **AuthnRequest Binding** | `HTTP-Redirect` |
| **Name ID Format** | `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` |
## Required and Optional SAML Attributes
Chainloop expects the following attributes in the SAML assertion. Only `email` is required.
| Attribute | Required | SAML Attribute Name | Description |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Email** | Yes | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` or `NameID` (email format) | User's email address. Used to identify and provision the user. |
| **First name** | No | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | User's first name. |
| **Last name** | No | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | User's last name. |
| **Display name** | No | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/displayname` | Fallback display name if first/last name are not provided. |
| **Groups** | No | `groups` | List of group memberships. Used for [automatic provisioning of user roles and groups](/guides/deployment/guides/provisioning#dynamic-provisioning-through-single-sign-on-oidc). |
## IdP-Specific Configuration
### Step 1: Create a New SAML Application
1. In the Okta Admin Console, go to **Applications** > **Applications**
2. Click **Create App Integration**
3. Select **SAML 2.0** and click **Next**
4. Enter a name (e.g. `Chainloop`) and click **Next**
### Step 2: Configure SAML Settings
In the **SAML Settings** section, fill in:
| Field | Value |
| ------------------------------- | --------------------------------------------- |
| **Single sign-on URL** | `https://api.app.chainloop.dev/auth/saml/acs` |
| **Audience URI (SP Entity ID)** | `https://api.app.chainloop.dev/auth/saml` |
| **Name ID format** | `EmailAddress` |
| **Application username** | `Email` |
### Step 3: Configure Attribute Statements
Under **Attribute Statements**, add:
| Name | Value |
| -------------------------------------------------------------------- | ---------------- |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | `user.email` |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | `user.firstName` |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | `user.lastName` |
Under **Group Attribute Statements** (optional, for [automatic provisioning](/guides/deployment/guides/provisioning)):
| Name | Filter |
| -------- | -------------------------------------------------------------------------------------- |
| `groups` | Choose a filter that matches the groups you want to send (e.g. **Matches regex** `.*`) |
### Step 4: Assign Users (if Applicable)
Go to the **Assignments** tab of your new application and assign the users or groups that should have access to Chainloop. Depending on your Okta configuration, all users may already have access by default.
### Step 5: Share the IdP Metadata
Go to the **Sign On** tab and copy the **Metadata URL** (under **SAML Signing Certificates** > **Actions** > **View IdP metadata**). Share this URL with the Chainloop team.
### Step 1: Create a new Enterprise Application
1. In the Azure portal, go to **Microsoft Entra ID** > **Enterprise Applications**
2. Click **New application** > **Create your own application**
3. Enter a name (e.g. `Chainloop`), select **Integrate any other application you don't find in the gallery (Non-gallery)**, and click **Create**
### Step 2: Set up Single Sign-On
1. In your new application, go to **Single sign-on** and select **SAML**
2. In the **Basic SAML Configuration** section, click **Edit** and enter:
| Field | Value |
| -------------------------- | --------------------------------------------- |
| **Identifier (Entity ID)** | `https://api.app.chainloop.dev/auth/saml` |
| **Reply URL (ACS URL)** | `https://api.app.chainloop.dev/auth/saml/acs` |
### Step 3: Configure Attributes and Claims
Click **Edit** in the **Attributes & Claims** section. Verify or add the following claims:
| Claim name | Source attribute |
| -------------------------------------------------------------------- | ---------------- |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | `user.mail` |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | `user.givenname` |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | `user.surname` |
To send group claims (optional, for [automatic provisioning](/guides/deployment/guides/provisioning)):
1. Click **Add a group claim**
2. Select **Groups assigned to the application**
3. Set **Source attribute** to the value that matches your group naming convention
### Step 4: Assign Users and Groups (if Applicable)
Go to **Users and groups** and assign the users or groups that should have access to Chainloop. Depending on your Entra ID configuration, all users may already have access by default.
### Step 5: Share the IdP Metadata
In the **SAML Certificates** section, copy the **App Federation Metadata Url**. Share this URL with the Chainloop team.
### Step 1: Create a Custom SAML Application
1. In the Google Admin console, go to **Apps** > **Web and mobile apps**
2. Click **Add app** > **Add custom SAML app**
3. Enter a name (e.g. `Chainloop`) and click **Continue**
4. On the **Google Identity Provider details** page, copy the **SSO URL**, **Entity ID**, and download the **Certificate**. You will share these with the Chainloop team. Click **Continue**.
### Step 2: Configure Service Provider Details
Enter the following values:
| Field | Value |
| ------------------ | --------------------------------------------- |
| **ACS URL** | `https://api.app.chainloop.dev/auth/saml/acs` |
| **Entity ID** | `https://api.app.chainloop.dev/auth/saml` |
| **Name ID format** | `EMAIL` |
| **Name ID** | `Basic Information > Primary email` |
### Step 3: Configure Attribute Mapping
Add the following attribute mappings:
| Google Directory attribute | App attribute |
| -------------------------- | -------------------------------------------------------------------- |
| **Primary email** | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` |
| **First name** | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` |
| **Last name** | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` |
If you want to send group memberships for [automatic provisioning](/guides/deployment/guides/provisioning), configure a group membership attribute with the name `groups`.
### Step 4: Enable the Application
1. Click **Finish** to create the application
2. Click on the application, then go to **User access**
3. Turn the service **ON** for the organizational units or groups that should have access
### Step 5: Share the IdP Metadata
Share the **SSO URL**, **Entity ID**, and **Certificate** you copied in Step 1 with the Chainloop team.
For any SAML 2.0 compatible Identity Provider, configure a new application with the following settings:
1. Set the **SP Entity ID** (also called Audience URI or Identifier) to `https://api.app.chainloop.dev/auth/saml`
2. Set the **Assertion Consumer Service (ACS) URL** to `https://api.app.chainloop.dev/auth/saml/acs`
3. Set the **Name ID format** to email address
4. Configure the attribute mappings as described in the [attributes table above](#required-and-optional-saml-attributes)
5. If applicable, assign the users or groups that should have access
Then share your IdP metadata URL (or XML file) with the Chainloop team to complete the setup.
## Complete the Setup
Once you have configured your IdP, send the following to the Chainloop team at [support@chainloop.dev](mailto:support@chainloop.dev):
1. Your **IdP metadata URL** (preferred) or **metadata XML file**
2. The **email domains** that should be routed to this IdP (e.g. `acme.com`, `acme.io`)
The Chainloop team will register your IdP and confirm when SSO is ready. After that, users with the configured email domains will see a **Log in with SSO** option on the [Chainloop login page](https://app.chainloop.dev/login).
## How It Works
1. A user opens the Chainloop login page and clicks **Log in with SSO**
2. They enter their email address, and Chainloop discovers the matching IdP based on the email domain
3. The user is redirected to their IdP for authentication
4. After successful authentication, the IdP sends a signed SAML assertion back to Chainloop
5. Chainloop validates the assertion, provisions the user account if needed, and issues a session token
6. The user is logged in — this works for both the web application and the CLI
SAML SSO works with the Chainloop CLI as well. The CLI opens the login page in a browser, and after the SAML flow completes, the token is automatically passed back to the CLI.
## Automatic User Provisioning
Chainloop can automatically provision users into organizations and groups based on the `groups` attribute in the SAML assertion. To enable this, let the Chainloop team know when requesting your SAML setup and make sure your IdP is configured to send the `groups` attribute (see the IdP-specific steps above).
For more details on how provisioning rules work, see the [automatic provisioning guide](/guides/deployment/guides/provisioning).
## Troubleshooting
**Users see "domain not allowed" after authenticating**
The email domain returned in the SAML assertion does not match the domains registered for your IdP. Verify that the email domain(s) provided to the Chainloop team match the domains in your IdP user directory.
**Users are not automatically added to organizations**
Ensure your IdP is configured to send a `groups` attribute in the SAML assertion and that [auto-onboarding rules](/guides/deployment/guides/provisioning) are configured on the Chainloop side. Contact the Chainloop team to verify the setup.
**"SSO" option does not appear on the login page**
The Chainloop team has not yet completed the IdP registration. Confirm that you have sent the metadata URL and email domains to [support@chainloop.dev](mailto:support@chainloop.dev).