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: Gather Opik’s SAML settings

Before configuring your IdP, you’ll need Opik’s Service Provider (SP) settings.

Navigate to Admin Dashboard > SSO Configuration to view:

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 > SSO Configuration.
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:

• Copied exactly as shown in the Opik SSO configuration page.
• Entered in 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

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.