OAuth 服務說明文件

本文件介紹如何使用本服務提供的 OAuth 系統進行用戶授權與認證，並獲取用戶資料。本系統基於 OAuth 2.0 標準（RFC 6749）開發，目前僅支援 Authorization Code 認證方式。

平台網址：https://oauth.yzu.edu.tw

認證方法

（一）申請應用程式

目前暫不開放

（二）獲取使用者授權

使用以下 URL 發起授權請求，將 <client_id>、<scope>、<state>和 <redirect_uri> 替換為實際值：

https://oauth.yzu.edu.tw/authorize?client_id=&scope=&redirect_uri=

範例請求：
（1）自行製作跳轉至網頁

https://oauth.yzu.edu.tw/authorize?client_id=zflow&state=ooxxooxx&redirect_uri=https://flower.yzu.edu.tw/admin/api/oauth_callback.php

（2）透過按鈕跳轉








<a href="https://oauth.yzu.edu.tw/login?client_id=zflow&redirect_uri=https://flower.yzu.edu.tw/admin/api/oauth_callback.php" 
    style="display: inline-flex; align-items: center; justify-content: center;
    text-decoration: none; color: #000000; background-color: #ffffff; border-radius: 4px;
    padding: 10px 20px; font-size: 16px; box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);">
    <img src="https://oauth.yzu.edu.tw/images/yzu-icon.png" alt="OAuth Icon" style="
        width: 20px; height: 20px; margin-right: 10px;">
    使用 OAuth 登入
</a>

用戶將通過此連結登入並授權。
3.1 成功授權後，瀏覽器將跳轉至指定的 Redirect URI，並附加授權碼參數：

https://example.com/oauth/callback?authorized=true&code=xxxxxx&state=xxxxx

3.2 用戶拒絕授權，導致失敗會跳轉至

https://example.com/oauth/callback?authorized=false&state=xxxxxx

記錄 <Authorization Code>，以便後續使用。

（三）與 OAuth 伺服器交換 Token

使用 POST 請求至以下網址：
請求表單包含以下參數：

code: <Authorization Code>
client_id: <Client ID>
client_secret: <Client Secret>
redirect_uri: <Redirect URI>

範例請求：

POST https://oauth.yzu.edu.tw/api/exchange
Content-Type: application/x-www-form-urlencoded
code=your-authorization-code&
client_id=your-client-id&
client_secret=your-client-secret

伺服器回應

{
    "token_type": "Bearer",
    "access_token": "<Access Token>",
}

（四）使用 Access Token 獲取用戶資訊

使用 GET 請求至以下資源 URL，並在標頭中附加授權資訊：

Authorization: Bearer <Access Token>

範例請求：

GET https://oauth.yzu.edu.tw/api/userinfo
Authorization: Bearer your-access-token

伺服器回應：

{
    "userid": "user123",
    "email": "user123@yzu.edu.tw"
}

OAuth 可用 Scope 說明

以下表格列出 OAuth 系統中可用的 Scope，以及每個 Scope 的用途說明。

Scope 名稱	用途說明	存取權限
`userid`	用戶的 `Portal 帳號`	必選
`email`	用戶的備用電子郵件地址	可選
`name`	用戶的姓名	可選
`name_en`	用戶的英文姓名	可選
`dept`	用戶所屬部門	可選
`grade`	用戶的年級資訊	可選
`position`	用戶的職位資訊	可選
`dept_id`	用戶所屬部門的識別碼	可選
`status`	用戶的當前狀態（例如在學或離校）	可選
`role`	用戶角色（例如`student`或`staff`）	可選
`inschool`	是否為在校用戶（布林值: 在職、在校）	可選
`phone`	聯絡電話	機密

使用建議

Scope之間使用 , , , ; 分隔
僅請求應用程式所需的 Scope，避免請求不必要的權限。
在授權流程中，用戶將看到您所請求的 Scope，請確保用途透明且符合使用者期望。
機密內容需要向學校申請才可選用。

常見錯誤

Invalid Authorization Code
• 原因：授權碼已過期或無效。
• 解決方法：重新發起授權請求以獲取新的授權碼。
Invalid Client ID/Secret
• 原因：Client ID 或 Client Secret 不正確。
• 解決方法：確認您的憑證是否與申請的憑證匹配。
Invalid or Expired Token
• 原因：Access Token 已過期或無效。
• 解決方法：重新發起授權流程。