クッキー認証

Cookie認証は、HTTP Cookieを使用してクライアントのリクエストを認証し、セッション情報を維持します。その仕組みは以下のとおりです。

クライアントはサーバーにログインリクエストを送信します。
ログインが成功すると、サーバーの応答にはCookie名、値、有効期限、その他の情報を含むSet-Cookieヘッダーが含まれます。以下はJSESSIONIDという名前のCookieを設定する例です。

1
Set-Cookie: JSESSIONID=abcde12345; Path=/; HttpOnly

クライアントは、その後のすべてのサーバーへのリクエストで、このCookieをCookieヘッダーに含めて送信する必要があります。

1
Cookie: JSESSIONID=abcde12345

ログアウト操作では、サーバーはCookieを期限切れにするSet-Cookieヘッダーを返します。

注: Cookie認証はクロスサイトリクエストフォージェリ (CSRF) 攻撃に対して脆弱であるため、CSRFトークンなどの他のセキュリティ対策と併用する必要があります。

Swagger UIおよびSwagger Editorユーザーへの注意: ブラウザのセキュリティ制限により、「試す」リクエストではCookie認証は現在サポートされていません。この問題については、詳細をご覧ください。SwaggerHubにはこの制限はありません。

OpenAPI 3.0の用語では、Cookie認証はin: cookieで送信されるAPIキーです。JSESSIONIDという名前のCookieによる認証は、次のように定義されます。

1
openapi: 3.0.4
2
---
3
# 1) Define the cookie name
4
components:
5
  securitySchemes:
6
    cookieAuth: # arbitrary name for the security scheme; will be used in the "security" key later
7
      type: apiKey
8
      in: cookie
9
      name: JSESSIONID # cookie name
10

11
# 2) Apply cookie auth globally to all operations
12
security:
13
  - cookieAuth: []

この例では、仕様のルートレベルのsecurityキーを使用して、Cookie認証がAPI全体にグローバルに適用されます。Cookieが一部の操作にのみ必要な場合は、グローバルに適用するのではなく、操作レベルでsecurityを適用します。

1
paths:
2
  /users:
3
    get:
4
      security:
5
        - cookieAuth: []
6
      description: Returns a list of users.
7
      responses:
8
        "200":
9
          description: OK

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

ログイン操作がSet-CookieヘッダーでCookieを返すことを文書化したい場合もあるでしょう。この情報をdescriptionに含め、応答のheadersにSet-Cookieヘッダーを定義することができます。以下に例を示します。

1
paths:
2
  /login:
3
    post:
4
      summary: Logs in and returns the authentication  cookie
5
      requestBody:
6
        required: true
7
        description: A JSON object containing the login and password.
8
        content:
9
          application/json:
10
            schema:
11
              $ref: "#/components/schemas/LoginRequest"
12
      security: [] # no authentication
13
      responses:
14
        "200":
15
          description: >
16
            Successfully authenticated.
17
            The session ID is returned in a cookie named `JSESSIONID`. You need to include this cookie in subsequent requests.
18
          headers:
19
            Set-Cookie:
20
              schema:
21
                type: string
22
                example: JSESSIONID=abcde12345; Path=/; HttpOnly

Set-CookieヘッダーとsecuritySchemesはどのような方法でも接続されておらず、Set-Headerの定義はドキュメント作成のみを目的としていることに注意してください。

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

クッキー認証

Cookie認証の記述

Set-Cookieヘッダーの記述