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.

Artifact Hub backend

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.

Artifact Hub backend

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:
      # Option A: Pass keys inline
      privateKey: |
        -----BEGIN PRIVATE KEY-----
        ...
        -----END PRIVATE KEY-----

      publicKey: |
        -----BEGIN PUBLIC KEY-----
        ...
        -----END PUBLIC KEY-----

      # Option B: Reference an existing Kubernetes Secret (recommended for production)
      # privateKeySecretName: "zymtrace-signing-keys"
      # privateKeySecretKey: "private-key"    # key name inside the secret
      # publicKeySecretName: "zymtrace-signing-keys"
      # publicKeySecretKey: "public-key"      # key name inside the secret
Using an existing Kubernetes Secret

If you manage secrets externally (e.g. via AWS Secrets Manager, Vault, or Sealed Secrets), use privateKeySecretName and publicKeySecretName to reference them directly instead of passing key material inline.

First, create the Kubernetes Secret (run once before deploying):

kubectl create secret generic zymtrace-signing-keys \
  --namespace zymtrace \
  --from-literal=private-key="-----BEGIN PRIVATE KEY-----
<your-private-key>
-----END PRIVATE KEY-----" \
  --from-literal=public-key="-----BEGIN PUBLIC KEY-----
<your-public-key>
-----END PUBLIC KEY-----"

Then reference it in your values file:

auth:
  validation:
    keys:
      privateKeySecretName: "zymtrace-signing-keys"
      privateKeySecretKey: "private-key"
      publicKeySecretName: "zymtrace-signing-keys"
      publicKeySecretKey: "public-key"

The chart injects the key material from the named secret at deploy time, so the values file never contains sensitive key material.

If privateKeySecretName/publicKeySecretName are not set, the chart falls back to the inline privateKey/publicKey values.

The chart does not pre-check whether the referenced secret exists — doing so would require cluster read privileges at render time. If the secret is missing, the pods will fail to start. Always verify your deployment is healthy after applying:

kubectl get pods -n zymtrace
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.

Artifact Hub backend

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