AdministrationAuthentication

Authentication Overview

Understanding authentication options and choosing the right approach

Opik supports multiple authentication methods to integrate with your organization’s identity management infrastructure. This guide helps you understand the available options and choose the right approach for your needs.

Authentication features are available on Enterprise plans. These features are not available in open-source deployments. Reach out if you want to enable SSO or JWT authentication for your Opik deployment.

Authentication methods

Opik supports multiple authentication methods for enterprise organizations. For configurable UI access, you can set up SAML SSO or OIDC SSO to integrate with your identity provider. Other available methods include base authentication (username/password), Google OAuth, GitHub OAuth, and LDAP (for on-premises deployments). JWT Authentication is available separately for SDK and programmatic access. Unlike SAML SSO and OIDC SSO, JWT Authentication is designed for service-to-service and API integrations, not for user interface login.

MethodBest forKey features
SAML SSOOrganizations with enterprise IdPs (Okta, Azure AD, etc.)Workspace sync, attribute mapping, broad IdP support
OIDC SSOOrganizations using OAuth 2.0 / OpenID ConnectSimpler setup, token-based, modern protocol
JWT AuthenticationProgrammatic access, custom auth flowsFlexible integration, JWKS support, service-to-service auth

Choosing an authentication method

Use this decision guide to select the right authentication method:

Use SAML SSO when:

  • Your organization already uses an enterprise identity provider (Okta, Azure AD, OneLogin, etc.)
  • You need automatic workspace assignment based on user attributes/groups
  • You require centralized user lifecycle management (auto-provisioning/deprovisioning)
  • Your security policies mandate SAML-based authentication

Use OIDC SSO when:

  • Your identity provider supports OpenID Connect but not SAML
  • You prefer a simpler, more modern protocol
  • You’re using a cloud-native identity solution
  • You don’t need attribute-based workspace sync

Use JWT Authentication when:

  • You need programmatic/API access from backend services
  • You’re building custom authentication flows
  • You want to integrate with existing JWT-based systems
  • You need service-to-service authentication

Multiple methods: You can configure multiple authentication methods for your organization. For example, use SAML for human users and JWT for service accounts.

Common prerequisites

Before configuring any authentication method, ensure you have:

  1. Admin access: You must be an organization administrator.
  2. Enterprise plan: SSO features require an Enterprise subscription.
  3. Domain ownership: You should control the email domain(s) you want to use for SSO.
  4. IdP access (for SSO): Admin access to your identity provider to configure the integration.

Glossary

Understanding these terms will help you configure authentication:

General terms

TermDescription
IdP (Identity Provider)The system that authenticates users (e.g., Okta, Azure AD, Google Workspace)
SP (Service Provider)The application users are logging into (Opik)
SSO (Single Sign-On)Authentication method allowing users to log in once and access multiple applications
DomainYour organization’s email domain (e.g., company.com) used to route users to SSO

SAML-specific terms

TermDescription
Entity IDUnique identifier for the IdP or SP in a SAML configuration
ACS URL (Assertion Consumer Service)URL where the IdP sends authentication responses
IdP SSO URLURL where users are redirected to authenticate
X.509 CertificatePublic certificate used to verify SAML assertions
Attribute MappingConfiguration that maps IdP user attributes to Opik fields
Workspace SyncFeature that automatically assigns users to workspaces based on IdP attributes

OIDC-specific terms

TermDescription
Client IDUnique identifier for Opik in your IdP
Client SecretSecret key used to authenticate Opik with your IdP
Authorization URLURL where users are redirected to authenticate
Token URLURL where Opik exchanges authorization codes for tokens
Callback URLURL where the IdP redirects users after authentication
ScopePermissions requested from the IdP (e.g., openid, profile, email)

JWT-specific terms

TermDescription
JWKS (JSON Web Key Set)Endpoint providing public keys for JWT verification
JWKS URIURL of the JWKS endpoint
Static Public KeyAlternative to JWKS; a fixed public key for verification (on-prem only)
IssuerThe entity that issued the JWT token
AudienceThe intended recipient of the JWT token
SubjectThe user or entity the token represents
Subject MappingHow Opik identifies users from JWT claims (EMAIL or USER_NAME)
Subject Claim NameThe JWT claim containing the subject (defaults to sub)
kid (Key ID)Identifier in the JWT header specifying which key to use for verification

Authentication flow comparison

SAML authentication flow

┌──────┐      ┌──────┐      ┌──────┐
│ User │      │ Opik │      │  IdP │
└──┬───┘      └──┬───┘      └──┬───┘
   │   1. Login   │             │
   │────────────>│             │
   │             │ 2. Redirect │
   │             │────────────>│
   │             │             │ 3. User authenticates
   │             │<────────────│
   │             │ 4. SAML     │
   │             │   Assertion │
   │<────────────│             │
   │ 5. Logged in│             │
   └─────────────┘             │

OIDC authentication flow

┌──────┐      ┌──────┐      ┌──────┐
│ User │      │ Opik │      │  IdP │
└──┬───┘      └──┬───┘      └──┬───┘
   │   1. Login   │             │
   │────────────>│             │
   │             │ 2. Redirect │
   │────────────────────────-->│
   │             │             │ 3. User authenticates
   │<──────────────────────────│
   │ 4. Auth code│             │
   │────────────>│             │
   │             │ 5. Exchange │
   │             │    for token│
   │             │────────────>│
   │             │<────────────│
   │             │ 6. Token    │
   │<────────────│             │
   │ 7. Logged in│             │

JWT authentication flow

┌──────────┐      ┌──────┐      ┌──────┐
│ Service/ │      │ Opik │      │ JWKS │
│   User   │      │      │      │      │
└────┬─────┘      └──┬───┘      └──┬───┘
     │   1. API call │             │
     │   with JWT    │             │
     │──────────────>│             │
     │               │ 2. Fetch    │
     │               │    keys     │
     │               │────────────>│
     │               │<────────────│
     │               │ 3. Verify   │
     │               │    JWT      │
     │<──────────────│             │
     │ 4. Response   │             │

Configuration guides

Detailed setup instructions are available for each authentication method:

SAML SSO

Configure SAML-based single sign-on with enterprise identity providers.

OIDC SSO

Set up OpenID Connect authentication for your organization.

JWT Authentication

Configure JWT-based authentication for programmatic access.

Security considerations

Domain verification

When configuring SSO, you associate email domains with your organization. This ensures:

  • Users with those email domains are directed to your SSO configuration.
  • Only users who authenticate through your IdP can access the organization.

Important: Ensure you only configure domains you own or control. Misconfigured domains could prevent legitimate users from accessing their accounts.

Certificate management

For SAML authentication:

  • Store IdP certificates securely.
  • Monitor certificate expiration dates.
  • Plan for certificate rotation to avoid authentication disruptions.

Key rotation

For JWT authentication:

  • Use JWKS endpoints when possible for automatic key rotation.
  • If using static keys (on-prem only), establish a key rotation schedule.
  • Monitor JWKS endpoint availability.

Troubleshooting

Common authentication issues and solutions:

IssuePossible causesSolution
User can’t log in via SSODomain not configured, IdP misconfiguredVerify domain settings, check IdP configuration
User lands in wrong organizationMultiple SSO configs for same domainReview domain-to-organization mappings
Workspace sync not workingAttribute mapping incorrectVerify IdP sends expected attributes
JWT validation failsKey mismatch, expired token, wrong issuerCheck JWKS endpoint, verify token claims
Certificate errorsExpired or wrong certificateUpdate certificate in SSO configuration

Next steps