OAuth 2.0

OAuth 2.0 是一種授權協定，可讓 API 用戶端有限地存取 Web 伺服器上的使用者資料。GitHub、Google 和 Facebook API 都明顯地使用它。OAuth 依賴稱為流程的驗證情境，這些流程允許資源擁有者 (使用者) 在不分享其憑證的情況下，從資源伺服器分享受保護的內容。為此，OAuth 2.0 伺服器會發出存取權杖，用戶端應用程式可以使用這些權杖代表資源擁有者存取受保護的資源。如需關於 OAuth 2.0 的更多資訊，請參閱 oauth.net 和 RFC 6749。

流程

流程 (也稱為授權類型) 是 API 用戶端執行以從授權伺服器取得存取權杖的情境。OAuth 2.0 提供多種適用於不同類型 API 用戶端的流程

授權碼 – 最常見的流程，主要用於伺服器端和行動 Web 應用程式。此流程類似於使用者使用其 Facebook 或 Google 帳戶登入 Web 應用程式的方式。
隱含 – 此流程要求用戶端直接擷取存取權杖。當使用者的憑證無法儲存在用戶端程式碼中，因為協力廠商可以輕鬆存取這些憑證時，此流程很有用。它適用於不包含任何伺服器元件的 Web、桌面和行動應用程式。
資源擁有者密碼憑證 (或簡稱 password) – 要求使用使用者名稱和密碼登入。由於在這種情況下，憑證將成為請求的一部分，因此此流程僅適用於受信任的用戶端 (例如，API 提供者發佈的官方應用程式)。
用戶端憑證 – 用於伺服器對伺服器驗證，此流程描述一種方法，其中用戶端應用程式代表自身而不是代表任何個人使用者。在大多數情況下，此流程提供讓使用者在用戶端應用程式中指定其憑證的方法，以便它可以存取在用戶端控制下的資源。

使用 OpenAPI 描述 OAuth 2.0

若要描述使用 OAuth 2.0 保護的 API，首先，請在全域 components/securitySchemes 區段中新增 type: oauth2 的安全性配置。然後新增 security 金鑰，以全域或個別操作的方式套用安全性

1
# Step 1 - define the security scheme
2
components:
3
  securitySchemes:
4
    oAuthSample:    # <---- arbitrary name
5
      type: oauth2
