|
| 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) |
0 commit comments