陽明交通大學 OAuth 服務 - 開發者說明文件

這裡會介紹如何透過陽明交通大學 OAuth 服務獲取使用者資訊。本平台是依據 OAuth 2.0 (RFC6749) 的標準開發，目前僅開放 Authorization Code 方式來認證。

1. 註冊應用程式

1. 前往 https://id.nycu.edu.tw/apply/app 註冊應用程式。
2. 填寫以下資訊：
   • Client Name：您的應用程式名稱。
   • Client Type: Public
   • Authorization Grant Type: Authorization code
   • Redirect URIs：使用者授權後，會被重新導向到此網址，此欄位為白名單機制，如需要多個網址，請填寫所有使用的網址。
3. 在此頁面找到 https://id.nycu.edu.tw/apply/app，獲取剛剛所申請到的 Client Id, Client Secret, Redirect URIs

2. 授權流程

Step 1: 將使用者導向授權頁面

您的應用程式需要將使用者導向 NYCU OAuth 的授權頁面，並附上以下參數：

• response_type: code
• client_id: 您註冊後得到的 Client ID
• redirect_uri: 您註冊時填寫的 重新導向網址
• scope: 您想要存取的資料範圍，例如 profile、name。多個 scope 請用空白分隔。
• state: (可選) 一個隨機字串，用於防止 CSRF 攻擊。

範例 URL:

https://id.nycu.edu.tw/o/authorize/?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=profile&state=RANDOM_STRING

使用者會被導向登入頁面，登入並授權後，頁面會重新導向所提供的 redirect_uri，並附上 code 和 state。

範例重新導向 URL:

https://your-app.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STRING

Step 2: 用授權碼 (Authorization Code) 交換存取權杖 (Access Token)

您的後端服務需要拿著 code，向 NYCU OAuth 的 token 端點發送一個 POST 請求，以交換 Access Token。

請求 URL: https://id.nycu.edu.tw/o/token/

請求方法: POST

請求標頭 (Headers):

Content-Type: application/x-www-form-urlencoded

請求主體 (Body):

• grant_type: authorization_code
• code: 在 Step 1 得到的 AUTHORIZATION_CODE
• redirect_uri: 註冊時填寫的 重新導向網址
• client_id: 應用程式的 Client ID
• client_secret: 應用程式的 Client Secret

範例 cURL 請求:

curl -X POST https://id.nycu.edu.tw/o/token/ \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

成功的回應:

您會收到一個 JSON 物件，其中包含 access_token、refresh_token 等資訊。

{
  "access_token": "ACCESS_TOKEN",
  "expires_in": 36000,
  "token_type": "Bearer",
  "scope": "profile email",
  "refresh_token": "REFRESH_TOKEN"
}

3. 取得使用者資料

有了 access_token，您就可以向 API 端點請求使用者資料，部分機敏資料需審核。以profile為例：

API 端點: https://id.nycu.edu.tw/api/profile/

請求方法: GET

請求標頭 (Headers):

Authorization: Bearer ACCESS_TOKEN

範例 cURL 請求:

curl -X GET https://id.nycu.edu.tw/api/profile/ \
  -H "Authorization: Bearer ACCESS_TOKEN"

成功的回應:

您會收到一個 JSON 物件，其中包含使用者的個人資料。

{
    "username": "testuser",
    "email": "test@nycu.edu.tw",
}

申請機敏資料存取核可

若需要存取機敏資料，必須在系統內提出申請，通過學校的核可後才有存取權限。

申請方法

在應用程式的管理頁面中，在「申請核可」這個欄位填寫所需的欄位及用途，通過校方的審查後即可使用。

支援的 Scopes

4. 撤銷權杖 (Revoke Token)

您可以撤銷 Access Token 或 Refresh Token。

請求 URL: https://id.nycu.edu.tw/o/revoke_token/

請求方法: POST

請求標頭 (Headers):

Content-Type: application/x-www-form-urlencoded

請求主體 (Body):

• token: 您想要撤銷的 Access Token
• client_id: 應用程式的 Client ID
• client_secret: 應用程式的 Client Secret (Confidential Client 需要)

範例 cURL 請求:

curl -X POST https://id.nycu.edu.tw/o/revoke_token/ \
  -d "token=YOUR_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

成功的回應:

如果成功，會回傳一個 HTTP 200 OK 狀態碼，且 Body 為空。

若有任何問題，請聯繫 NYCU OAuth 管理員。