Skip to main content

Advanced Configuration

This guide covers advanced authentication configuration options that apply to both local and OIDC authentication methods.

Cookie settings control how authentication sessions are managed in zymtrace. These settings apply when using local or oidc authentication.

custom-values.yaml
auth:
  cookie:
    # Refresh token cookie lifespan (in seconds)
    # Default: 31536000 (1 year)
    refreshMaxAgeSec: 31536000

    # Path for refresh token cookie
    refreshPath: /

    # Login/access token cookie lifespan (in seconds)
    # Default: 60 (1 minute)
    loginMaxAgeSec: 60

    # Path for login cookie (typically /api/v1/oauth2 for OIDC)
    loginPath: /

    # SameSite cookie attribute: "strict", "lax", or "none"
    sameSite: lax

    # Secure flag (requires HTTPS)
    secure: true

    # HttpOnly flag (prevents JavaScript access)
    httpOnly: true

    # OIDC cookie TTL during OAuth flow (in seconds)
    cookieTtlSec: 60
Cookie Security
  • Always set secure: true in production (requires HTTPS)
  • Keep httpOnly: true to prevent XSS attacks
  • Use sameSite: lax or sameSite: strict for CSRF protection

Token Validation​

Token validation settings control how JWT tokens are verified throughout the system. These settings apply to both local and oidc authentication.

custom-values.yaml
auth:
  validation:
    # List of valid token issuers (optional)
    # If empty or not specified, auto-derived from ingress host
    # Example: If your ingress host is company.example.com, issuer will be https://company.example.com
    issuers: [ ]
    # Or specify explicitly:
    # issuers:
    #   - "https://zymtrace.company.com"

    # List of valid token audiences (optional)
    # If empty or not specified, defaults to ["zymtrace"]
    audiences: [ ]
    # Or specify explicitly:
    # audiences:
    #   - "domain"
    #   - "some-api"

    # Signing keys for token verification (REQUIRED)
    keys:
      privateKey: |
        -----BEGIN PRIVATE KEY-----
        ...
        -----END PRIVATE KEY-----

      publicKey: |
        -----BEGIN PUBLIC KEY-----
        ...
        -----END PUBLIC KEY-----
Auto-Derived Values

Most deployments can leave issuers and audiences empty to use auto-derived defaults:

  • Issuers: Automatically set to your ingress host URL (e.g., https://company.example.com)
  • Audiences: Automatically set to ["zymtrace"]

Only specify these explicitly if you know why you need it.

OIDC Configuration​

By default, scopes and extraParams are configured to support the usual GCP authentication flow. If you're using a different OIDC provider, you can customize the configuration using the following example.

custom-values.yaml
auth:
  type: "oidc"

  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"

      # OAuth2 scopes to request
      scopes:
        - openid
        - email
        - profile

      # Additional OAuth2 parameters (optional)
      # These are passed as query parameters to the OIDC provider
      extraParams:
        - prompt=consent        # Force consent screen on Google
        - access_type=offline   # Request refresh token from Google

Branding​

You can customize the text your users see when authenticating with zymtrace.

custom-values.yaml
auth:
  info:
    displayName: "my custom zymtrace deployment"
    pictureUri: null