Deploying Genesis - Azure AKS with OIDC Authentication

This guide walks through setting up Azure AD authentication for Genesis deployed on Azure Kubernetes Service (AKS) using native OIDC authentication — no OAuth2 Proxy required.

Overview

Genesis supports native OIDC authentication using Authorization Code Flow + PKCE. This approach:

No OAuth2 Proxy needed — Genesis handles authentication directly
Simpler architecture — Fewer moving parts to configure and maintain
Browser-native — Works with all modern browsers including Safari and Chrome Incognito
Automatic token refresh — Uses refresh tokens, not iframe-based silent renew
WebSocket support — Authenticated real-time connections

Architecture

User clicks login → redirected to Azure AD
User authenticates → returns with authorization code
Frontend exchanges code for Access Token + Refresh Token (PKCE flow)
API calls use Authorization: Bearer <token> header
Token refresh handled automatically (no user interaction)

Prerequisites

AKS cluster with NGINX ingress controller installed
Azure CLI installed and authenticated
kubectl configured to access your AKS cluster
Helm 3.x installed
Sufficient node resources (Standard_D4s_v3 or larger recommended)

Hostname Configuration

For Testing/Development: This guide uses nip.io for quick testing (e.g., genesis-oidc.172.214.4.208.nip.io). nip.io is a free DNS service that maps any IP to a hostname. Only use nip.io for testing and development.For Production: You must create a permanent DNS name (e.g., genesis-oidc.yourcompany.com). Create a DNS A record pointing your domain to the ingress IP address, update all configuration files to use your permanent domain name, update Azure AD redirect URIs to use your permanent domain, and configure TLS certificates for HTTPS (required for production).

Step 1: Scale AKS Node Pool (if needed)

If you have resource constraints, ensure adequate capacity:

# Check current nodes
kubectl get nodes

# Scale node pool if needed
az aks nodepool scale \
    --resource-group <resource-group> \
    --cluster-name <cluster-name> \
    --nodepool-name <nodepool-name> \
    --node-count 2 \
    --no-wait

# Verify nodes are ready
kubectl get nodes -w

Step 2: Create Azure AD App Registration

Using Azure Portal (Recommended)

Navigate to Azure Portal → Microsoft Entra ID → App registrations
Click “New registration”
Configure:
- Name: Genesis (or your preferred name)
- Supported account types: Single tenant (recommended)
- Redirect URI: Leave empty for now
Click “Register”
Copy these values (you’ll need them later):
- Application (client) ID → This is your AUTH0_CLIENT_ID
- Directory (tenant) ID → Used in AUTH_ISSUER

Configure Authentication Platform

Go to Authentication blade (left sidebar)
Click “Add a platform”
Select “Single-page application” (NOT “Web”!)
Enter Redirect URI:
- For Testing: http://genesis-oidc.<INGRESS_IP>.nip.io or https://genesis-oidc.<INGRESS_IP>.nip.io
- For Production: https://genesis-oidc.yourcompany.com (your permanent domain)
- Important: No trailing slash, no /callback path — just the origin
Click “Configure”
If hosted MCP for Claude Code will be enabled, click “Add a platform” again, select “Mobile and desktop applications”, and add this redirect URI:
http://localhost:31318/callback
This is Claude Code’s local loopback callback. It does not require inbound network access to the user’s laptop; after Microsoft sign-in, the user’s browser redirects to localhost on the same machine.
Under “Implicit grant and hybrid flows”:
- Leave BOTH unchecked (ID tokens AND Access tokens)
- We use Authorization Code + PKCE, not Implicit flow
Click “Save”

Configure Token Claims (Important)

Azure AD doesn’t include email in tokens by default. To fix:

Go to Token configuration blade
Click “Add optional claim”
Select ID token type
Check: email, upn, preferred_username
Click “Add”

Checklist

Platform type is “Single-page application” (not “Web”)
Redirect URI is exact origin without trailing slash
Hosted MCP public/native redirect URI is added: http://localhost:31318/callback
Implicit grant checkboxes are BOTH unchecked
Optional claims added: email, upn, preferred_username

Step 3: Configure values-aks-oidc.yaml

Copy and edit the values file from your Genesis deployment bundle:

cp Azure/values-aks-oidc.yaml Azure/my-values-oidc.yaml

Required Configuration

Edit Azure/my-values-oidc.yaml with your values:

# Namespace
namespace: genesis-oidc

# Container image
image:
  repository: ghcr.io/genesis-computing-ai/genesis
  tag: v1.18.2
  pullPolicy: IfNotPresent

# Genesis AKS bundle uses ECR by default; registry/token are injected at deploy time
ecr:
  enabled: true
  registry: ""

