Skip to content

Commit ea7025b

Browse files
docs(admin/users): add google provider-specific guide (#19309)
## 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>
1 parent f4f4e52 commit ea7025b

File tree

2 files changed

+67
-0
lines changed

2 files changed

+67
-0
lines changed

docs/admin/users/oidc-auth/google.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Google authentication (OIDC)
2+
3+
This guide shows how to configure Coder to authenticate users with Google using OpenID Connect (OIDC).
4+
5+
## Prerequisites
6+
7+
- A Google Cloud project with the OAuth consent screen configured
8+
- Permission to create OAuth 2.0 Client IDs in Google Cloud
9+
10+
## Step 1: Create an OAuth client in Google Cloud
11+
12+
1. Open Google Cloud Console → APIs & Services → Credentials → Create Credentials → OAuth client ID.
13+
2. Application type: Web application.
14+
3. Authorized redirect URIs: add your Coder callback URL:
15+
- `https://coder.example.com/api/v2/users/oidc/callback`
16+
4. Save and note the Client ID and Client secret.
17+
18+
## Step 2: Configure Coder OIDC for Google
19+
20+
Set the following environment variables on your Coder deployment and restart Coder:
21+
22+
```env
23+
CODER_OIDC_ISSUER_URL=https://accounts.google.com
24+
CODER_OIDC_CLIENT_ID=<client id>
25+
CODER_OIDC_CLIENT_SECRET=<client secret>
26+
# Restrict to one or more email domains (comma-separated)
27+
CODER_OIDC_EMAIL_DOMAIN="example.com"
28+
# Standard OIDC scopes for Google
29+
CODER_OIDC_SCOPES=openid,profile,email
30+
# Optional: customize the login button
31+
CODER_OIDC_SIGN_IN_TEXT="Sign in with Google"
32+
CODER_OIDC_ICON_URL=/icon/google.svg
33+
```
34+
35+
> [!NOTE]
36+
> The redirect URI must exactly match what you configured in Google Cloud.
37+
38+
## Enable refresh tokens (recommended)
39+
40+
Google uses auth URL parameters to issue refresh tokens. Configure:
41+
42+
```env
43+
# Keep standard scopes
44+
CODER_OIDC_SCOPES=openid,profile,email
45+
# Add Google-specific auth URL params
46+
CODER_OIDC_AUTH_URL_PARAMS='{"access_type": "offline", "prompt": "consent"}'
47+
```
48+
49+
After changing settings, users must log out and back in once to obtain refresh tokens.
50+
51+
Learn more in [Configure OIDC refresh tokens](./refresh-tokens.md).
52+
53+
## Troubleshooting
54+
55+
- "invalid redirect_uri": ensure the redirect URI in Google Cloud matches `https://<your-coder-host>/api/v2/users/oidc/callback`.
56+
- Domain restriction: if users from unexpected domains can log in, verify `CODER_OIDC_EMAIL_DOMAIN`.
57+
- Claims: to inspect claims returned by Google, see guidance in the [OIDC overview](./index.md#oidc-claims).
58+
59+
## See also
60+
61+
- [OIDC overview](./index.md)
62+
- [Configure OIDC refresh tokens](./refresh-tokens.md)

docs/manifest.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -416,6 +416,11 @@
416416
"description": "Configure OpenID Connect authentication with identity providers like Okta or Active Directory",
417417
"path": "./admin/users/oidc-auth/index.md",
418418
"children": [
419+
{
420+
"title": "Google",
421+
"description": "Configure Google as an OIDC provider",
422+
"path": "./admin/users/oidc-auth/google.md"
423+
},
419424
{
420425
"title": "Configure OIDC refresh tokens",
421426
"description": "How to configure OIDC refresh tokens",

0 commit comments

Comments
 (0)