Cookie Authentication

Cookie authentication uses HTTP cookies to authenticate client requests and maintain session information. It works as follows:

1. The client sends a login request to the server.

2. On the successful login, the server response includes the Set-Cookie header that contains the cookie name, value, expiry time and some other info. Here is an example that sets the cookie named JSESSIONID:

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

3. The client needs to send this cookie in the Cookie header in all subsequent requests to the server.

   Cookie: JSESSIONID=abcde12345

4. On the logout operation, the server sends back the Set-Cookie header that causes the cookie to expire.

Note: Cookie authentication is vulnerable to Cross-Site Request Forgeries (CSRF) attacks, so it should be used together with other security measures, such as CSRF tokens.

Note for Swagger UI and Swagger Editor users: Cookie authentication is currently not supported for "try it out" requests due to browser security restrictions.

Describing Cookie Authentication

In OpenAPI 3.0 terms, cookie authentication is an API key that is sent in: cookie. For example, authentication via a cookie named JSESSIONID is defined as follows:

openapi: 3.0.0
...
# 1) Define the cookie name
components:
  securitySchemes:
    cookieAuth:         # arbitrary name for the security scheme; will be used in the "security" key later
      type: apiKey
      in: cookie
      name: JSESSIONID  # cookie name
# 2) Apply cookie auth globally to all operations
security:
  - cookieAuth: []

In this example, cookie authentication is applied globally to the whole API using the security key at the root level of the specification. If cookies are required for just a subset of operations, apply security on the operation level instead of doing it globally:

paths:
  /users:
    get:
      security:
        - cookieAuth: []
      description: Returns a list of users.
      responses: 
        '200':
          description: OK

Cookie authentication can be combined with other authentication methods as explained in Using Multiple Authentication Types.

Describing the Set-Cookie Header

You may also want to document that your login operation returns the cookie in the Set-Cookie header. You can include this information in the description, and also define the Set-Cookie header in the response headers, like so:

paths:
  /login:
    post:
      summary: Logs in and returns the authentication  cookie
      requestBody:
        required: true
        description: A JSON object containing the login and password.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      security: []    # no authentication
      responses:
        '200':
          description: >
            Successfully authenticated.
            The session ID is returned in a cookie named `JSESSIONID`. You need to include this cookie in subsequent requests.
          headers: 
            Set-Cookie:
              schema: 
                type: string
                example: JSESSIONID=abcde12345; Path=/; HttpOnly

Note that the Set-Cookie header and securitySchemes are not connected in any way, and the Set-Header definition is for documentation purposes only.