Merge pull request #5 from database-playground/pan93412/dbp-20-設計一個比較正常的-oauth

DBP-20: redesign authentication

Author: pan93412

cmd/backend/dependencies.go

@@ -77,11 +77,10 @@ func GinEngine(services []httpapi.Service, authStorage auth.Storage, gqlgenHandl
 	engine.Use(gin.Recovery())
 	engine.Use(httputils.MachineMiddleware())
 	engine.Use(cors.New(cors.Config{
-		AllowOrigins:     cfg.AllowedOrigins,
-		AllowMethods:     []string{"GET", "POST", "OPTIONS"},
-		AllowHeaders:     []string{"Content-Type", "User-Agent", "Referer"},
-		AllowCredentials: true,
-		MaxAge:           24 * time.Hour,
+		AllowOrigins: cfg.AllowedOrigins,
+		AllowMethods: []string{"GET", "POST", "OPTIONS"},
+		AllowHeaders: []string{"Content-Type", "User-Agent", "Referer", "Authorization"},
+		MaxAge:       24 * time.Hour,
 	}))
 
 	router := engine.Group("/")

docs/config.md

@@ -44,13 +44,15 @@ Database Playground 使用 PostgreSQL 作為資料庫。
 
 這個 backend 以 Google OAuth 登入為主。
 
+- `GAUTH_SECRET`：用來加密認證相關請求的 secret
 - `GAUTH_CLIENT_ID`：Google OAuth 的 Client ID
 - `GAUTH_CLIENT_SECRET`：Google OAuth 的 Client Secret
 - `GAUTH_REDIRECT_URIS`：在完成 Google OAuth 流程後，允許重新導向到的 URIs。
   - 舉例：`https://admin.dbplay.app`
 
-Google OAuth 的登入起始連結為 `https://backend.yourdomain.tld/api/auth/google/login`，可選擇性帶入 `state` 參數。
-Google OAuth 的回呼連結為 `https://backend.yourdomain.tld/api/auth/google/callback`。
+OAuth 的使用方式請參考 [Auth 端點](../httpapi/auth/README.md) 內容。
+
+Google OAuth 的「已授權的重新導向 URI」應包含 `https://HOST/api/auth/v2/callback/google` 端點。
 
 ## SQL Runner
 

httpapi/auth/README.md

@@ -2,25 +2,100 @@
 
 Auth 端點提供適合供網頁應用程式使用的認證 API。
 
+## 登入帳號
+
+使用 `GET /api/auth/v2/authorize/google` 登入帳號。
+
+GET 時，您需要帶入這些查詢參數 (query string)：
+
+- `response_type`：目前只支援授權碼模式，必須是 `code`
+- `redirect_uri`：要接收 token 的 callback endpoint，比如 `https://www.dbplay.app/api/auth/callback`
+- `state`：要傳給 redirect URI 的狀態參數
+- `code_challenge`：雜湊後的授權碼，在 callback 中取回 token 時會用到。
+- `code_challenge_method`：必須是 `S256`
+
+`code_challenge` 的雜湊方式如下：
+
+```plain
+code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
+```
+
+登入完成後，會自動跳轉到 `redirect_uri` 上，接著您可以在 redirect URI（下稱 callback）中取回 token。
+
+### Callback 會收到的參數
+
+在驗證完成後，瀏覽器會跳轉到 `redirect_uri`，並帶入以下的查詢字串：
+
+- `code`：取回 token 的授權碼
+- `state`：你在〈登入帳號〉中傳入的狀態參數
+- `code_challenge`：你在〈登入帳號〉中傳入的雜湊授權碼
+- `code_challenge_method`：你在〈登入帳號〉中傳入的雜湊授權碼
+
+接著您可以使用〈取回 token〉API 來取得 token。
+
+如果登入失敗，則是會帶入以下的查詢字串：
+
+- `error`：錯誤代碼
+- `error_description`：錯誤描述
+
+## 取回 token
+
+使用 `POST /api/auth/v2/token` 取回 token。
+
+POST 時，您需要帶入這些查詢參數 (query string)：
+
+- `grant_type`：目前只支援授權碼模式，必須是 `authorization_code`
+- `code`：你在 `redirect_uri` 收到的授權碼
+- `redirect_uri`：重新導向連結，必須與〈登入帳號〉的 redirect URI 相同
+
+如果一切順利的話，會回傳 token、token type、過期時間等資訊：
+
+```json
+{
+    "token_type": "Bearer",
+    "access_token": "2YotnFZFEjr1zCsicMWpAA",
+    "expires_in": 28800
+}
+```
+
+## 授權
+
+請將 access token 帶入 `Authorization` 標頭中，格式如下：
+
+```plain
+Authorization: Bearer <access_token>
+```
+
+預設 `access_token` 會存活 8 小時，且只要 token 有人存取就會延長。
+
+如果需要登出的話，除了使用〈登出帳號〉API 撤銷特定 token 外，也可以使用 GraphQL 的批次撤銷來處理。
+
 ## 登出帳號
 
-您可以使用 `POST /api/logout` 登出帳號。
+您可以使用 `POST /api/auth/v2/revoke` 登出帳號。
+
+需要帶入以 `application/x-www-form-urlencoded` 編碼的請求體：
+
+- `token`：要 revoke 的 token
+- `token_type_hint`：必須是 `access_token`
 
 如果 Token 撤回失敗，則會回傳 HTTP 500 錯誤並帶上錯誤資訊：
 
 ```json
 {
-    "error": "Failed to revoke the token. Please try again later.",
-    "detail": "(error details)",
+    "error": "server_error",
+    "error_description": "Failed to revoke the token. Please try again later."
 }
 ```
 
-如果 Token 撤回成功，則回傳 HTTP 205 (Reset Content)，此時您可以重新整理登入狀態。
+如果 Token 撤回成功，則回傳 HTTP 200 OK，此時您可以重新整理登入狀態。
 
-如果沒有 Auth Token 或者是 token 無效，則依然回傳 HTTP 205。請引導使用者重新登入。
+如果沒有 Auth Token 或者是 token 無效，則依然回傳 HTTP 200。請引導使用者重新登入。
 
-## Google 登入
+## 參考來源
 
-如果您要觸發 Google 登入的流程，請前往 `GET /api/auth/google/login`。可以帶入 `redirect_uri` 參數來在登入完成後轉導到指定畫面。
+為了保證登入時的資訊安全，這裡參考了兩份 RFC 進行 API 的設計：
 
-這個頁面會重新導向到 Google 的登入頁面，登入後會回到 `POST /api/auth/google/callback` 並進行帳號登入和註冊手續。
+- [RFC 6749 – The OAuth 2.0 Authorization Framework](https://datatracker.ietf.org/doc/html/rfc6749#autoid-35)
+- [RFC 7636 – Proof Key for Code Exchange by OAuth Public Clients](https://datatracker.ietf.org/doc/html/rfc7636#section-4.1)
+- [RFC 7009 – OAuth 2.0 Token Revocation](https://datatracker.ietf.org/doc/html/rfc7009)