Skip to main content

Troubleshooting Authentication

This guide covers common authentication issues and their solutions.

Authentication Not Working​

Symptom: Users cannot log in or agents are rejected

  1. Check that auth type is correctly set:
kubectl get configmap -n zymtrace zymtrace-auth-config -o yaml | grep "AUTH"
  1. Verify signing keys are configured:
kubectl get configmap -n zymtrace zymtrace-auth-config -o yaml | grep "PRIVATE_KEY"
  1. Check service logs:
# Identity service logs
kubectl logs -n zymtrace -l app=identity --tail=100

# Gateway logs
kubectl logs -n zymtrace -l app=gateway --tail=100

OIDC Redirect Issues​

Symptom: Authentication fails after redirect from OIDC provider

  1. Verify redirect URI matches exactly what's registered:
# In your OIDC provider console
Redirect URI: https://company.example.com/api/v1/oauth2/callback

# In your values.yaml
redirectUri: "https://company.example.com/api/v1/oauth2/callback"

  1. Check for trailing slashes or protocol mismatches (http vs https)

  2. Ensure issuerUri matches your OIDC provider exactly

Token Validation Failures​

Symptom: Tokens are rejected even when valid

  1. Verify issuer and audience configuration:
kubectl get configmap -n zymtrace zymtrace-config -o yaml | grep "ISSUER"
kubectl get configmap -n zymtrace zymtrace-config -o yaml | grep "AUDIENCE"
  1. Check that public key matches private key:
# Test key pair (outside cluster)
echo "test" | openssl dgst -sha256 -sign private.pem | \
  openssl dgst -sha256 -verify public.pem -signature -
  1. Ensure gateway URL is accessible and matches issuer

Symptom: Users logged out frequently or unable to stay logged in

  1. Verify cookie settings match your deployment:
# For HTTPS deployments
secure: true

# For HTTP deployments (development only)
secure: false

  1. Check browser console for cookie warnings

  2. Verify SameSite settings for cross-domain scenarios

Service Token Issues​

Symptom: Agents or CLI tools cannot authenticate with service tokens

  1. Verify service tokens are enabled:
kubectl get configmap -n zymtrace zymtrace-auth-config -o yaml | grep "SERVICE_TOKEN"

  1. Check that the token hasn't expired

  2. Verify the token is being passed correctly to the agent:

# Check agent logs for authentication errors
kubectl logs -n zymtrace -l app=agent --tail=50
  1. Ensure the token has the correct permissions (see RBAC guide)

Permission Denied Errors​

Symptom: Users receive "permission denied" errors when accessing features

  1. Check user's assigned roles:

    • Navigate to Profile picture → Account → Users
    • Verify the user has appropriate roles

  2. Verify role permissions:

    • Navigate to Role & Permissions
    • Check that the role has the required permission patterns

Deployment Validation​

Use these commands to validate your authentication deployment:

# Check all auth-related environment variables
kubectl get configmap -n zymtrace zymtrace-auth-config -o yaml | grep -E "(AUTH|OIDC|IDENTITY|WEB__AUTH)"

# Test gateway connectivity
kubectl port-forward svc/zymtrace-gateway 8080:80 -n zymtrace
curl -v http://localhost:8080/

# Check identity service status
kubectl get pods -n zymtrace -l app=identity
kubectl logs -n zymtrace -l app=identity --tail=50

Common Error Messages​

"Invalid token"​

Cause: Token has expired, is malformed, or signing keys don't match

Solution:

  • For users: Log out and log back in
  • For agents: Generate a new service token
  • Verify signing keys are configured correctly

"Insufficient permissions"​

Cause: User's roles don't include required permissions

Solution:

  • Assign appropriate roles to the user
  • Create a custom role with required permissions
  • See RBAC guide for permission patterns

"OIDC provider unreachable"​

Cause: Cannot connect to OIDC provider's issuer URI

Solution:

  • Verify issuerUri is correct and accessible
  • Check network connectivity from the cluster
  • Verify firewall rules allow outbound HTTPS

"Redirect URI mismatch"​

Cause: The redirect URI in your config doesn't match what's registered in the OIDC provider

Solution:

  • Ensure both URIs match exactly (including protocol and trailing slashes)
  • Update OIDC provider configuration if needed
  • Redeploy with corrected configuration

Getting Help​

If you continue to experience issues:

  1. Collect logs from identity and gateway services 2Contact support at support@zymtrace.com 3Include your authentication configuration (without secrets)