OIDC SSO

OpenID Connect (OIDC) is a modern authentication protocol built on OAuth 2.0. This guide walks you through configuring OIDC SSO for your Opik organization.

Prerequisites

Before you begin, ensure you have:

• Organization admin access to Opik
• Admin access to your identity provider that supports OIDC
• Enterprise plan enabled for your organization
• Email domain you want to use for SSO (e.g., company.com)

OIDC vs. SAML

OIDC offers several advantages over SAML:

Choose OIDC when:

• Your IdP supports OIDC (most modern IdPs do)
• You prefer simpler configuration
• You don’t need attribute-based workspace sync

Choose SAML when:

• You need automatic workspace assignment based on user attributes
• Your organization requires SAML specifically

Configuration overview

Setting up OIDC SSO involves:

1. Register Opik in your identity provider as an OIDC application.
2. Configure Opik with your IdP’s OIDC endpoints and credentials.

Step 1: Register Opik in your IdP

Create a new OIDC/OAuth application in your identity provider:

Application settings

Required scopes

Ensure your OIDC application requests these scopes:

• openid - Required for OIDC
• profile - User profile information
• email - User’s email address

Step 2: Gather IdP information

After registering the application, collect the following from your IdP:

Step 3: Configure Opik

1. Navigate to Admin Dashboard > SSO Configuration.
2. Select OIDC as the SSO protocol.
3. Enter the following settings:

Required OIDC settings

Optional OIDC settings

Field reference

Client ID

The unique identifier assigned to Opik when you registered it with your IdP:

• Created when you register the application
• Used in authorization requests to identify Opik
• Should be treated as public (not secret)

Client Secret

The secret key used to authenticate Opik with your IdP:

• Created when you register the application
• Used when exchanging authorization codes for tokens
• Must be kept secret - never expose in client-side code

Authorization URL (Auth Base URL)

The endpoint where users are redirected to authenticate:

https://idp.company.com/oauth/authorize

This URL receives authorization requests with:

• client_id - Your application’s client ID
• redirect_uri - The callback URL
• scope - Requested permissions
• response_type - Always code for authorization code flow
• state - Security parameter to prevent CSRF

Token URL (Access Token URL)

The endpoint where Opik exchanges authorization codes for access tokens:

https://idp.company.com/oauth/token

Opik sends a POST request with:

• grant_type - Always authorization_code
• code - The authorization code received
• redirect_uri - The callback URL
• client_id and client_secret - For authentication

Callback URL

The URL where your IdP redirects users after authentication:

https://www.comet.com/opik/oauth/callback/<organization-id>

• Must be registered in your IdP’s allowed redirect URIs
• Must match exactly (including trailing slashes)
• Opik generates this URL based on your organization ID

Protected Resource URL (User Info URL)

The endpoint where Opik fetches user profile information:

https://idp.company.com/oauth/userinfo

Opik uses the access token to request:

• sub - User’s unique identifier
• email - User’s email address
• name - User’s display name

Default Workspace

When users authenticate via OIDC for the first time:

• They are added to the default workspace specified in SSO settings.
• If not specified, they are added to the organization’s default workspace.
• Workspace assignment can be managed manually after initial login.

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 client credentials: Double-check client ID and secret.
2. Check callback URL: Must match exactly (including protocol, trailing slashes).
3. Validate endpoint URLs: Ensure all URLs are correct and accessible.
4. Review IdP logs: Check your identity provider’s logs for errors.
5. Test well-known endpoint: Verify /.well-known/openid-configuration returns valid JSON.
6. Check scopes: Ensure required scopes are configured and allowed.

Debugging with browser tools

Use browser developer tools to inspect the authentication flow:

1. Open Network tab before starting login.
2. Look for requests to your IdP’s authorization endpoint.
3. Check for error parameters in the callback URL.
4. Review any error responses from the token endpoint.

Security considerations

Client secret protection

• Store the client secret securely in Opik’s configuration.
• Never expose the client secret in logs or client-side code.
• Rotate the secret periodically per your security policies.

Callback URL validation

• Only configure the exact callback URL provided by Opik.
• Do not add additional redirect URIs unless necessary.
• Review registered redirect URIs periodically.

Token handling

Opik handles tokens securely:

• Access tokens are used server-side only.
• Tokens are not exposed to the browser.
• Sessions are managed securely after authentication.

Next steps

• Configure SAML if you need workspace sync features.
• Set up JWT authentication for programmatic access.
• Manage users and workspace assignments.