Testing vouch-proxy configuration

This guide provides instructions for testing your Identity Provider (IdP) configuration using the official vouch-proxy Helm chart in an isolated environment before integrating with Patronus AI.

Why test vouch-proxy separately?

Testing vouch-proxy in isolation allows you to:

• Verify your IdP OAuth configuration is correct
• Test SSO authentication flow independently
• Troubleshoot authentication issues without affecting your Patronus deployment
• Validate JWT token structure and claims before configuring role mappings
• Ensure redirect URIs and callback URLs are properly configured

Prerequisites

Before proceeding, ensure you have:

• Kubernetes cluster with kubectl access
• Helm 3.8.0 or above installed
• Identity Provider (IdP) OAuth application configured (see cloud provider-specific guides)
• Basic understanding of OAuth 2.0 and JWT tokens

Step 1: Configure your IdP OAuth application

Before deploying vouch-proxy, ensure your IdP OAuth application is configured with the test callback URL.

Add test callback URL

In your IdP's OAuth application settings, add the vouch-proxy callback URL:

https://<TEST_DOMAIN>/auth

Replace <TEST_DOMAIN> with the domain you'll use for testing (e.g., vouch-test.example.com).

Gather OAuth credentials

You'll need the following from your IdP:

• Client ID - OAuth application identifier
• Client Secret - OAuth application secret
• Authorization endpoint - IdP's OAuth authorization URL
• Token endpoint - IdP's token exchange URL
• User info endpoint - IdP's user information endpoint (if applicable)

auth_url: https://accounts.google.com/o/oauth2/v2/auth
token_url: https://oauth2.googleapis.com/token
user_info_url: https://openidconnect.googleapis.com/v1/userinfo
scopes:
  - openid
  - email
  - profile

Step 2: Create vouch-proxy configuration

Create a values.yaml file for vouch-proxy with your IdP configuration.

Basic configuration template

Create a file named vouch-values.yaml:

config:
  vouch:
    # Domain where vouch-proxy will be accessible
    domains:
      - <TEST_DOMAIN>
 
    # Cookie configuration
    cookie:
      # Must match your domain
      domain: <TEST_DOMAIN>
      # Secure cookies (use true for HTTPS)
      secure: true
      # Cookie name
      name: VouchCookie
 
    # Session configuration
    session:
      name: VouchSession
      key: <RANDOM_SECRET_KEY>  # Generate with: openssl rand -base64 32
 
    # JWT configuration
    jwt:
      secret: <RANDOM_JWT_SECRET>  # Generate with: openssl rand -base64 32
      issuer: Vouch
      maxAge: 240  # 4 hours in minutes
      compress: true
 
  oauth:
    # OAuth provider (google, oidc, azure, etc.)
    provider: <PROVIDER>
 
    # OAuth client configuration
    client_id: <YOUR_CLIENT_ID>
    client_secret: <YOUR_CLIENT_SECRET>
 
    # OAuth endpoints
    auth_url: <AUTHORIZATION_URL>
    token_url: <TOKEN_URL>
    user_info_url: <USER_INFO_URL>
 
    # OAuth scopes
    scopes:
      - openid
      - email
      - profile
 
    # Callback URL
    callback_url: https://<TEST_DOMAIN>/auth
 
# Ingress configuration
ingress:
  enabled: true
  className: nginx  # Or your ingress controller class
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod  # If using cert-manager
  hosts:
    - host: <TEST_DOMAIN>
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: vouch-test-tls
      hosts:
        - <TEST_DOMAIN>

Generate secrets

Generate random secrets for session and JWT:

# Session key
openssl rand -base64 32
 
# JWT secret
openssl rand -base64 32

Copy these values into your vouch-values.yaml file.

Step 3: Deploy vouch-proxy

Deploy vouch-proxy using the official Helm chart.

Add vouch-proxy Helm repository

helm repo add vouch https://vouch.github.io/helm-charts/
helm repo update

Create namespace

kubectl create namespace vouch-test

Deploy vouch-proxy

helm install vouch-test vouch/vouch \
  --namespace vouch-test \
  --values vouch-values.yaml

Verify deployment

Check that vouch-proxy is running:

kubectl get pods -n vouch-test

Expected output:

NAME                     READY   STATUS    RESTARTS   AGE
vouch-xxxxxxxxxx-xxxxx   1/1     Running   0          30s

Check the ingress:

kubectl get ingress -n vouch-test

Step 4: Test authentication flow

Now test the authentication flow to verify your IdP configuration.

Access the validate endpoint

Navigate to the validate endpoint in your browser:

https://<TEST_DOMAIN>/validate

Expected behavior:

1. You should be redirected to your IdP's login page
2. After authenticating, you should be redirected back to vouch-proxy
3. If successful, you'll see a 200 OK response or be redirected to /

Test the login endpoint

You can also test the login endpoint directly:

https://<TEST_DOMAIN>/login

This will initiate the OAuth flow.

Common test scenarios

Successful authentication:

• Browser redirects to IdP login
• After login, redirects back to vouch-proxy
• Cookie is set in browser
• Subsequent requests to /validate return 200 OK

Failed authentication:

