OAuth 2.0 / OIDC Authentication with Google and Datum

This guide describes how to configure OAuth 2.0 / OIDC Authentication for applications running behind a Datum gateway using datumctl. The configuration uses Envoy Gateway SecurityPolicy resources and applies to Windows, macOS, and Linux.

Overview

OIDC authentication protects an application by requiring users to sign in with their Google account before requests are forwarded to the origin. Envoy Gateway handles the OAuth 2.0 flow transparently — users are redirected to Google, authenticate, and are redirected back without any changes to your application. At a high level, this setup:

Creates a Google OAuth 2.0 Client in Google Cloud Console
Stores the client secret in a Kubernetes Secret
Labels the Secret so it is synced to edge clusters
Attaches a SecurityPolicy with OIDC config to an HTTPRoute
Verifies authentication behavior

Prerequisites

datumctl installed and authenticated
A valid Project
A Google Cloud account with a project
Existing:
- Gateway
- HTTPRoute
Permission to create:
- Secret
- SecurityPolicy

Verify access:

datumctl get gateway
datumctl get httproute

Critical requirement: secret syncing

Secrets and ConfigMaps referenced by gateway configurations are not automatically synced to edge clusters. To make a Secret available to edge gateways, it must include the following label:

networking.datumapis.com/gateway-sync: "true"

Why this matters

Without this label, the gateway receives the policy but not the Secret
Envoy fails to load the OAuth client credentials
All requests return HTTP 500 instead of redirecting to Google

This requirement exists to prevent accidental replication of unrelated secrets.

Configuration steps

Step 1: Create Google OAuth 2.0 credentials

Go to Google Cloud Console → APIs & Services → Credentials
Select Create Credentials → OAuth 2.0 Client ID
Set Application type to Web application
Under Authorized redirect URIs, add:
https://<your-app-hostname>/oauth2/callback
Replace <your-app-hostname> with the public hostname of your HTTPRoute.
Select Create and copy the Client ID and Client Secret

Note: The redirect URI must exactly match the value you will configure in the SecurityPolicy. Any mismatch causes Google to reject the OAuth flow.

Step 2: Set variables

Windows (PowerShell)

$project      = "your-project-id"
$namespace    = "default"
$route        = "your-route-name"
$hostname     = "your-app.example.com"
$clientID     = "your-client-id.apps.googleusercontent.com"
$clientSecret = "your-client-secret"

macOS / Linux

project="your-project-id"
namespace="default"
route="your-route-name"
hostname="your-app.example.com"
clientID="your-client-id.apps.googleusercontent.com"
clientSecret="your-client-secret"

Step 3: Create the client secret

The Secret must:

Use the key client-secret
Exist in the same namespace as the SecurityPolicy
Include the gateway-sync label

Windows (PowerShell)

$b64Secret = [Convert]::ToBase64String(
  [Text.Encoding]::UTF8.GetBytes($clientSecret)
)

@"
apiVersion: v1
kind: Secret
metadata:
  name: ${route}-oidc-secret
  labels:
    networking.datumapis.com/gateway-sync: "true"
type: Opaque
data:
  client-secret: $b64Secret
"@ | datumctl apply --project $project --namespace $namespace -f -

macOS / Linux

b64Secret=$(printf "%s" "$clientSecret" | base64)

cat <<EOF | datumctl apply --project $project --namespace $namespace -f -
apiVersion: v1
kind: Secret
metadata:
  name: ${route}-oidc-secret
  labels:
    networking.datumapis.com/gateway-sync: "true"
type: Opaque
data:
  client-secret: $b64Secret
EOF

Step 4: Attach OIDC authentication using a SecurityPolicy

Attach the policy to the HTTPRoute. This is the most reliable attachment point.

Windows (PowerShell)

@"
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: ${route}-oidc
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: $route
  oidc:
    provider:
      issuer: "https://accounts.google.com"
    clientID: "$clientID"
    clientSecret:
      name: ${route}-oidc-secret
    redirectURL: "https://${hostname}/oauth2/callback"
    scopes:
      - openid
      - email
      - profile
"@ | datumctl apply --project $project --namespace $namespace -f -

macOS / Linux

cat <<EOF | datumctl apply --project $project --namespace $namespace -f -
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: ${route}-oidc
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: $route
  oidc:
    provider:
      issuer: "https://accounts.google.com"
    clientID: "$clientID"
    clientSecret:
      name: ${route}-oidc-secret
    redirectURL: "https://${hostname}/oauth2/callback"
    scopes:
      - openid
      - email
      - profile
EOF

