ベアラー認証

ベアラー認証（トークン認証とも呼ばれる）は、ベアラー・トークンと呼ばれるセキュリティ・トークンを伴うHTTP認証スキームです。「ベアラー認証」という名前は、「このトークンのベアラーにアクセスを許可する」と理解できます。ベアラー・トークンは、通常、ログイン要求に応じてサーバーによって生成される暗号化された文字列です。クライアントは、保護されたリソースへの要求を行う際に、このトークンをAuthorizationヘッダーで送信する必要があります。

1
Authorization: Bearer <token>

ベアラー認証スキームは、元々RFC 6750のOAuth 2.0の一部として作成されましたが、単独で使用されることもあります。Basic認証と同様に、ベアラー認証はHTTPS (SSL) 上でのみ使用する必要があります。

ベアラー認証の記述

OpenAPI 3.0では、ベアラー認証はtype: httpおよびscheme: bearerを持つセキュリティスキームです。まずcomponents/securitySchemesの下にセキュリティスキームを定義し、次にsecurityキーワードを使用して、このスキームを目的のスコープ（以下の例のようにグローバル、または特定の操作）に適用する必要があります。

1
openapi: 3.0.4
2
---
3
# 1) Define the security scheme type (HTTP bearer)
4
components:
5
  securitySchemes:
6
    bearerAuth: # arbitrary name for the security scheme
7
      type: http
8
      scheme: bearer
9
      bearerFormat: JWT # optional, arbitrary value for documentation purposes
10

11
# 2) Apply the security globally to all operations
12
security:
13
  - bearerAuth: [] # use the same name as above

オプションのbearerFormatは、ベアラー・トークンがどのようにフォーマットされるかを指定する任意の文字列です。ベアラー・トークンは通常サーバーによって生成されるため、bearerFormatは、クライアントへのヒントとして、主にドキュメント目的で使用されます。上記の例では「JWT」であり、JSON Web Tokenを意味します。bearerAuth: [] の角括弧[]には、API呼び出しに必要なセキュリティ・スコープのリストが含まれます。スコープはOAuth 2とOpenID Connectでのみ使用されるため、リストは空です。上記の例では、ベアラー認証はAPI全体にグローバルに適用されています。一部の操作にのみ適用する必要がある場合は、グローバルに行うのではなく、操作レベルでsecurityを追加します。

1
paths:
2
  /something:
3
    get:
4
      security:
5
        - bearerAuth: []

ベアラー認証は、複数の認証タイプの使用で説明されているように、他の認証方法と組み合わせることもできます。

401レスポンス

適切なベアラー・トークンを含まないリクエストに対して返される401「Unauthorized」レスポンスを定義することもできます。401レスポンスは複数の操作で使用されるため、グローバルなcomponents/responsesセクションで定義し、$refを介して他の場所から参照できます。

1
paths:
2
  /something:
3
    get:
4
      ...
5
      responses:
6
        '401':
7
          $ref: '#/components/responses/UnauthorizedError'
8
        ...
9
    post:
10
      ...
11
      responses:
12
        '401':
13
          $ref: '#/components/responses/UnauthorizedError'
14
        ...
15

16
components:
17
  responses:
18
    UnauthorizedError:
19
      description: Access token is missing or invalid

responsesの詳細については、レスポンスの記述を参照してください。

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