コンテンツにスキップ

認証

OpenAPI では、認証および認可スキームをセキュリティスキームと呼びます。OpenAPI 3.0 では、以下のセキュリティスキームで保護された API を記述できます。

特定のセキュリティタイプのガイドについては、上記のリンクをたどるか、引き続き読んで一般的なセキュリティの記述方法を学んでください。

OpenAPI 2.0 からの変更点

以前に OpenAPI 2.0 を使用したことがある場合、OpenAPI 3.0 を始めるのに役立つ変更点の概要を以下に示します。

  • securityDefinitions は securitySchemes に名前が変更され、components 内に移動されました。
  • type: basic は type: http と scheme: basic に置き換えられました。
  • 新しい type: http は、Basic、Bearer、その他を含むすべての HTTP セキュリティスキームの傘型であり、scheme キーワードはスキームタイプを示します。
  • API キーは in: cookie で送信できるようになりました。
  • OpenID Connect Discovery (type: openIdConnect) のサポートを追加しました。
  • OAuth 2 セキュリティスキームは、複数の flows を定義できるようになりました。
  • OAuth 2 フローは、OAuth 2 仕様に合わせて名前が変更されました。accessCode は authorizationCode に、application は clientCredentials になりました。

セキュリティの記述

セキュリティは securitySchemes と security キーワードを使用して記述されます。securitySchemes を使用して API がサポートするすべてのセキュリティスキームを定義し、次に security を使用して特定のスキームを API 全体または個々の操作に適用します。

ステップ 1. securitySchemes の定義

API で使用されるすべてのセキュリティスキームは、グローバルの components/securitySchemes セクションで定義する必要があります。このセクションには、名前付きセキュリティスキームのリストが含まれており、各スキームは次のtypeを持つことができます。

セキュリティスキームのその他の必須プロパティは、type によって異なります。次の例は、さまざまなセキュリティスキームがどのように定義されるかを示しています。BasicAuth、BearerAuth などの名前は、仕様の他の場所からこれらの定義を参照するために使用される任意の名前です。

1
components:
2
  securitySchemes:
3
    BasicAuth:
4
      type: http
5
      scheme: basic
6


7
    BearerAuth:
8
      type: http
9
      scheme: bearer
10


11
    ApiKeyAuth:
12
      type: apiKey
13
      in: header
14
      name: X-API-Key
15


16
    OpenID:
17
      type: openIdConnect
18
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
19


20
    OAuth2:
21
      type: oauth2
22
      flows:
23
        authorizationCode:
24
          authorizationUrl: https://example.com/oauth/authorize
25
          tokenUrl: https://example.com/oauth/token
26
          scopes:
27
            read: Grants read access
28
            write: Grants write access
29
            admin: Grants access to admin operations

ステップ 2. セキュリティの適用

securitySchemes セクションでセキュリティスキームを定義したら、ルートレベルまたは操作レベルにsecurityセクションを追加することで、API 全体または個々の操作にそれらを適用できます。ルートレベルで使用する場合、securityは、操作レベルで上書きされない限り、指定されたセキュリティスキームをすべての API 操作にグローバルに適用します。次の例では、API 呼び出しは API キーまたは OAuth 2 のいずれかを使用して認証できます。ApiKeyAuth と OAuth2 の名前は、以前にsecuritySchemesで定義されたスキームを参照しています。

1
security:
2
  - ApiKeyAuth: []
3
  - OAuth2:
4
      - read
5
      - write
6
# The syntax is:
7
# - scheme name:
8
#     - scope 1
9
#     - scope 2

各スキームについて、API 呼び出しに必要なセキュリティスコープのリストを指定します（以下の参照）。スコープは OAuth 2 と OpenID Connect Discovery のみに使用されます。他のセキュリティスキームは空の配列 [] を使用します。グローバルの security は、個々の操作で異なる認証タイプ、異なる OAuth/OpenID スコープ、またはまったく認証なしを使用するように上書きできます。