6
      description: This API uses OAuth 2 with the implicit grant flow. [More info](https://api.example.com/docs/auth)
7
      flows:
8
        implicit:   # <---- OAuth flow(authorizationCode, implicit, password or clientCredentials)
9
          authorizationUrl: https://api.example.com/oauth2/authorize
10
          scopes:
11
            read_pets: read your pets
12
            write_pets: modify pets in your account
13

14
# Step 2 - apply security globally...
15
security:
16
  - oAuthSample:
17
    - write_pets
18
    - read_pets
19

20
# ... or to individual operations
21
paths:
22
  /pets:
23
    patch:
24
      summary: Add a new pet
25
      security:
26
        - oAuthSample:
27
          - write_pets
28
          - read_pets
29
      ...

flows 關鍵字指定此 OAuth 2.0 配置支援的一或多個已命名流程。流程名稱為

authorizationCode – 授權碼流程 (先前在 OpenAPI 2.0 中稱為 accessCode)
implicit – 隱含流程
password – 資源擁有者密碼流程
clientCredentials – 用戶端憑證流程 (先前在 OpenAPI 2.0 中稱為 application)

flows 物件可以指定多個流程，但每種類型只能有一個。每個流程都包含以下資訊

欄位名稱	描述	適用於流程
欄位名稱	描述	`authorizationCode`	`implicit`	`password`	`clientCredentials`
`authorizationUrl`	此流程要使用的授權 URL。可以相對於 API 伺服器 URL。	+	+	-	-
`tokenUrl`	此流程要使用的權杖 URL。可以相對於 API 伺服器 URL。	+	-	+	+
`refreshUrl`	選用。用於取得重新整理權杖的 URL。可以相對於 API 伺服器 URL。	+	+	+	+
`scopes`	OAuth2 安全性配置的可用範圍。範圍名稱與其簡短描述之間的對應。	+	+	+	+

關於範圍

在 OpenAPI 3.0 中，使用者可以授予其帳戶的範圍存取權，這可能會因用戶端應用程式想要執行的操作而異。每個 OAuth 存取權杖都可以標記多個範圍。範圍是存取權限，控制使用者提供的憑證是否允許對資源伺服器執行所需的呼叫。它們不會授予用戶端任何額外權限，除了它已經擁有的權限之外。注意：在授權碼和隱含流程中，請求的範圍會列在顯示給使用者的授權表單上。若要套用範圍，您需要執行兩個步驟

在 components/securitySchemes 區段中，定義 OAuth 安全性定義中所有支援的範圍

1
components:
2
  securitySchemes:
3
    oAuthSample:
4
      type: oauth2
5
      flows:
6
        implicit:
7
          authorizationUrl: https://api.example.com/oauth2/authorize
8
          scopes:
9
            read_pets: read pets in your account
10
            write_pets: modify pets in your account

在該操作的 security 區段中，列出每個操作所需的範圍

1
paths:
2
  /pets/{petId}:
3
    patch:
4
      summary: Updates a pet in the store
5
      security:
6
        - oAuthSample: [write_pets]
7
      ...

如果所有 API 操作都需要相同的範圍，您可以在 API 定義的根層級新增 security

1
security:
2
  - oAuthSample: [write_pets]

沒有範圍

範圍是選用的，您的 API 可能不會使用任何範圍。在這種情況下，請在範圍定義中指定空物件 {}，並在 security 區段中指定空範圍清單 []

1
components:
2
  securitySchemes:
3
    oAuthNoScopes:
4
      type: oauth2
5
      flows:
6
        implicit:
7
          authorizationUrl: https://api.example.com/oauth2/authorize
8
          scopes: {} # <-----
9

10
security:
11
  - oAuthNoScopes: [] # <-----

相對端點 URL

在 OpenAPI 3.0 中，authorizationUrl、tokenUrl 和 refreshUrl 可以指定為相對於 API 伺服器 URL。如果這些端點與其餘 API 操作位於同一伺服器上，這會很方便。

1
servers:
2
  - url: https://api.example.com/v2
3

4
components:
5
  securitySchemes:
6
    oauth2sample:
7
      type: oauth2
8
      flows:
9
        authorizationCode:
10
          authorizationUrl: /oauth/authorize # <-----
11
          tokenUrl: /oauth/token # <-----
12
          scopes: ...

相對 URL 會根據 RFC 3986 進行解析。在上面的範例中，端點將解析為

authorizationUrl：https://api.example.com/oauth/authorize

tokenUrl：https://api.example.com/oauth/token

安全性配置範例

授權碼流程

authorization 流程使用 authorizationUrl、tokenUrl 和選用的 refreshUrl。以下是 Slack API 的範例

1
components:
2
  securitySchemes:
3
    oAuth2AuthCode:
4
      type: oauth2
5
      description: For more information, see https://api.slack.com/docs/oauth
6
      flows:
7
        authorizationCode:
8
          authorizationUrl: https://slack.com/oauth/authorize
9
          tokenUrl: https://slack.com/api/oauth.access
10
          scopes:
11
            users:read: Read user information
12
            users:write: Modify user information
13
            im:read: Read messages
14
            im:write: Write messages
15
            im:history: Access the message archive
16
            search:read: Search messages, files, and so on
17
            # etc.

隱含流程

implicit 流程定義用於從授權伺服器取得存取權杖的 authorizationUrl。以下是範例

1
components:
2
  securitySchemes:
3
    oAuth2Implicit:
4
      type: oauth2
5
      description: For more information, see https://developers.getbase.com/docs/rest/articles/oauth2/requests
6
      flows:
7
        implicit:
8
          authorizationUrl: https://api.getbase.com/oauth2/authorize
9
          scopes:
10
            read: Grant read-only access to all your data except for the account and user info
11
            write: Grant write-only access to all your data except for the account and user info
12
            profile: Grant read-only access to the account and user info only

資源擁有者密碼流程

password 流程使用 tokenUrl 和選用的 refreshUrl。以下是範例

1
components:
2
  securitySchemes:
3
    oAuth2Password:
4
      type: oauth2
5
      description: See https://developers.getbase.com/docs/rest/articles/oauth2/requests
6
      flows:
7
        password:
8
          tokenUrl: https://api.getbase.com/oauth2/token
9
          scopes:
10
            read: Grant read-only access to all your data except for the account and user info
11
            write: Grant write-only access to all your data except for the account and user info
12
            profile: Grant read-only access to the account and user info only

用戶端憑證流程

clientCredentials 流程使用 tokenUrl 和可選的 refreshUrl。以下是 Getty Images API 的範例

1
components:
2
  securitySchemes:
3
    oAuth2ClientCredentials:
4
      type: oauth2
5
      description: See http://developers.gettyimages.com/api/docs/v3/oauth2.html
6
      flows:
7
        clientCredentials:
8
          tokenUrl: https://api.gettyimages.com/oauth2/token/
9
          scopes: {} # Getty Images does not use scopes

多種流程

下方是支援多種流程的 OAuth 2.0 安全定義範例。用戶端可以使用任何這些流程。

1
components:
2
  securitySchemes:
3
    oAuth2:
4
      type: oauth2
5
      description: For more information, see https://developers.getbase.com/docs/rest/articles/oauth2/requests
6
      flows:
7
        implicit:
8
          authorizationUrl: https://api.getbase.com/oauth2/authorize
9
          scopes:
10
            read: Grant read-only access to all your data except for the account and user info
11
            write: Grant write-only access to all your data except for the account and user info
12
            profile: Grant read-only access to the account and user info only
13
        password:
14
          tokenUrl: https://api.getbase.com/oauth2/token
15
          scopes:
16
            read: Grant read-only access to all your data except for the account and user info
17
            write: Grant write-only access to all your data except for the account and user info
18
            profile: Grant read-only access to the account and user info only

常見問題

我是否還應該將 authorizationUrl 和 tokenUrl 定義為 API 操作？

authorizationUrl 不是 API 端點，而是一個需要使用者輸入的特殊網頁。因此，無法使用 OpenAPI 進行描述。不過，如果需要，您可以描述 tokenUrl。

authorizationUrl 和 tokenUrl 是否應該包含查詢字串參數，例如 grant_type、client_id 等？

OpenAPI 規範並未說明這一點，因此這取決於您和您使用的工具。

沒有找到您要找的內容嗎？向社群提問發現錯誤？請告訴我們