SAML SSO

SAML (Security Assertion Markup Language) SSO allows your users to authenticate using your organization's identity provider (IdP). This guide walks you through configuring SAML SSO for your Opik organization.

Before you begin, ensure you have:

• Organization admin access to Opik
• Admin access to your identity provider (Okta, Azure AD, OneLogin, etc.)
• Enterprise plan enabled for your organization
• Email domain you want to use for SSO (e.g., company.com)

Setting up SAML SSO involves two main steps:

1. Configure your IdP: Add Opik as a SAML application in your identity provider.
2. Configure Opik: Enter your IdP's SAML settings in Opik's admin dashboard.

Choose matching Service Provider (SP) URLs and enter them in both Opik and your identity provider (IdP).

1. In Opik, navigate to Admin Dashboard > Organization > Authentication.
2. Toggle Enable SSO Authentication on. The SP and IdP form fields appear only once SSO is enabled.
3. Set both the SP Entity ID and the SP ACS URL to the same URL, in the format https://<your-app-base-url>/sso/saml/acs/<organization-id>. Your app base URL is the origin you use to access the admin dashboard (for example, https://www.comet.com). Your organization ID is visible in the admin dashboard URL. The last path segment is used internally as the routing key for SAML responses to your organization.

Add Opik as a new SAML application in your IdP. The specific steps vary by provider, but you'll generally need to:

1. Create a new SAML application.
2. Enter Opik's SP Entity ID and ACS URL.
3. Configure attribute mappings (see below).
4. Download or copy the IdP metadata (Entity ID, SSO URL, certificate).

Your IdP must send the following attributes in the SAML assertion:

If you want to automatically assign users to workspaces based on IdP attributes:

Once your IdP is configured, enter the settings in Opik:

1. Navigate to Admin Dashboard > Organization > Authentication.
2. Select SAML as the SSO protocol.
3. Enter the following settings:

The Service Provider Entity ID uniquely identifies Opik to your IdP. This value should be:

• A URL of the form https://<your-app-base-url>/sso/saml/acs/<organization-id>, set to the same value as the SP ACS URL.
• Entered identically in both Opik's SSO configuration form and your IdP's SAML application configuration.
• Consistent between Opik and your IdP (case-sensitive).

The ACS URL is where your IdP sends the SAML assertion after successful authentication:

• Must be an HTTPS URL.
• Must match exactly between Opik and your IdP configuration.
• Opik validates this URL when processing assertions.

Your identity provider's unique identifier. Find this in your IdP's SAML metadata or configuration:

• Okta: Found in the SAML setup instructions or metadata XML.
• Azure AD: The "Identifier (Entity ID)" in the SAML configuration.
• OneLogin: The "Issuer URL" in the SSO settings.

The URL where users are redirected to authenticate. This is the entry point for the SAML authentication flow:

• Usually ends in /sso/saml or similar.
• Found in your IdP's SAML configuration or metadata.

The public certificate used to verify SAML assertion signatures:

• Must be in PEM format (starting with -----BEGIN CERTIFICATE-----).
• Download from your IdP's SAML configuration.
• Multiple certificates can be provided if your IdP is rotating keys.

Enable workspace sync to automatically assign users to workspaces based on IdP attributes.

1. In the SSO configuration, enable Sync Workspaces.
2. Configure your IdP to send workspace information as a SAML attribute.
3. Map the attribute to Opik workspace names.

When a user authenticates via SAML with workspace sync enabled:

1. Opik reads the workspace attribute from the SAML assertion.
2. User is added to the specified workspaces (created if they don't exist).
3. User is removed from workspaces not listed in the attribute.

The workspace attribute should contain a comma-separated list of workspace names:

engineering,data-science,ml-platform

Ensure workspace names match exactly (case-sensitive).

After configuring both Opik and your IdP:

1. Open an incognito/private browser window (to avoid cached sessions).
2. Navigate to Opik's login page.
3. Enter an email address with your configured domain.
4. You should be redirected to your IdP for authentication.
5. After authenticating, you should be redirected back to Opik and logged in.

1. Verify domain configuration: Ensure the email domain matches your SSO configuration.
2. Check Entity IDs: Both SP and IdP Entity IDs must match exactly (case-sensitive).
3. Validate ACS URL: The ACS URL must be identical in both Opik and your IdP.
4. Review attribute mapping: Ensure guid and email attributes are sent by your IdP.
5. Check certificate format: Certificate should be in PEM format with headers.
6. Test with debug enabled: Enable IdP Debug to see detailed error messages.
7. Check IdP logs: Review your identity provider's logs for SAML errors.

If you continue to experience issues:

1. Gather debug logs with IdP Debug enabled.
2. Capture the SAML assertion (available in browser developer tools or IdP logs).
3. Contact Opik support with the logs and assertion for assistance.

• Configure OIDC as an alternative SSO method.
• Set up JWT authentication for programmatic access.
• Manage users and their workspace assignments.