# The LLM provider is not configured here. It is configured after the pod is
# running — see "Step 8: Configure the LLM Provider" below.
config:
  # OIDC Authentication (Native - no OAuth2 Proxy)
  authEnabled: "true"
  authProvider: "oidc"

  extraEnv:
    # Azure AD OIDC Configuration
    AUTH_ISSUER: "https://login.microsoftonline.com/<tenant-id>/v2.0"
    AUTH0_CLIENT_ID: "<application-client-id>"
    AUTH_AUDIENCE: "<application-client-id>"
    AUTH_JWKS_URL: "https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys"
    AUTH_ALLOW_QUERY_TOKEN: "true"
    # Optional: override the domain the web client uses for Auth0-style bootstrap.
    # For Entra ID with authProvider "oidc", set this when the issuer-derived
    # domain does not match the path structure the legacy Auth0 SDK expects.
    AUTH0_DOMAIN: "login.microsoftonline.com/<tenant-id>/oauth2/v2.0"

# Recommended for IaC-managed Genesis settings
genesisConfig:
  content: ""  # Set with --set-file genesisConfig.content=genesis-config.yaml
  existingConfigMap: ""  # Or reference a pre-created ConfigMap, not both

# Helm-driven RBAC (optional — see "Helm-driven RBAC" below)
groupRoleMapping:
  content: ""  # --set-file groupRoleMapping.content=group-role-mapping.yaml
rbacSeedPolicy:
  content: ""  # --set-file rbacSeedPolicy.content=rbac-policies.csv

# Optional extra Kubernetes resources rendered as separate YAML documents
extraManifests: []

If you prefer to version Genesis app settings separately from AKS values, move the OIDC, provider, and embedding configuration into genesis-config.yaml and keep Kubernetes settings such as namespace, ingress, and resources in Azure/my-values-oidc.yaml.

auth:
  enabled: true
  provider: "oidc"
  issuer: "https://login.microsoftonline.com/<tenant-id>/v2.0"
  audience: "<application-client-id>"
  jwks_url: "https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys"
  client_id: "<application-client-id>"
  allow_query_token: true

Pass the file with --set-file genesisConfig.content=genesis-config.yaml, or use genesisConfig.existingConfigMap when the file already exists as a ConfigMap. Genesis mounts the file at /app/.genesis/config/genesis-config.yaml, and explicit environment variables still take precedence over file-backed values.

extraManifests defaults to []. Add complete Kubernetes resources here when you want Helm to deploy objects such as PodDisruptionBudget, NetworkPolicy, or PodMonitor alongside Genesis without forking the chart. Each list item is rendered as its own YAML document.

Current Genesis container images also bundle the in-repo genesis_sdk package under /app/genesis_sdk (for execute_python_code local execution — not installable from PyPI) and the llm_wiki package under /app/llm_wiki, so the SDK, wiki APIs, and tools shipped with Genesis are available without extra image customization.

If you use azure-aks/deploy-aks-ga-oidc.sh, set ECR_REGISTRY in azure-aks/aks-config.env and pin image.tag in your values file. The script passes ecr.registry and a fresh ecr.token, forces image.pullPolicy=Always, waits for the StatefulSet rollout to complete, and only passes --set image.tag when GENESIS_IMAGE_TAG is set for a one-off override.

Replace:

<tenant-id> with your Directory (tenant) ID
<application-client-id> with your Application (client) ID

Ingress Configuration

For Testing (nip.io): Initially deploy with a placeholder host, then update with ingress IP:

ingress:
  enabled: true
  className: "nginx"
  hosts:
    - host: genesis-oidc.placeholder.nip.io  # Will update after getting ingress IP
      paths:
        - path: /
          pathType: Prefix
          port: 8080

For Production (permanent DNS): After creating DNS A record, use your permanent domain:

ingress:
  enabled: true
  className: "nginx"
  hosts:
    - host: genesis-oidc.yourcompany.com  # Your permanent domain
      paths:
        - path: /
          pathType: Prefix
          port: 8080
  tls:
    - secretName: genesis-oidc-tls
      hosts:
        - genesis-oidc.yourcompany.com

Step 4: Deploy Genesis

# Create namespace and deploy
helm upgrade --install genesis-oidc . \
    -f Azure/my-values-oidc.yaml \
    -n genesis-oidc \
    --create-namespace

# Wait for pod to be ready
kubectl wait --for=condition=ready pod \
    -l app.kubernetes.io/instance=genesis-oidc \
    -n genesis-oidc \
    --timeout=300s

Step 5: Get Ingress IP and Update Configuration

# Get ingress IP (may take 2-5 minutes)
kubectl get ingress -n genesis-oidc -w

