docs: rewrite OIDC auth guide with complete setup instructions
- Add architecture flow diagram - Add Google OAuth consent screen steps - Add troubleshooting section - Remove obsolete NEXT_PUBLIC_ACCOUNTS_SVC_URL reference - Add quick reference table
This commit is contained in:
Haitao Pan
parent
4ce4147a8a
commit
2d2c972e29
@ -1,88 +1,244 @@
|
||||
# OIDC Authentication Configuration Guide
|
||||
|
||||
This guide describes how to configure GitHub and Google OIDC authentication for the Cloud Neutral Toolkit.
|
||||
This guide describes how to configure GitHub and Google OAuth login for the Cloud Neutral Toolkit, enabling any user to sign in with their own GitHub or Google account.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌──────────────┐ ┌──────────────────┐ ┌──────────────────┐
|
||||
│ Browser │ │ console.svc.plus │ │accounts.svc.plus │
|
||||
│ (User) │ │ (Frontend) │ │ (Backend) │
|
||||
└──────┬───────┘ └────────┬─────────┘ └────────┬─────────┘
|
||||
│ 1. Click "Login │ │
|
||||
│ with GitHub" │ │
|
||||
│──────────────────────>│ │
|
||||
│ │ │
|
||||
│ 2. Redirect to │ │
|
||||
│ accounts /api/ │ │
|
||||
│ auth/oauth/login/ │ │
|
||||
│ github │ │
|
||||
│<──────────────────────│ │
|
||||
│ │ │
|
||||
│ 3. accounts redirects to GitHub/Google │
|
||||
│ with client_id & callback URL │
|
||||
│<────────────────────────────────────────────────│
|
||||
│ │ │
|
||||
│ 4. User authorizes │ │
|
||||
│ on GitHub/Google │ │
|
||||
│ │ │
|
||||
│ 5. GitHub/Google redirects back to │
|
||||
│ accounts /api/auth/oauth/callback/github │
|
||||
│─────────────────────────────────────────────────>
|
||||
│ │ │
|
||||
│ 6. accounts exchanges code for token, │
|
||||
│ creates/links user, redirects to console │
|
||||
│<────────────────────────────────────────────────│
|
||||
│ │ │
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Access to GitHub Developer Settings.
|
||||
- Access to Google Cloud Console.
|
||||
- Properly configured `accounts.svc.plus` and `console.svc.plus` services.
|
||||
- A GitHub account with access to **Settings > Developer Settings**
|
||||
- A Google account with access to [Google Cloud Console](https://console.cloud.google.com/)
|
||||
- Running `accounts.svc.plus` and `console.svc.plus` services
|
||||
|
||||
---
|
||||
|
||||
## 1. GitHub Configuration
|
||||
## 1. GitHub OAuth App
|
||||
|
||||
### 1.1 Create GitHub OAuth App
|
||||
### 1.1 Create OAuth App
|
||||
|
||||
1. Log in to GitHub and go to **Settings** > **Developer Settings** > **OAuth Apps**.
|
||||
2. Click **New OAuth App**.
|
||||
3. **Application name**: e.g., `Cloud Neutral Console`
|
||||
4. **Homepage URL**: `https://console.svc.plus` (or your actual console domain)
|
||||
5. **Authorization callback URL**: `https://accounts.svc.plus/api/auth/oauth/callback/github`
|
||||
6. Click **Register application**.
|
||||
7. Copy the **Client ID**.
|
||||
8. Click **Generate a new client secret** and copy the **Client Secret**.
|
||||
1. Go to [GitHub Developer Settings > OAuth Apps](https://github.com/settings/developers)
|
||||
2. Click **"OAuth Apps"** tab, then **"New OAuth App"**
|
||||
3. Fill in the form:
|
||||
|
||||
### 1.2 Configure Environment Variables
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| **Application name** | `Cloud Neutral Console` |
|
||||
| **Homepage URL** | `https://console.svc.plus` |
|
||||
| **Authorization callback URL** | `https://accounts.svc.plus/api/auth/oauth/callback/github` |
|
||||
| **Enable Device Flow** | ☐ (unchecked) |
|
||||
|
||||
Set the following environment variables for **accounts.svc.plus**:
|
||||
4. Click **"Register application"**
|
||||
|
||||
```bash
|
||||
GITHUB_CLIENT_ID=your_github_client_id
|
||||
GITHUB_CLIENT_SECRET=your_github_client_secret
|
||||
# Optional: if you want to override the default callback
|
||||
# GITHUB_REDIRECT_URL=https://accounts.svc.plus/api/auth/oauth/callback/github
|
||||
### 1.2 Generate Client Secret
|
||||
|
||||
1. On the app detail page, copy the **Client ID** (displayed at the top)
|
||||
2. Click **"Generate a new client secret"**
|
||||
3. **Immediately copy the Client Secret** — it will only be shown once
|
||||
|
||||
### 1.3 Record Credentials
|
||||
|
||||
```
|
||||
GitHub Client ID: Ov23li...
|
||||
GitHub Client Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
Callback URL: https://accounts.svc.plus/api/auth/oauth/callback/github
|
||||
```
|
||||
|
||||
> ⚠️ **Security**: Never commit Client Secret to version control. Store it as an environment variable or in a secret manager.
|
||||
|
||||
### 1.4 GitHub OAuth Scopes
|
||||
|
||||
The OAuth App requests these scopes by default:
|
||||
- `user:email` — Read the user's email addresses (used for account binding)
|
||||
|
||||
No additional GitHub permissions are required.
|
||||
|
||||
---
|
||||
|
||||
## 2. Google OAuth Client ID
|
||||
|
||||
### 2.1 Configure OAuth Consent Screen
|
||||
|
||||
> This step is required before creating credentials. If already configured, skip to 2.2.
|
||||
|
||||
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
|
||||
2. Select or create a project
|
||||
3. Navigate to **APIs & Services > OAuth consent screen**
|
||||
4. Choose **External** user type (allows any Google user to sign in)
|
||||
5. Fill in the required fields:
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| **App name** | `Cloud Neutral Console` |
|
||||
| **User support email** | your email address |
|
||||
| **Developer contact email** | your email address |
|
||||
|
||||
6. Add scopes: `email`, `profile`, `openid`
|
||||
7. Click **Save and Continue** through the remaining steps
|
||||
8. Under **Publishing status**, click **"Publish App"** to move out of testing mode
|
||||
- In testing mode, only manually added test users can sign in
|
||||
|
||||
### 2.2 Create OAuth Client ID
|
||||
|
||||
1. Go to **APIs & Services > Credentials**
|
||||
2. Click **"Create Credentials" > "OAuth client ID"**
|
||||
3. Fill in the form:
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| **Application type** | `Web application` |
|
||||
| **Name** | `Cloud Neutral Console` |
|
||||
| **Authorized JavaScript origins** | `https://console.svc.plus` |
|
||||
| **Authorized redirect URIs** | `https://accounts.svc.plus/api/auth/oauth/callback/google` |
|
||||
|
||||
4. Click **"Create"**
|
||||
5. Copy the **Client ID** and **Client Secret** from the popup
|
||||
|
||||
### 2.3 Record Credentials
|
||||
|
||||
```
|
||||
Google Client ID: xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com
|
||||
Google Client Secret: GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
Callback URL: https://accounts.svc.plus/api/auth/oauth/callback/google
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Google Configuration
|
||||
|
||||
### 2.1 Create Google OAuth Client ID
|
||||
|
||||
1. Log in to [Google Cloud Console](https://console.cloud.google.com/).
|
||||
2. Select or create a project.
|
||||
3. Go to **APIs & Services** > **Credentials**.
|
||||
4. Click **Create Credentials** > **OAuth client ID**.
|
||||
5. **Application type**: `Web application`.
|
||||
6. **Name**: e.g., `Cloud Neutral Console`.
|
||||
7. **Authorized JavaScript origins**:
|
||||
- `https://console.svc.plus`
|
||||
8. **Authorized redirect URIs**:
|
||||
- `https://accounts.svc.plus/api/auth/oauth/callback/google`
|
||||
9. Click **Create**.
|
||||
10. Copy the **Client ID** and **Client Secret**.
|
||||
|
||||
### 2.2 Configure Environment Variables
|
||||
## 3. Backend Configuration (accounts.svc.plus)
|
||||
|
||||
Set the following environment variables for **accounts.svc.plus**:
|
||||
|
||||
```bash
|
||||
GOOGLE_CLIENT_ID=your_google_client_id
|
||||
GOOGLE_CLIENT_SECRET=your_google_client_secret
|
||||
# Optional: if you want to override the default callback
|
||||
# GOOGLE_REDIRECT_URL=https://accounts.svc.plus/api/auth/oauth/callback/google
|
||||
```
|
||||
# ── GitHub OAuth ──
|
||||
GITHUB_CLIENT_ID=<your_github_client_id>
|
||||
GITHUB_CLIENT_SECRET=<your_github_client_secret>
|
||||
|
||||
---
|
||||
# ── Google OAuth ──
|
||||
GOOGLE_CLIENT_ID=<your_google_client_id>
|
||||
GOOGLE_CLIENT_SECRET=<your_google_client_secret>
|
||||
|
||||
## 3. General OIDC Environment Variables
|
||||
|
||||
Ensure these are also set for **accounts.svc.plus**:
|
||||
|
||||
```bash
|
||||
# ── General OAuth ──
|
||||
OAUTH_REDIRECT_URL=https://accounts.svc.plus/api/auth/oauth/callback
|
||||
OAUTH_FRONTEND_URL=https://console.svc.plus
|
||||
```
|
||||
|
||||
**Note**: The backend automatically appends `/{provider}` to `OAUTH_REDIRECT_URL` if a provider-specific redirect URL is not provided.
|
||||
These variables are referenced in `config/account.yaml`:
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
oauth:
|
||||
redirectUrl: "${OAUTH_REDIRECT_URL}"
|
||||
frontendUrl: "${OAUTH_FRONTEND_URL:-https://console.svc.plus}"
|
||||
github:
|
||||
clientId: "${GITHUB_CLIENT_ID}"
|
||||
clientSecret: "${GITHUB_CLIENT_SECRET}"
|
||||
google:
|
||||
clientId: "${GOOGLE_CLIENT_ID}"
|
||||
clientSecret: "${GOOGLE_CLIENT_SECRET}"
|
||||
```
|
||||
|
||||
> **Note**: The backend automatically appends `/{provider}` to `OAUTH_REDIRECT_URL` (e.g. `.../callback/github`) if a provider-specific redirect URL is not set.
|
||||
|
||||
---
|
||||
|
||||
## 4. Frontend Configuration
|
||||
## 4. Frontend Configuration (console.svc.plus)
|
||||
|
||||
For **console.svc.plus**, ensure the following is set so it knows where to redirect for the initial OAuth step:
|
||||
The frontend resolves the accounts service URL **server-side** via `getAccountServiceBaseUrl()`, which reads:
|
||||
|
||||
```bash
|
||||
NEXT_PUBLIC_ACCOUNTS_SVC_URL=https://accounts.svc.plus
|
||||
# Set in accounts.svc.plus deployment environment
|
||||
ACCOUNT_SERVICE_URL=https://accounts.svc.plus
|
||||
```
|
||||
|
||||
If not set, the function falls back to a runtime default. **No `NEXT_PUBLIC_*` env var is needed** — the OAuth login URLs are constructed server-side and passed to the client components as props.
|
||||
|
||||
### OAuth Login URLs (auto-generated)
|
||||
|
||||
| Provider | Login URL |
|
||||
|---|---|
|
||||
| GitHub | `{accountServiceBaseUrl}/api/auth/oauth/login/github` |
|
||||
| Google | `{accountServiceBaseUrl}/api/auth/oauth/login/google` |
|
||||
|
||||
### OAuth Callback URLs (handled by accounts.svc.plus)
|
||||
|
||||
| Provider | Callback URL |
|
||||
|---|---|
|
||||
| GitHub | `https://accounts.svc.plus/api/auth/oauth/callback/github` |
|
||||
| Google | `https://accounts.svc.plus/api/auth/oauth/callback/google` |
|
||||
|
||||
---
|
||||
|
||||
## 5. Troubleshooting
|
||||
|
||||
### `undefined/api/auth/oauth/login/github`
|
||||
|
||||
**Cause**: OAuth URLs were using a client-side env var (`NEXT_PUBLIC_ACCOUNTS_SVC_URL`) that was not set.
|
||||
|
||||
**Fix** (applied in commit `4ce4147`): OAuth URLs now use the server-resolved `accountServiceBaseUrl` prop.
|
||||
|
||||
### OAuth login redirects to wrong domain
|
||||
|
||||
Check that `OAUTH_FRONTEND_URL` in accounts.svc.plus matches the console domain where users should be redirected after authentication.
|
||||
|
||||
### Google "Access blocked: This app's request is invalid"
|
||||
|
||||
Ensure the **Authorized redirect URI** in Google Cloud Console **exactly** matches:
|
||||
```
|
||||
https://accounts.svc.plus/api/auth/oauth/callback/google
|
||||
```
|
||||
Trailing slashes or mismatched protocols will cause this error.
|
||||
|
||||
### GitHub "The redirect_uri MUST match the registered callback URL"
|
||||
|
||||
Ensure the **Authorization callback URL** in GitHub Developer Settings **exactly** matches:
|
||||
```
|
||||
https://accounts.svc.plus/api/auth/oauth/callback/github
|
||||
```
|
||||
|
||||
### Google OAuth in "Testing" mode — only test users can sign in
|
||||
|
||||
Go to **OAuth consent screen > Publishing status** and click **"Publish App"** to allow any Google user to sign in.
|
||||
|
||||
---
|
||||
|
||||
## 6. Quick Reference
|
||||
|
||||
| Item | Value |
|
||||
|---|---|
|
||||
| GitHub OAuth App Settings | https://github.com/settings/developers |
|
||||
| Google Cloud Credentials | https://console.cloud.google.com/apis/credentials |
|
||||
| GitHub Callback URL | `https://accounts.svc.plus/api/auth/oauth/callback/github` |
|
||||
| Google Callback URL | `https://accounts.svc.plus/api/auth/oauth/callback/google` |
|
||||
| Backend Config File | `accounts.svc.plus/config/account.yaml` |
|
||||
| Frontend URL Resolution | `getAccountServiceBaseUrl()` in `src/server/serviceConfig.ts` |
|
||||
|
||||
Loading…
Reference in New Issue
Block a user