Github

Github 的 Oauth App 介紹 (一)

Github 的 OAuth App

如何建立 OAuth App?

Authorizing OAuth Apps

Authorization flow 的分類

  1. web application flow

    • Used to authorize users for standard OAuth apps that run in the browser. (The implicit grant type is not supported.)

  2. device flow

    • Used for headless apps, such as CLI tools.

Web application flow

簡單 3 步驟可完成 👌

  1. Users are redirected to request their GitHub identity

  2. Users are redirected back to your site by GitHub

  3. Your app accesses the API with the user’s access token

讓我們來詳細說說吧!

  1. Request a user’s GitHub identity

    • 利用 redirect 方式取得使用者的 GitHub identity，此時瀏覽器會跳出登入頁面讓使用者登入，需輸入帳密

    • 📌Request 方式如下

      • Required parameters
        • client_id
        GET https://github.com/login/oauth/authorize

  2. Users are redirected back to your site by GitHub，接著請求 access token

    • 步驟一若成功完成驗證，則頁面會被返回至 App，接著要進行請求 access token
    • 📌Request 方式如下
      • Required parameters
        • client_id
        • client_secret
        • code，就是步驟一所帶的 state 欄位值
      POST https://github.com/login/oauth/access_token

    • 📌Response

      • 成功的話，你會取得一組 access token
       Accept: application/json
 {
   "access_token":"gho_16C7e42F292c6912E7710c838347Ae178B4a",
   "scope":"repo,gist",
   "token_type":"bearer"
 }

  3. Use the access token to access the API

    • 利用步驟二的 access token 去 access API
    • 📌這邊提供兩個 access API 的 request 方式
      # 方式一
  Authorization: Bearer OAUTH-TOKEN
  GET https://api.github.com/user

  # 方式二
  curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.github.com/user

Device flow

  • 目的: authorize users for a headless app, such as a CLI tool or Git credential manager.
簡單 3 步驟可完成 👌

  1. Your app requests device and user verification codes and gets the authorization URL where the user will enter the user verification code.

  2. The app prompts the user to enter a user verification code at https://github.com/login/device.

  3. The app polls for the user authentication status. Once the user has authorized the device, the app will be able to make API calls with a new access token.

讓我們來詳細說說吧!

  • Step 1: App requests the device and user verification codes from GitHub

    • 📌Request

      • Required parameters
        • client_id
        POST https://github.com/login/device/code

    • 📌Response

      • ⚠️記下來 user code & verification uri，步驟二驗證時會使用到
      • ⚠️記下來 device code，步驟三驗證時會使用到
      • interval 意義是 minimum polling interval，單位為秒。
        • 步驟三 app 會去 github poll (輪詢) user 是否已驗證完成此 device
        • interval 即指 poll 的最小時間間隔。
        • 若在 interval 內請求超過 1 次，則會到達 rate limit，會得到一些 error response，更詳細請看 👉 rate limits
        Accept: application/json
  {
    "device_code": "3584d83530557fdd1f46af8289938c8ef79f9dc5",
    "user_code": "WDJB-MJHT",
    "verification_uri": "https://github.com/login/device",
    "expires_in": 900,
    "interval": 5
  }

  • Step 2: Prompt the user to enter the user code in a browser

  • Step 3: App polls GitHub to check if the user authorized the device

    • 📌Request

      • Required parameters
        • 步驟一得到的 device code
        • client id
        • 指定的 grant type
      • ⚠️注意: 發送輪詢請求，請求間隔必須大於最小輪詢時間間隔，否則會得到 error response，更詳細請看 👉 rate limits
        POST https://github.com/login/oauth/access_token

    • 📌Response

      • 成功取得 access token
        Accept: application/json
  {
  "access_token": "gho_16C7e42F292c6912E7710c838347Ae178B4a",
    "token_type": "bearer",
    "scope": "repo,gist"
  }

Rate limits

  • ⚠️當達到 rate limits，會得到 slow_down 的 error response
  • 📌更多 error response 請參考官方文件

📅 續集(二)會介紹 Non-Web application flow、Creating multiple tokens for OAuth Apps 以及 Directing users to review their access

參考資料 👐

🍀 最後，若喜歡我的分享，可以免費幫我按讚，是對我最大的鼓勵! ✨ ✨ ✨