1
paths:
2
  /billing_info:
3
    get:
4
      summary: Gets the account billing info
5
      security:
6
        - OAuth2: [admin] # Use OAuth with a different scope
7
      responses:
8
        "200":
9
          description: OK
10
        "401":
11
          description: Not authenticated
12
        "403":
13
          description: Access token does not have the required scope
14


15
  /ping:
16
    get:
17
      summary: Checks if the server is running
18
      security: [] # No security
19
      responses:
20
        "200":
21
          description: Server is up and running
22
        default:
23
          description: Something is wrong

スコープ

OAuth 2 と OpenID Connect は、さまざまなユーザーリソースへのアクセス許可を制御するためにスコープを使用します。たとえば、ペットストアのスコープには、read_pets、write_pets、read_orders、write_orders、admin が含まれる場合があります。security を適用するとき、OAuth 2 と OpenID Connect に対応するエントリは、特定の操作に必要なスコープのリスト（security が操作レベルで使用されている場合）またはすべての API 呼び出し（security がルートレベルで使用されている場合）を指定する必要があります。

1
security:
2
  - OAuth2:
3
      - scope1
4
      - scope2
5
  - OpenId:
6
      - scopeA
7
      - scopeB
8
  - BasicAuth: []
  • OAuth 2 の場合、security で使用されるスコープは、事前に securitySchemes で定義されている必要があります。
  • OpenID Connect Discovery の場合、可能なスコープは openIdConnectUrl で指定されたディスカバリエンドポイントにリストされています。
  • その他のスキーム (Basic、Bearer、API キーなど) はスコープを使用しないため、それらの security エントリは代わりに空の配列 [] を指定します。

通常、読み取り、書き込み、管理者など、異なる操作には異なるスコープが必要です。この場合、グローバルに行うのではなく、特定の操作にスコープ付きの security を適用する必要があります。

1
# Instead of this:
2
# security:
3
#   - OAuth2:
4
#       - read
5
#       - write
6


7
# Do this:
8
paths:
9
  /users:
10
    get:
11
      summary: Get a list of users
12
      security:
13
        - OAuth2: [read]     # <------
14
      ...
15


16
    post:
17
      summary: Add a user
18
      security:
19
        - OAuth2: [write]    # <------
20
      ...

複数の認証タイプを使用する

一部の REST API は複数の認証タイプをサポートしています。security セクションでは、論理 OR と AND を使用してセキュリティ要件を組み合わせて、目的の結果を達成できます。security は次のロジックを使用します。

1
security: # A OR B
2
  - A
3
  - B
1
security: # A AND B
2
  - A
3
    B
1
security: # (A AND B) OR (C AND D)
2
  - A
3
    B
4
  - C
5
    D

つまり、security はハッシュマップの配列であり、各ハッシュマップには 1 つ以上の名前付きセキュリティスキームが含まれています。ハッシュマップ内の項目は論理 AND を使用して結合され、配列の項目は論理 OR を使用して結合されます。OR を介して結合されたセキュリティスキームは代替案であり、与えられたコンテキストでいずれかを使用できます。AND を介して結合されたセキュリティスキームは、同じリクエストで同時に使用する必要があります。ここでは、Basic 認証または API キーのいずれかを使用できます。

1
security:
2
  - basicAuth: []
3
  - apiKey: []

ここでは、API はリクエストに API キーのペアを含める必要があります。

1
security:
2
  - apiKey1: []
3
    apiKey2: []

ここでは、OAuth 2 または API キーのペアのいずれかを使用できます。

1
security:
2
  - oauth2: [scope1, scope2]
3
  - apiKey1: []
4
    apiKey2: []

参照

セキュリティスキームオブジェクト

セキュリティ要件オブジェクト

お探しのものが見つかりませんでしたか？ コミュニティに質問する
間違いを見つけましたか？ お知らせください