OIDC Authentication

OIDC authentication integrates with external identity providers like Google, Okta, Azure AD, or any OpenID Connect-compatible service.

Configuration

Add the following to your custom-values.yaml:

custom-values.yaml

auth:
  type: "oidc"

  # Admin user (required)
  admin:
    email: admin@company.com
    password: "your-secure-password"
    roles:
      - "System Admin"

  # OIDC provider configuration
  oidc:
    provider:
      # REQUIRED: OAuth2 client credentials from your OIDC provider
      clientId: "your-client-id"
      clientSecret: "your-client-secret"

      # REQUIRED: Your OIDC provider's issuer URI
      # Examples:
      #   Google: https://accounts.google.com
      #   Okta: https://dev-123456.okta.com
      #   Azure AD: https://login.microsoftonline.com/{tenant-id}/v2.0
      issuerUri: "https://accounts.google.com"

      # REQUIRED: Redirect URI after authentication
      # Must match what's registered in your OIDC provider
      # Auto-derived from ingress host if not specified
      redirectUri: "https://company.example.com/api/v1/oauth2/callback"

Refer to the local authentication guide to create signing keys for production deployments. Refer to the OIDC configuration for additional OIDC options.

Issuer Configuration

The issuers field must match your actual deployment URL. If you're deploying to https://company.example.com, use that exact URL. The issuer is used to validate JWT tokens and must match the domain where your zymtrace gateway is accessible.

Setting Up OIDC Providers

Google

Google Cloud Console Setup

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Navigate to APIs & Services → Credentials
4. Click Create Credentials → OAuth 2.0 Client ID
5. Select Web application
6. Add authorized redirect URI: https://company.example.com/api/v1/oauth2/callback
7. Copy the Client ID and Client Secret

Configuration for Google

custom-values.yaml

auth:
  type: "oidc"
  oidc:
    provider:
      clientId: "YOUR-CLIENT-ID.apps.googleusercontent.com"
      clientSecret: "GOCSPX-YOUR-CLIENT-SECRET"
      issuerUri: "https://accounts.google.com"
      redirectUri: "https://company.example.com/api/v1/oauth2/callback"
      scopes:
        - openid
        - email
        - profile
      extraParams:
        - prompt=consent
        - access_type=offline

Okta

Okta Setup

1. Log in to your Okta Admin Console
2. Navigate to Applications → Applications
3. Click Create App Integration
4. Select OIDC - OpenID Connect and Web Application
5. Add sign-in redirect URI: https://company.example.com/api/v1/oauth2/callback
6. Copy the Client ID and Client Secret

Configuration for Okta

custom-values.yaml

auth:
  type: "oidc"
  oidc:
    provider:
      clientId: "YOUR-OKTA-CLIENT-ID"
      clientSecret: "YOUR-OKTA-CLIENT-SECRET"
      issuerUri: "https://dev-YOUR-OKTA-DOMAIN.okta.com"
      redirectUri: "https://company.example.com/api/v1/oauth2/callback"
      scopes:
        - openid
        - email
        - profile

Azure AD

Azure AD Setup

1. Go to Azure Portal
2. Navigate to Azure Active Directory → App registrations
3. Click New registration
4. Add redirect URI: https://company.example.com/api/v1/oauth2/callback
5. Go to Certificates & secrets → Create a new client secret
6. Copy the Application (client) ID and Client Secret

Configuration for Azure AD

custom-values.yaml

auth:
  type: "oidc"
  oidc:
    provider:
      clientId: "YOUR-APPLICATION-CLIENT-ID"
      clientSecret: "YOUR-CLIENT-SECRET"
      issuerUri: "https://login.microsoftonline.com/YOUR-TENANT-ID/v2.0"
      redirectUri: "https://company.example.com/api/v1/oauth2/callback"
      scopes:
        - openid
        - email
        - profile

Deployment

Deploy your backend with the OIDC configuration:

helm upgrade --install backend zymtrace/backend \
  --namespace zymtrace \
  -f custom-values.yaml

Accessing the System

1. Navigate to your zymtrace URL: https://zymtrace.company.com
2. Click the OIDC login button
3. Authenticate through your OIDC provider
4. You'll be redirected back to zymtrace

Once authenticated, you can access your profile and account settings:

Advanced Configuration

For cookie settings and token validation options, see the advanced configuration guide.