docs(admin/users): add google provider-specific guide (#19309)

DevelopmentCats · matifali · web-flow · commit ea7025b562db · 2025-08-12T13:02:40.000-05:00
## 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>
diff --git a/docs/admin/users/oidc-auth/google.md 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
@@ -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",
