> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Agent home for Datum, with what it is, pricing, and how to act: https://agents.datum.net
> If you can only fetch URLs: read https://www.datum.net/docs/llms.txt in full and open the most specific page for the task. Commands, limits, and field paths are on task, operations, and limits pages, not on section overviews. Pages described as "Documentation is coming soon" are placeholders.
> If you have a shell or can save files: download https://www.datum.net/docs/llms-full.txt (every page, about 740 KB) once and search it with grep, instead of fetching pages one at a time.
> datumctl describes itself: `datumctl api-resources` lists resource types and `datumctl explain <resource>` shows a schema. To act on live resources, use Datum MCP or datumctl. To search the docs, use the Docs MCP server at https://www.datum.net/docs/mcp.

# Sign in with Google (OIDC)

> Configure OIDC authentication using Google OAuth 2.0 for applications behind a Datum gateway using datumctl and Envoy Gateway SecurityPolicy.

This page shows how to require people to sign in with their Google account before requests reach your app, using an [Envoy Gateway](https://gateway.envoyproxy.io/) `SecurityPolicy` and `datumctl`.

***

## 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:

1. Creates a **Google OAuth 2.0 Client** in Google Cloud Console
2. Stores the client secret in a **Kubernetes Secret**
3. Labels the Secret so it is synced to edge clusters
4. Attaches a **SecurityPolicy** with OIDC config to an `HTTPRoute`
5. 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:

```bash theme={null}
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:

```yaml theme={null}
networking.datumapis.com/gateway-sync: "true"
```

### Why this matters

* Without this label, the gateway receives the policy but **not the Secret**
* [Envoy](/docs/platform/envoy.md) 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

1. Go to [Google Cloud Console](https://console.cloud.google.com) → **APIs & Services** → **Credentials**
2. Select **Create Credentials** → **OAuth 2.0 Client ID**
3. Set **Application type** to **Web application**
4. Under **Authorized redirect URIs**, add:
   ```
   https://<your-app-hostname>/oauth2/callback
   ```
   Replace `<your-app-hostname>` with the public hostname of your `HTTPRoute`.
5. 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

> [tab] macOS / Linux
>
> ```bash theme={null}
> 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"
> ```

> [tab] Windows (PowerShell)
>
> ```powershell theme={null}
> $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

> [tab] macOS / Linux
>
> ```bash theme={null}
> 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
> ```

> [tab] Windows (PowerShell)
>
> ```powershell theme={null}
> $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 -
> ```

***

### Step 4: Attach OIDC authentication using a SecurityPolicy

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

> [tab] macOS / Linux
>
> ```bash theme={null}
> 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
> ```

> [tab] Windows (PowerShell)
>
> ```powershell theme={null}
> @"
> 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 -
> ```

***

## Verification

### Unauthenticated request

```bash theme={null}
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.

```bash theme={null}
curl -I https://your-app.example.com
```

Expected response after authentication:

```
HTTP/1.1 200 OK
```

***

## Cleanup / disable OIDC authentication

> [tab] macOS / Linux
>
> ```bash theme={null}
> 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
> ```

> [tab] Windows (PowerShell)
>
> ```powershell theme={null}
> 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

```bash theme={null}
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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.