• Check vouch-proxy logs for error messages
• Verify OAuth credentials are correct
• Ensure callback URL matches IdP configuration

Step 5: Inspect JWT token

After successful authentication, inspect the JWT token to understand its structure for role mapping configuration.

View token information

Navigate to the health endpoint:

https://<TEST_DOMAIN>/healthcheck

This returns vouch-proxy status and configuration.

Extract JWT token from cookie

Use browser developer tools to extract the JWT token:

1. Open browser developer tools (F12)
2. Go to Application > Cookies
3. Find the VouchCookie cookie
4. Copy the cookie value

Decode the JWT token

Use JWT.io to decode the token:

1. Navigate to https://jwt.io
2. Paste the JWT token into the "Encoded" field
3. View the decoded payload in the "Decoded" section

Example token payload:

{
  "iss": "https://accounts.google.com",
  "sub": "1234567890",
  "email": "user@example.com",
  "email_verified": true,
  "name": "John Doe",
  "groups": ["engineering", "admin"],
  "aud": "your-client-id.apps.googleusercontent.com",
  "iat": 1516239022,
  "exp": 1516242622
}

Document token structure

Note the following for role mapping configuration:

• Available claims (email, groups, sub, etc.)
• Claim values that identify users or groups
• Token issuer (iss claim)
• Custom claims specific to your IdP

Step 6: Check vouch-proxy logs

Review logs to troubleshoot issues or verify successful authentication.

View logs

kubectl logs -n vouch-test deployment/vouch-test-vouch --tail=50 --follow

Common log messages

Successful authentication:

INFO successful authentication for user@example.com
INFO setting cookie for user@example.com

Failed authentication:

ERROR oauth token exchange failed: invalid_client
ERROR callback error: state parameter mismatch

Configuration errors:

ERROR missing required config: oauth.client_id
WARN invalid callback_url configuration

Step 7: Test specific OAuth scenarios

Perform additional tests to validate edge cases.

Test logout flow

Navigate to the logout endpoint:

https://<TEST_DOMAIN>/logout

This should clear the session and cookie. Subsequent requests to /validate should redirect to login.

Test token expiration

Wait for the JWT maxAge to expire (default 4 hours) and verify that re-authentication is required.

Test multiple users

If testing group-based access, authenticate with different users to verify claim variations.

Step 8: Validate configuration for Patronus integration

Before integrating with Patronus, verify your configuration meets requirements.

Configuration checklist

• Authentication flow completes successfully
• JWT token contains required claims (email or unique identifier)
• JWT token structure is documented
• Cookie domain is correctly configured
• TLS/HTTPS is properly configured
• Callback URLs match IdP configuration
• Session and JWT secrets are secure and random

Clean up test deployment

After validation, you can remove the test deployment:

helm uninstall vouch-test --namespace vouch-test
kubectl delete namespace vouch-test

Troubleshooting

Cannot access vouch-proxy

Issue: Unable to reach https://<TEST_DOMAIN>

Solutions:

• Verify DNS resolves to your cluster ingress IP:

  nslookup <TEST_DOMAIN>

• Check ingress controller is running:

  kubectl get pods -n ingress-nginx

• Verify ingress configuration:

  kubectl describe ingress -n vouch-test

• Check TLS certificate status (if using cert-manager):

  kubectl get certificate -n vouch-test

OAuth authentication fails

Issue: Redirected to IdP but authentication fails

Solutions:

• Verify Client ID and Secret are correct
• Check callback URL matches exactly in IdP configuration
• Ensure scopes are supported by your IdP
• Review vouch-proxy logs for specific error messages:

  kubectl logs -n vouch-test deployment/vouch-test-vouch

• Verify OAuth endpoints are correct for your IdP

Cookie not being set

Issue: Authentication completes but cookie is not set

Solutions:

• Verify cookie.domain matches your test domain
• Ensure cookie.secure is true when using HTTPS
• Check browser console for cookie-related errors
• Verify SameSite cookie policies are compatible

State parameter mismatch

Issue: Error message about state parameter mismatch

Solutions:

• Ensure session storage is working properly
• Check that session key is configured
• Verify clock synchronization between vouch-proxy and IdP
• Clear browser cookies and try again

Invalid redirect URI error

Issue: IdP shows "invalid redirect URI" error

Solutions:

• Verify callback URL in vouch-values.yaml matches IdP configuration exactly
• Ensure use https protocol
• Check for trailing slashes or path differences
• Confirm the OAuth application allows the redirect URI

Next steps

After successfully testing vouch-proxy configuration:

1. Accounts and Authentication - Configure authentication in Patronus
2. Integrate vouch-proxy configuration into Patronus values.yaml
   • Deployment in AWS with Amazon Cognito
   • Deployment in Azure with Microsoft Entra ID
   • Deployment in GCP with Google Identity
3. Accounts and Authentication - Configure authentication in Patronus
4. Configure role mappings based on JWT token structure
5. Test end-to-end authentication with Patronus AI

Additional resources

• Vouch Proxy Documentation
• Vouch Proxy Helm Chart
• Vouch Proxy Examples
• JWT.io Token Inspector
• OAuth 2.0 Debugger

← Back to Self Hosting Guide