認証

Swagger 2.0 では、API に対して以下の認証タイプを定義できます。

基本認証
API キー (ヘッダーまたはクエリ文字列パラメーターとして)
OAuth 2 の一般的なフロー (承認コード、Implicit、リソースオーナーパスワード認証情報、クライアント認証情報)

これらの認証タイプに固有の例については上記のリンクをたどるか、一般的な認証の記述方法については読み進めてください。

認証は、securityDefinitions と security キーワードを使用して記述されます。securityDefinitions を使用して API がサポートするすべての認証タイプを定義し、次に security を使用して特定の認証タイプを API 全体または個々の操作に適用します。

securityDefinitions セクションは、API がサポートするすべてのセキュリティスキーム (認証タイプ) を定義するために使用されます。これは、任意の名前をセキュリティスキーム定義にマッピングする名前->定義マップです。ここでは、API は BasicAuth、ApiKeyAuth、OAuth2 という 3 つのセキュリティスキームをサポートしており、これらの名前は他の場所からこれらのセキュリティスキームを参照するために使用されます。

1
securityDefinitions:
2
  BasicAuth:
3
    type: basic
4
  ApiKeyAuth:
5
    type: apiKey
6
    in: header
7
    name: X-API-Key
8
  OAuth2:
9
    type: oauth2
10
    flow: accessCode
11
    authorizationUrl: https://example.com/oauth/authorize
12
    tokenUrl: https://example.com/oauth/token
13
    scopes:
14
      read: Grants read access
15
      write: Grants write access
16
      admin: Grants read and write access to administrative information

各セキュリティスキームは type で指定できます。

基本認証の場合は basic
API キーの場合は apiKey
OAuth 2 の場合は oauth2

その他の必須プロパティはセキュリティタイプによって異なります。詳細については、Swagger 仕様または基本認証およびAPI キーの例をご覧ください。

securityDefinitions でセキュリティスキームを定義した後、ルートレベルまたは操作レベルでそれぞれ security セクションを追加することで、それらを API 全体または個々の操作に適用できます。ルートレベルで使用する場合、security は、操作レベルで上書きされない限り、指定されたセキュリティスキームをすべての API 操作にグローバルに適用します。

次の例では、API 呼び出しは API キーまたは OAuth 2 のいずれかを使用して認証できます。ApiKeyAuth および OAuth2 の名前は、以前に securityDefinitions で定義されたセキュリティスキームを参照します。

1
security:
2
  - ApiKeyAuth: []
3
  - OAuth2: [read, write]

グローバルな security は、個々の操作で異なる認証タイプ、異なる OAuth 2 スコープ、またはまったく認証なしを使用するように上書きできます。

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

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

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

1
security:    # A OR B
2
  - A
3
  - B
4

5
security:    # A AND B
6
  - A
7
    B
8

9
security:    # (A AND B) OR (C AND D)
10
  - A
11
    B
12
  - C
13
    D

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

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

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

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

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

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

FAQ

「securitySchemeName: [ ]」の [ ] は何を意味しますか?

[] は空の配列の YAML/JSON 構文です。Swagger 仕様では、security 配列内の項目が次のように必要なスコープのリストを指定する必要があります。

1
security:
2
  - securityA: [scopeA1, scopeA2]
3
  - securityB: [scopeB1, scopeB2]

スコープは OAuth 2 でのみ使用されるため、基本認証と API キーの security 項目では代わりに空の配列を使用します。

1
security:
2
  - oauth2: [scope1, scope2]
3
  - BasicAuth: []
4
  - ApiKeyAuth: []

参照

securityDefinitions

security

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