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.
This feature is only available on Chainloop’s platform paid plans. 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. |
IdP-Specific Configuration
Step 1: Create a New SAML Application
- In the Okta Admin Console, go to Applications > Applications
- Click Create App Integration
- Select SAML 2.0 and click Next
- Enter a name (e.g.
Chainloop) and click Next
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 |
| 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 |
| 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.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
- In the Azure portal, go to Microsoft Entra ID > Enterprise Applications
- Click New application > Create your own application
- 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
- In your new application, go to Single sign-on and select SAML
- 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 |
| 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 |
- Click Add a group claim
- Select Groups assigned to the application
- 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.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
- In the Google Admin console, go to Apps > Web and mobile apps
- Click Add app > Add custom SAML app
- Enter a name (e.g.
Chainloop) and click Continue
- 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.
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 |
| 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 |
groups.Step 4: Enable the Application
- Click Finish to create the application
- Click on the application, then go to User access
- Turn the service ON for the organizational units or groups that should have access
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:
- Set the SP Entity ID (also called Audience URI or Identifier) to
https://api.app.chainloop.dev/auth/saml
- Set the Assertion Consumer Service (ACS) URL to
https://api.app.chainloop.dev/auth/saml/acs
- Set the Name ID format to email address
- Configure the attribute mappings as described in the attributes table above
- 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 [email protected]:
- Your IdP metadata URL (preferred) or metadata XML file
- 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.
How It Works
- A user opens the Chainloop login page and clicks Log in with SSO
- They enter their email address, and Chainloop discovers the matching IdP based on the email domain
- The user is redirected to their IdP for authentication
- After successful authentication, the IdP sends a signed SAML assertion back to Chainloop
- Chainloop validates the assertion, provisions the user account if needed, and issues a session token
- 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.
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 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 [email protected].