Verification

Unauthenticated request

curl -I https://your-app.example.com

Expected response:

HTTP/1.1 302 Found
Location: https://accounts.google.com/o/oauth2/v2/auth?...

Browsers will redirect automatically to the Google sign-in page.

Authenticated session

After completing the Google sign-in flow, subsequent requests will be forwarded to your origin with a session cookie managed by Envoy.

curl -I https://your-app.example.com

Expected response after authentication:

HTTP/1.1 200 OK

Cleanup / disable OIDC authentication

Windows (PowerShell)

datumctl delete securitypolicy ${route}-oidc `
  --project $project --namespace $namespace --ignore-not-found

datumctl delete secret ${route}-oidc-secret `
  --project $project --namespace $namespace --ignore-not-found

macOS / Linux

datumctl delete securitypolicy ${route}-oidc \
  --project $project --namespace $namespace --ignore-not-found

datumctl delete secret ${route}-oidc-secret \
  --project $project --namespace $namespace --ignore-not-found

Troubleshooting

Common failure modes

Symptom	Root cause	Resolution
HTTP 500 on all requests	Secret not synced to edge	Add `gateway-sync` label
Redirect loop	Redirect URI mismatch	Ensure `redirectURL` matches Google Console exactly
`redirect_uri_mismatch` from Google	URI not registered	Add URI to Google Cloud Credentials
HTTP 401 after login	Scopes insufficient	Verify `openid` scope is included
Works after deleting policy	Invalid Secret reference	Fix Secret name and `gateway-sync` label

Useful debug commands

datumctl get secret --project $project --namespace $namespace
datumctl get securitypolicy --project $project --namespace $namespace
datumctl get httproute --project $project --namespace $namespace

Best practices

Register separate OAuth clients for each environment (dev, staging, prod)
Restrict authorized redirect URIs to known hostnames only
Limit OAuth scopes to the minimum required (openid, email)
Rotate the client secret periodically and re-apply the Secret
Use OIDC for production — Basic Auth is suited for development and demos

Summary

Google OAuth is configured using Envoy Gateway SecurityPolicy with an oidc block
The client secret is stored as a Kubernetes Secret with key client-secret
Secrets must be explicitly synced to edge clusters using the networking.datumapis.com/gateway-sync: "true" label
The redirectURL in the policy must exactly match the URI registered in Google Cloud Console
Attaching policies to HTTPRoute is the most reliable approach

Documentation

TLDR

Platform

AI Edge

Connectors

Galactic VPC

Domains & DNS

Agents

Tools

OAuth 2.0 / OIDC Authentication with Google and Datum

Overview

Prerequisites

Critical requirement: secret syncing

Why this matters

Configuration steps

Step 1: Create Google OAuth 2.0 credentials

Step 2: Set variables

Windows (PowerShell)

macOS / Linux

Step 3: Create the client secret

Windows (PowerShell)

macOS / Linux

Step 4: Attach OIDC authentication using a SecurityPolicy

Windows (PowerShell)

macOS / Linux

Verification

Unauthenticated request

Authenticated session

Cleanup / disable OIDC authentication

Windows (PowerShell)

macOS / Linux

Troubleshooting

Common failure modes

Useful debug commands

Best practices

Summary

​Overview

​Prerequisites

​Critical requirement: secret syncing

​Why this matters

​Configuration steps

​Step 1: Create Google OAuth 2.0 credentials

​Step 2: Set variables

​Windows (PowerShell)

​macOS / Linux

​Step 3: Create the client secret

​Windows (PowerShell)

​macOS / Linux

​Step 4: Attach OIDC authentication using a SecurityPolicy

​Windows (PowerShell)

​macOS / Linux

​Verification

​Unauthenticated request

​Authenticated session

​Cleanup / disable OIDC authentication

​Windows (PowerShell)

​macOS / Linux

​Troubleshooting

​Common failure modes

​Useful debug commands

​Best practices

​Summary

Overview

Prerequisites

Critical requirement: secret syncing

Why this matters

Configuration steps

Step 1: Create Google OAuth 2.0 credentials

Step 2: Set variables

Windows (PowerShell)

macOS / Linux

Step 3: Create the client secret

Windows (PowerShell)

macOS / Linux

Step 4: Attach OIDC authentication using a SecurityPolicy

Windows (PowerShell)

macOS / Linux

Verification

Unauthenticated request

Authenticated session

Cleanup / disable OIDC authentication

Windows (PowerShell)

macOS / Linux

Troubleshooting

Common failure modes

Useful debug commands

Best practices

Summary