From ea7025b562dbc2cdf2c9c01a4f10f95d69f159e6 Mon Sep 17 00:00:00 2001
From: DevCats <christofer@coder.com>
Date: Tue, 12 Aug 2025 13:02:40 -0500
Subject: [PATCH] docs(admin/users): add google provider-specific guide
 (#19309)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary
- Add a provider-specific guide for configuring Google as an OIDC
provider
- Document refresh token setup via CODER_OIDC_AUTH_URL_PARAMS
- Add page to docs navigation under Users → OIDC Authentication

## Test plan
- Docs site builds: `docs/admin/users/oidc-auth/google.md` renders
- Nav shows 'Google' under OIDC Authentication
- Links to OIDC overview and refresh tokens work

Fixes #13508

---------

Co-authored-by: Atif Ali <atif@coder.com>
---
 docs/admin/users/oidc-auth/google.md | 62 ++++++++++++++++++++++++++++
 docs/manifest.json                   |  5 +++
 2 files changed, 67 insertions(+)
 create mode 100644 docs/admin/users/oidc-auth/google.md

diff --git a/docs/admin/users/oidc-auth/google.md b/docs/admin/users/oidc-auth/google.md
new file mode 100644
index 0000000000..298497b27b
--- /dev/null
+++ b/docs/admin/users/oidc-auth/google.md
@@ -0,0 +1,62 @@
+# Google authentication (OIDC)
+
+This guide shows how to configure Coder to authenticate users with Google using OpenID Connect (OIDC).
+
+## Prerequisites
+
+- A Google Cloud project with the OAuth consent screen configured
+- Permission to create OAuth 2.0 Client IDs in Google Cloud
+
+## Step 1: Create an OAuth client in Google Cloud
+
+1. Open Google Cloud Console → APIs & Services → Credentials → Create Credentials → OAuth client ID.
+2. Application type: Web application.
+3. Authorized redirect URIs: add your Coder callback URL:
+   - `https://coder.example.com/api/v2/users/oidc/callback`
+4. Save and note the Client ID and Client secret.
+
+## Step 2: Configure Coder OIDC for Google
+
+Set the following environment variables on your Coder deployment and restart Coder:
+
+```env
+CODER_OIDC_ISSUER_URL=https://accounts.google.com
+CODER_OIDC_CLIENT_ID=<client id>
+CODER_OIDC_CLIENT_SECRET=<client secret>
+# Restrict to one or more email domains (comma-separated)
+CODER_OIDC_EMAIL_DOMAIN="example.com"
+# Standard OIDC scopes for Google
+CODER_OIDC_SCOPES=openid,profile,email
+# Optional: customize the login button
+CODER_OIDC_SIGN_IN_TEXT="Sign in with Google"
+CODER_OIDC_ICON_URL=/icon/google.svg
+```
+
+> [!NOTE]
+> The redirect URI must exactly match what you configured in Google Cloud.
+
+## Enable refresh tokens (recommended)
+
+Google uses auth URL parameters to issue refresh tokens. Configure:
+
+```env
+# Keep standard scopes
+CODER_OIDC_SCOPES=openid,profile,email
+# Add Google-specific auth URL params
+CODER_OIDC_AUTH_URL_PARAMS='{"access_type": "offline", "prompt": "consent"}'
+```
+
+After changing settings, users must log out and back in once to obtain refresh tokens.
+
+Learn more in [Configure OIDC refresh tokens](./refresh-tokens.md).
+
+## Troubleshooting
+
+- "invalid redirect_uri": ensure the redirect URI in Google Cloud matches `https://<your-coder-host>/api/v2/users/oidc/callback`.
+- Domain restriction: if users from unexpected domains can log in, verify `CODER_OIDC_EMAIL_DOMAIN`.
+- Claims: to inspect claims returned by Google, see guidance in the [OIDC overview](./index.md#oidc-claims).
+
+## See also
+
+- [OIDC overview](./index.md)
+- [Configure OIDC refresh tokens](./refresh-tokens.md)
diff --git a/docs/manifest.json b/docs/manifest.json
index ce03ef0ff2..6e943aa56f 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -416,6 +416,11 @@
 							"description": "Configure OpenID Connect authentication with identity providers like Okta or Active Directory",
 							"path": "./admin/users/oidc-auth/index.md",
 							"children": [
+								{
+									"title": "Google",
+									"description": "Configure Google as an OIDC provider",
+									"path": "./admin/users/oidc-auth/google.md"
+								},
 								{
 									"title": "Configure OIDC refresh tokens",
 									"description": "How to configure OIDC refresh tokens",