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.

Prerequisites

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)

Configuration overview

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.

Step 1: Choose Opik's Service Provider (SP) URLs

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.

Step 2: Configure your identity provider

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).

Required attribute mappings

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

Workspace sync attributes (optional)

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

Step 3: Configure Opik

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:

Required SAML settings

Optional SAML settings

Field reference

SP Entity ID

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).

ACS URL (Assertion Consumer Service)

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.

IdP Entity ID

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.

IdP SSO URL

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.

IdP X.509 Certificate

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.

Workspace synchronization

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

Enabling workspace sync

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.

How workspace sync works

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.

Attribute format for workspaces

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

engineering,data-science,ml-platform

Ensure workspace names match exactly (case-sensitive).

IdP-specific configuration guides

Configuring Okta

1. In Okta Admin Console, go to Applications > Create App Integration.
2. Select SAML 2.0 and click Next.
3. Enter an app name (e.g., "Opik") and click Next.
4. Configure SAML settings:
   • Single Sign-On URL: Your ACS URL from Opik
   • Audience URI (SP Entity ID): Your SP Entity ID from Opik
   • Name ID format: EmailAddress
   • Application username: Email
5. Add attribute statements:
   • guid → user.id
   • email → user.email
   • firstName → user.firstName
   • lastName → user.lastName
6. Complete the wizard and assign users/groups.
7. Copy the IdP Issuer, Single Sign-On URL, and X.509 Certificate to Opik.

Configuring Azure AD

1. In Azure Portal, go to Azure Active Directory > Enterprise applications.
2. Click New application > Create your own application.
3. Select Integrate any other application you don't find in the gallery.
4. Go to Single sign-on > SAML.
5. Edit Basic SAML Configuration:
   • Identifier (Entity ID): Your SP Entity ID from Opik
   • Reply URL (ACS URL): Your ACS URL from Opik
6. Edit Attributes & Claims:
   • Ensure email claim is configured
   • Add custom claims for guid, firstName, lastName
7. Download the Certificate (Base64).
8. Copy the Azure AD Identifier and Login URL to Opik.

Configuring OneLogin

1. In OneLogin Admin, go to Applications > Add App.
2. Search for "SAML Custom Connector (Advanced)" and add it.
3. Configure the application:
   • Audience (EntityID): Your SP Entity ID from Opik
   • ACS URL: Your ACS URL from Opik
   • ACS URL Validator: Your ACS URL (escaped for regex)
4. Go to Parameters and add:
   • guid → User ID
   • email → Email
   • firstName → First Name
   • lastName → Last Name
5. Go to SSO tab and copy:
   • Issuer URL → IdP Entity ID
   • SAML 2.0 Endpoint → IdP SSO URL
   • X.509 Certificate → IdP Certificate

Testing the configuration

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.

Troubleshooting

Common issues

Troubleshooting checklist

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.

Getting help

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.

Next steps

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