# Once IP is assigned, note it
INGRESS_IP=$(kubectl get ingress -n genesis-oidc genesis-oidc \
    -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
echo "Ingress IP: $INGRESS_IP"

Update Helm Values

For Testing (nip.io): Edit Azure/values-aks-oidc.yaml and update the ingress host:

ingress:
  hosts:
    - host: genesis-oidc.<INGRESS_IP>.nip.io  # Testing only
      paths:
        - path: /
          pathType: Prefix
          port: 8080

For Production (permanent DNS):

Create DNS A record: genesis-oidc.yourcompany.com → <INGRESS_IP>
Edit Azure/values-aks-oidc.yaml:

ingress:
  hosts:
    - host: genesis-oidc.yourcompany.com  # Your permanent domain
      paths:
        - path: /
          pathType: Prefix
          port: 8080
  tls:
    - secretName: genesis-oidc-tls
      hosts:
        - genesis-oidc.yourcompany.com

Update Azure AD Redirect URIs

Keep the Genesis web UI redirect and Claude Code hosted-MCP redirect together on the same app registration:

The Genesis web UI redirect is the public Genesis origin.
The Claude Code MCP redirect is http://localhost:31318/callback.

When enabling Hosted MCP for Claude Code, also configure a customer-facing public base URL (GENESIS_MCP_PUBLIC_URL or correct ingress forwarding headers). For Anthropic Console Connect, set GENESIS_OAUTH_PROXY_ENABLED=true on the Genesis workload so Genesis can advertise and proxy OAuth on the same public hostname. For Testing (nip.io):

# Variables
CLIENT_ID="<your-application-client-id>"
INGRESS_IP="<your-ingress-ip>"

# Update Azure AD app registration
az rest --method PATCH \
    --uri "https://graph.microsoft.com/v1.0/applications/$(az ad app show --id $CLIENT_ID --query id -o tsv)" \
    --headers "Content-Type=application/json" \
    --body '{"spa":{"redirectUris":["http://genesis-oidc.'${INGRESS_IP}'.nip.io","https://genesis-oidc.'${INGRESS_IP}'.nip.io"]},"publicClient":{"redirectUris":["http://localhost:31318/callback"]}}'

For Production (permanent domain):

# First create DNS A record: genesis-oidc.yourcompany.com → <INGRESS_IP>
CLIENT_ID="<your-application-client-id>"

# Update Azure AD app registration
az rest --method PATCH \
    --uri "https://graph.microsoft.com/v1.0/applications/$(az ad app show --id $CLIENT_ID --query id -o tsv)" \
    --headers "Content-Type=application/json" \
    --body '{"spa":{"redirectUris":["https://genesis-oidc.yourcompany.com"]},"publicClient":{"redirectUris":["http://localhost:31318/callback"]}}'

Redeploy with Updated Values

helm upgrade genesis-oidc . \
    -f Azure/values-aks-oidc.yaml \
    -n genesis-oidc

Step 6: Verify Deployment

# Check pod status
kubectl get pods -n genesis-oidc

# Check ingress
kubectl get ingress -n genesis-oidc

# Check logs
kubectl logs -n genesis-oidc genesis-oidc-0 --tail=50

# Test health endpoint
# Testing: curl http://genesis-oidc.<INGRESS_IP>.nip.io/api/health
# Production: curl https://genesis-oidc.yourcompany.com/api/health

Step 7: Test Authentication

Testing (nip.io):

Navigate to http://genesis-oidc.<INGRESS_IP>.nip.io/ or https://genesis-oidc.<INGRESS_IP>.nip.io/
Click Login — you’ll be redirected to Microsoft login
Authenticate with your Azure AD credentials
After successful authentication, you’ll be redirected back to Genesis

Production (permanent domain):

Navigate to https://genesis-oidc.yourcompany.com/
Click Login — you’ll be redirected to Microsoft login
Authenticate with your Azure AD credentials
After successful authentication, you’ll be redirected back to Genesis

Step 8: Configure the LLM Provider

Genesis starts without a provider and reports No suitable LLM found until one is configured. Configure it against the running pod, either from Config → AI Providers in the UI or through the config API. Keep credentials in a request-body file — process arguments are visible to every process on the host and land in shell history.

umask 077
set -o pipefail
GENESIS_URL=https://genesis-oidc.yourcompany.com
BODY=$(mktemp "${TMPDIR:-/tmp}/genesis-llm-body.XXXXXX.json")
CURL_CONFIG=$(mktemp "${TMPDIR:-/tmp}/genesis-curl.XXXXXX")
trap 'rm -f "$BODY" "$CURL_CONFIG"' EXIT
chmod 600 "$BODY" "$CURL_CONFIG"

# This deployment runs with authEnabled "true", so every call below needs a bearer
# token for a user holding access_config_panel. Without it each request returns 401.
read -rsp 'Genesis access token: ' GENESIS_TOKEN && echo
printf 'header = "Authorization: Bearer %s"\n' "$GENESIS_TOKEN" > "$CURL_CONFIG"
unset GENESIS_TOKEN

# --fail-with-body catches an HTTP error, but these routes also answer 200 with
# {"success": false}. check() turns that into a nonzero exit so the && chain stops
# instead of activating a provider whose credential never saved.
check() {
  python3 -c 'import json, sys
body = json.load(sys.stdin)
print(json.dumps(body, indent=2), flush=True)
if not body.get("success"):
    sys.exit("STOP: %s" % (body.get("message") or "call reported success: false"))'
}

cat > "$BODY" <<'JSON'
{"endpoint_name": "genesis-azureopenai-1",
 "api_key": "<azure-openai-api-key>",
 "full_endpoint_url": "https://<your-resource>.openai.azure.com/",
 "api_version": "2025-04-01-preview",
 "model_deployment_name": "<chat-deployment-name>",
 "embedding_deployment_name": "<embedding-deployment-name>",
 "test_connection": true}
JSON
curl -sS --fail-with-body --config "$CURL_CONFIG" \
  -X POST -H 'Content-Type: application/json' --data @"$BODY" \
  "$GENESIS_URL/api/config/llm-providers/azure" | check &&
# Note the two naming spaces: the card is "azure", the llm type is "azureopenai".
curl -sS --fail-with-body --config "$CURL_CONFIG" \
  -X POST -H 'Content-Type: application/json' -d '{"force": true}' \
  "$GENESIS_URL/api/config/llm-providers/azureopenai/activate" | check &&
curl -sS --fail-with-body --config "$CURL_CONFIG" \
  -X PUT -H 'Content-Type: application/json' \
  -d '{"provider": "azureopenai", "use_defaults": true, "activate_provider": true}' \
  "$GENESIS_URL/api/config/models/main/assignments" | check

The key is stored by Genesis through this call, not supplied as a Helm value. If check stops the chain on “Configuration for … already exists”, the activation and model-assignment calls never ran — the provider is stored but not usable. Change the first call from POST to PUT and rerun the whole block, so activation and assignment execute after the update. For the full endpoint reference and the other providers, see Configuring a provider through the config API.

The chart still accepts secrets.openaiApiKey, config.modelName and config.azureOpenaiEndpoint; this guide’s values example no longer shows them. Each reaches the pod as an environment variable carrying a default_env_var binding — secrets.openaiApiKey as OPENAI_API_KEY, on the OpenAI provider’s key field. Such a binding seeds its field while nothing is stored there, and stored APP_CONFIG values take precedence from then on, so a value saved through the UI or the config API wins on every later read. They are deprecated as an LLM setup path: none of them writes llm.active_provider, and on an Azure OpenAI deployment secrets.openaiApiKey seeds the wrong provider — the azureopenai key field binds to AZURE_OPENAI_API_KEY. Configure the provider with the calls above, or declare it in a genesis-config.yaml mounted with --set-file genesisConfig.content=....

A mounted genesis-config.yaml is a third configuration surface. An unchanged file fills only the paths that are missing, so later UI edits survive a restart; when the profile path or the file’s hash changes, Genesis clears and rewrites every top-level section the file contains. Treat the file as the canonical source wherever it is used.

Helm-driven RBAC

For production OIDC deployments (for example Azure Entra ID on AKS), you can declare RBAC outside the Genesis UI using Helm values. Genesis applies both features on startup and on every login.

Group-to-role mapping (`groupRoleMapping`)

Maps external identity-provider group identifiers (for example Entra security group GUIDs from the JWT groups claim) to Genesis role names. On each login, Genesis syncs the user’s roles from group membership. Provide a YAML file via --set-file:

helm upgrade --install genesis-oidc . \
  -f Azure/my-values-oidc.yaml \
  --set-file groupRoleMapping.content=group-role-mapping.yaml \
  -n genesis-oidc

Example group-role-mapping.yaml:

"2d8b2b8d-a652-4eed-9939-a08238e58af9": "admin"
"5dba4ec0-2ddd-4203-abc9-6fb730cbe0f5": "user"

Sync behavior:

Roles are added when the user gains membership in a mapped group.
Roles are removed when the user loses membership — but only for roles that appear as values in the mapping. Manually assigned roles outside the mapping are never removed.
The sync runs on every login, not only first login.

Entra prerequisite: Under Token configuration, add a groups claim with Security groups and emit group identifiers as GUIDs. Genesis mounts the file at /app/.genesis/config/group-role-mapping.yaml and sets GENESIS_GROUP_ROLE_MAPPING_FILE. Without Helm, you can instead set GENESIS_GROUP_ROLE_MAPPING to a JSON object with the same key/value shape.

RBAC seed policies (`rbacSeedPolicy`)

Pre-populate custom roles, permissions, and role hierarchy at startup using standard Casbin CSV format. Provide via --set-file:

helm upgrade --install genesis-oidc . \
  -f Azure/my-values-oidc.yaml \
  --set-file rbacSeedPolicy.content=rbac-policies.csv \
  -n genesis-oidc

Example rbac-policies.csv:

# Role hierarchy — custom_role inherits built-in user permissions
g, custom_role, user
# Permissions
p, custom_role, apps, view
p, custom_role, agent:Adam, access

Genesis mounts the file at /app/.genesis/config/rbac-policies.csv and sets GENESIS_RBAC_SEED_FILE. Policies are idempotent — existing rules are not duplicated. Lines starting with # and blank lines are skipped. You can also set default roles for brand-new users (before the admin UI override) in genesis-config.yaml:

rbac:
  default_roles:
    - user

See RBAC in Genesis: A Practical Guide and Advanced Settings → RBAC defaults.

Configuration Reference

Environment Variables

Variable	Required	Description
`AUTH_ENABLED`	Yes	Set to `true` to enable authentication
`AUTH_PROVIDER`	Yes	Set to `oidc` for native OIDC
`AUTH_ISSUER`	Yes	OIDC issuer URL (e.g., `https://login.microsoftonline.com/{tenant}/v2.0`)
`AUTH0_CLIENT_ID`	Yes	Application (Client) ID
`AUTH0_DOMAIN`	No	Override for `auth0_domain` returned by `GET /api/config/frontend`. When set, takes precedence over the domain derived from `AUTH_ISSUER`. Use for Entra when the issuer host alone is not the correct OAuth path prefix (for example `login.microsoftonline.com/{tenant}/oauth2/v2.0`).
`AUTH_AUDIENCE`	No	JWT audience claim (typically same as Client ID)
`AUTH_JWKS_URL`	No	JWKS URL (auto-discovered if not set)
`AUTH_ALLOW_QUERY_TOKEN`	No	Allow token in query params for WebSocket (default: `false`)
`GENESIS_GROUP_ROLE_MAPPING_FILE`	No	Path to a YAML group-to-role map (set automatically when `groupRoleMapping.content` is provided)
`GENESIS_RBAC_SEED_FILE`	No	Path to a Casbin CSV seed file (set automatically when `rbacSeedPolicy.content` is provided)

Azure AD URLs

For tenant ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:

Issuer URL: https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/v2.0
JWKS URL: https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/discovery/v2.0/keys

Reference: Example values file

The following is a production-ready example values-aks-oidc.yaml for Genesis on Azure AKS with native OIDC. Replace placeholders (e.g. <tenant-id>, <application-client-id>, <your-resource-name>, genesis-oidc.yourcompany.com) with your own values.

# Genesis Helm Chart - Azure AKS Values with Native OIDC Authentication
# Production-ready configuration for Azure Kubernetes Service
#
# This configuration uses Native OIDC authentication (no OAuth2 Proxy needed).
# Genesis handles authentication directly using Authorization Code Flow + PKCE.
#
# Compatible with: Azure AD (Entra ID), Okta, Keycloak, and any OIDC provider.
#
# Required configuration:
#   1. Configure OIDC settings in config.extraEnv (see below)
#
# The LLM provider is NOT configured in this file. It is configured after the pod
# is running, from Config -> AI Providers or through the config API — see
# "Step 8: Configure the LLM Provider".
#
# OIDC Environment Variables (set in config.extraEnv):
#   AUTH_ISSUER: "https://login.microsoftonline.com/<tenant-id>/v2.0"
#   AUTH0_CLIENT_ID: "<application-client-id>"  # Used for backward compatibility
#   AUTH_AUDIENCE: "<application-client-id>"
#   AUTH_JWKS_URL: "https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys"  # Optional
#   AUTH_ALLOW_QUERY_TOKEN: "true"  # For WebSocket support

# Namespace configuration
namespace: genesis-oidc

# Container image configuration
image:
  repository: ghcr.io/genesis-computing-ai/genesis
  tag: v1.18.2
  pullPolicy: IfNotPresent

# Genesis AKS bundle uses ECR by default; registry/token are injected by the helper script
ecr:
  enabled: true
  registry: ""

# Leave empty when the helper script injects the ECR pull secret
imagePullSecrets: []

# Secrets configuration (sensitive values only)
# IMPORTANT: Use Azure Key Vault or --set flags for production
secrets:
  # Master encryption key for Genesis secrets management (REQUIRED on first
  # install unless existingSecretGenesisMasterKey or
  # config.extraEnv.GENESIS_MASTER_KEY_REF is set)
  # Generate with: python -c "import secrets; print(secrets.token_hex(32))"
  genesisMasterKey: ""
  # Or reference an existing Kubernetes Secret
  existingSecretGenesisMasterKey:
    secretName: ""
    secretKey: "GENESIS_MASTER_KEY"
  # Or resolve from GCP Secret Manager at startup (Workload Identity):
  # config.extraEnv.GENESIS_MASTER_KEY_REF: "gcp_prod/genesis-keys#master_key"
  
  # No LLM provider secret appears here. The chart still accepts
  # secrets.openaiApiKey / secrets.databricksApiKey, but they are deprecated
  # bootstrap seeds — see the note under "Step 8: Configure the LLM Provider".
  
  # Databricks Database Connection PAT (SQL warehouse, not the LLM provider)
  databricksDbPat: ""
  existingSecretDatabricksDbPat:
    secretName: ""
    secretKey: "DATABRICKS_DB_PAT"

# Non-sensitive configuration
config:
  # Database path (inside the persistent volume)
  sqliteDbPath: "/app/.genesis/db/genesis.db"
  
  # Log level: DEBUG, INFO, WARNING, ERROR
  logLevel: "INFO"
  
  # Log format: json, text
  logsFormat: "json"  # Use json for Azure Log Analytics integration
  
  # --------------------------------------------------------------------------
  # Authentication Configuration (Native OIDC)
  # --------------------------------------------------------------------------
  # Genesis handles authentication directly - no OAuth2 Proxy required
  authEnabled: "true"
  authProvider: "oidc"  # Native OIDC support (Authorization Code + PKCE)
  
  # --------------------------------------------------------------------------
  # LLM model configuration is not set here
  # --------------------------------------------------------------------------
  # The chart still accepts config.modelName / fastModelName / harvesterModel /
  # embeddingModel / maxTokens / azureOpenaiEndpoint as deprecated bootstrap
  # seeds. Model assignments and the endpoint are saved with the provider in
  # Step 8, so they are not shown in this example.
  
  # --------------------------------------------------------------------------
  # Databricks-specific configuration
  # --------------------------------------------------------------------------
  databricksBaseUrl: ""
  databricksHost: ""
  databricksDb:
    enabled: false
    connectionId: "databricks"
    serverHostname: ""
    httpPath: ""
    description: "Databricks SQL Warehouse"
    # Authentication type: "pat" (default) or "user_oauth" (per-user OAuth)
    authType: "pat"
  
  # --------------------------------------------------------------------------
  # OIDC Authentication Environment Variables
  # --------------------------------------------------------------------------
  # These variables configure the native OIDC authentication
  # Replace placeholders with your Azure AD (or other IdP) values
  extraEnv:
    # OIDC Issuer URL (Azure AD v2.0 endpoint)
    AUTH_ISSUER: "https://login.microsoftonline.com/<tenant-id>/v2.0"
    
    # Application (Client) ID from Azure AD App Registration
    AUTH0_CLIENT_ID: "<application-client-id>"
    
    # JWT Audience - typically the same as Client ID
    AUTH_AUDIENCE: "<application-client-id>"
    
    # JWKS URL for JWT verification
    AUTH_JWKS_URL: "https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys"
    
    # Allow token in query parameter (required for WebSocket support)
    AUTH_ALLOW_QUERY_TOKEN: "true"
    
    # Optional: see Configuration Reference — AUTH0_DOMAIN
    AUTH0_DOMAIN: "login.microsoftonline.com/<tenant-id>/oauth2/v2.0"

# Helm-driven RBAC (optional)
groupRoleMapping:
  content: ""
rbacSeedPolicy:
  content: ""

# Resource requests (production sizing)
resources:
  requests:
    cpu: "2000m"
    memory: "6Gi"
  limits:
    cpu: "4000m"
    memory: "8Gi"

# Persistent storage configuration
# AKS uses Azure Disk (default storage class)
persistence:
  storageClassName: "managed-csi"  # Azure Disk CSI driver (default in AKS)
  size: 50Gi
  accessMode: ReadWriteOnce

# Service configuration
service:
  type: ClusterIP
  ports:
    fastapi: 8080
    flask: 8082
    streamlit: 8501

# --------------------------------------------------------------------------
# Ingress Configuration
# --------------------------------------------------------------------------
# With native OIDC, Genesis handles auth directly - ingress goes to Genesis
# (No OAuth2 Proxy needed)
ingress:
  enabled: true
  className: "nginx"
  annotations:
    # WebSocket support
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-body-size: "100m"
  
  # Host configuration
  hosts:
    # Option 1: For testing/development - Use nip.io with ingress IP
    # Step 1: Deploy with placeholder
    # Step 2: Get ingress IP: kubectl get ingress -n genesis-oidc
    # Step 3: Update host to: genesis-oidc.<INGRESS_IP>.nip.io
    # Step 4: helm upgrade genesis-oidc . -f values-aks-oidc.yaml -n genesis-oidc
    - host: genesis-oidc.yourcompany.com  # Your permanent domain
      paths:
        - path: /
          pathType: Prefix
          port: 8080
    
    # Option 2: For production - Use your real domain
    # - host: genesis.yourcompany.com
    #   paths:
    #     - path: /
    #       pathType: Prefix
    #       port: 8080
  
  # TLS configuration
  tls: []
  # Example with cert-manager:
  # tls:
  #   - secretName: genesis-oidc-tls
  #     hosts:
  #       - genesis.yourdomain.com

# Health probes
startupProbe:
  httpGet:
    path: /api/health
    port: 8080
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 60

livenessProbe:
  httpGet:
    path: /api/health/live
    port: 8080
  periodSeconds: 30
  timeoutSeconds: 5
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /api/health
    port: 8080
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

# Pod annotations
podAnnotations: {}

# Node selector (optional)
nodeSelector: {}

# Tolerations (optional)
tolerations: []

# Affinity rules (optional)
affinity: {}

# Extra volumes (e.g., Azure Key Vault CSI driver)
extraVolumes: []

# Extra volume mounts
extraVolumeMounts: []

When config.databricksDb.authType is user_oauth, Genesis bootstraps a per-user OAuth Databricks connection at startup using DATABRICKS_DB_SERVER_HOSTNAME and DATABRICKS_DB_HTTP_PATH only — no DATABRICKS_DB_PAT secret is required. Each user authorizes their own grant at runtime. When authType is pat (default), provide secrets.databricksDbPat or existingSecretDatabricksDbPat.

Troubleshooting

”AADSTS500113: No reply address is registered”

Cause: No Redirect URI configured in Azure AD. Fix:

Azure Portal → App registrations → Your app → Authentication
Add platform: Single-page application
Add redirect URI: http://genesis-oidc.<IP>.nip.io (no trailing slash, no path)

“AADSTS50011: Reply URL does not match”

Cause: Redirect URI mismatch. Fix:

For Genesis web login, register exactly: http://genesis-oidc.<IP>.nip.io or https://genesis-oidc.yourcompany.com (no trailing /)
For Claude Code hosted MCP login, register exactly: http://localhost:31318/callback as a Mobile and desktop applications redirect URI
Check browser DevTools → Network → look at redirect_uri in the /authorize request

Cause: Azure AD doesn’t include email in tokens by default. Fix:

Azure Portal → App registrations → Your app → Token configuration
Click “Add optional claim”
Select ID token type
Check: email, upn, preferred_username
Save and re-login

Cause: Missing offline_access scope. Fix:

The frontend automatically requests openid profile email offline_access
Verify Azure AD allows refresh tokens for SPAs (enabled by default)

CORS Errors

Cause: Usually a misconfiguration in Azure AD. Fix:

Azure AD enables CORS by default for SPA apps
Verify the platform type is “Single-page application”

WebSocket Connection Fails

Cause: Token not sent or invalid. Fix:

Set AUTH_ALLOW_QUERY_TOKEN: "true" in config
Check that token hasn’t expired
Check browser DevTools → Network → WS → Headers

Pod Not Starting

# Check pod status
kubectl describe pod -n genesis-oidc genesis-oidc-0

# Check events
kubectl get events -n genesis-oidc --sort-by='.lastTimestamp'

# Check logs
kubectl logs -n genesis-oidc genesis-oidc-0 --previous

Comparison: OIDC vs OAuth2 Proxy

Aspect	Native OIDC	OAuth2 Proxy
Components	Genesis only	Genesis + OAuth2 Proxy
Configuration	Helm values only	Helm values + oauth2-proxy-values.yaml
Cookie handling	Standard JWT	Large session cookies (needs buffer tuning)
502 errors	Unlikely	Common (buffer size issues)
Maintenance	Lower	Higher (two components)
Token refresh	Browser-native	Proxy-managed

If you choose OAuth2 Proxy instead of native OIDC, use the Helm bundle’s azure-aks/oauth2-proxy-values.yaml example (see also azure-aks/AZURE_AD_AKS_SETUP.md). Required oauth2-proxy settings for dashboard and Kubernetes health probes:

cookie_secure = true
cookie_samesite = "lax"
skip_auth_routes = ["GET=^/api/health$", "GET=^/api/health/startup$", "GET=^/api/health/live$", "GET=^/api/healthcheck$"]
cookie_csrf_per_request = true
cookie_csrf_expire = "5m"
scope = "openid email profile offline_access"
# cookie_refresh = "55m"

cookie_secure = true applies when HTTPS terminates at the ingress or external load balancer. In this guide’s reverse-proxy mode (upstreams = [...]), skip_auth_routes exempts only the GET probe endpoints above; other /api/health/* routes stay behind authentication. Under the nginx auth_request / nginx.ingress.kubernetes.io/auth-url pattern, oauth2-proxy sees only /oauth2/auth, so skip_auth_routes does not match application paths. Use a second Ingress on the same host without the auth annotations to exempt the health endpoints there. Keep offline_access in scope when using cookie_refresh: Entra ID returns a refresh token only for requests that include this scope. Without it, oauth2-proxy cannot renew the session when the Entra access token expires (about 1 hour by default), and the user is sent through sign-in again. cookie_refresh is not enabled in this example; if you enable it, set it below the access-token lifetime, such as 55m. Adding offline_access to an existing app registration may prompt users for consent on their next sign-in, depending on tenant consent policy and existing grants. Grant admin consent once from Azure AD → App registrations → your app → API permissions → Grant admin consent to avoid that prompt. Keep cookie_csrf_per_request = true to give concurrent sign-in flows separate CSRF cookies and prevent invalid-CSRF 403 errors. The trade-off is that abandoned flows leave cookies behind, so keep cookie_csrf_expire = "5m"; on oauth2-proxy 7.11 and later, set cookie_csrf_per_request_limit if needed to cap accumulation and avoid request headers growing until nginx returns 431 or 502.

Cleanup

To remove the deployment:

# Delete Genesis
helm uninstall genesis-oidc -n genesis-oidc

# Delete namespace (optional)
kubectl delete namespace genesis-oidc

PVCs are retained by default. To delete: kubectl delete pvc -n genesis-oidc --allFor backup and snapshot strategies (CSI snapshots, Azure Backup for AKS, Velero, logical exports), see Backup and Snapshot Options.

Production DNS Setup

Important: For production deployments, you must configure permanent DNS names:

Get your ingress IP:

kubectl get ingress -n genesis-oidc genesis-oidc \
    -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

Create DNS A record:
- In your DNS provider (Azure DNS, Route 53, etc.)
- Create A record: genesis-oidc.yourcompany.com → <INGRESS_IP>
Update Helm values:
- Edit Azure/values-aks-oidc.yaml to use your permanent domain
- Update ingress hosts to use your domain
- Add TLS configuration
Update Azure AD redirect URIs:
- Remove nip.io redirect URIs
- Add your permanent domain redirect URI: https://genesis-oidc.yourcompany.com

Redeploy:

helm upgrade genesis-oidc . -f Azure/values-aks-oidc.yaml -n genesis-oidc

Next Steps

See your Genesis deployment bundle for Azure Key Vault setup (storing secrets securely), TLS configuration (HTTPS), and production checklist (hardening).
For general AKS deployment without OIDC, see Deploying Genesis - Kubernetes on Azure.

​Overview

​Architecture

​Prerequisites

​Hostname Configuration

​Step 1: Scale AKS Node Pool (if needed)

​Step 2: Create Azure AD App Registration

​Using Azure Portal (Recommended)

​Configure Authentication Platform

​Configure Token Claims (Important)

​Checklist

​Step 3: Configure values-aks-oidc.yaml

​Required Configuration

​Ingress Configuration

​Step 4: Deploy Genesis

​Step 5: Get Ingress IP and Update Configuration

​Update Helm Values

​Update Azure AD Redirect URIs

​Redeploy with Updated Values

​Step 6: Verify Deployment

​Step 7: Test Authentication

​Step 8: Configure the LLM Provider

​Helm-driven RBAC

​Group-to-role mapping (groupRoleMapping)

​RBAC seed policies (rbacSeedPolicy)

​Configuration Reference

​Environment Variables

​Azure AD URLs

​Reference: Example values file

​Troubleshooting

​”AADSTS500113: No reply address is registered”

​“AADSTS50011: Reply URL does not match”

​Login works but no email in Genesis

​Token Refresh Failure / Infinite Login Loop

​CORS Errors

​WebSocket Connection Fails

​Pod Not Starting

​Comparison: OIDC vs OAuth2 Proxy

​Cleanup

​Production DNS Setup

​Next Steps

Overview

Architecture

Prerequisites

Hostname Configuration

Step 1: Scale AKS Node Pool (if needed)

Step 2: Create Azure AD App Registration

Using Azure Portal (Recommended)

Configure Authentication Platform

Configure Token Claims (Important)

Checklist

Step 3: Configure values-aks-oidc.yaml

Required Configuration

Ingress Configuration

Step 4: Deploy Genesis

Step 5: Get Ingress IP and Update Configuration

Update Helm Values

Update Azure AD Redirect URIs

Redeploy with Updated Values

Step 6: Verify Deployment

Step 7: Test Authentication

Step 8: Configure the LLM Provider

Helm-driven RBAC

Group-to-role mapping (`groupRoleMapping`)

RBAC seed policies (`rbacSeedPolicy`)

Configuration Reference

Environment Variables

Azure AD URLs

Reference: Example values file

Troubleshooting

”AADSTS500113: No reply address is registered”

“AADSTS50011: Reply URL does not match”

Login works but no email in Genesis

Token Refresh Failure / Infinite Login Loop

CORS Errors

WebSocket Connection Fails

Pod Not Starting

Comparison: OIDC vs OAuth2 Proxy

Cleanup

Production DNS Setup

Next Steps