[ADP-123] Authorization

The Authorization header allows APIs to identify the user or system making the request and determine whether they have permission to access the requested resource.

Overview

The Authorization header is used to provide credentials for authenticating a user agent with a server. Various authentication schemes can be used, such as Basic, Bearer, and custom schemes. The most common approach in modern APIs is the Bearer token, often used in conjunction with OAuth 2.0.

Common Authentication Schemes

1. Basic Authentication:

   • Credentials are encoded using Base64.
   • Not recommended for production due to security concerns unless used with HTTPS.

   Example:

   Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

2. Bearer Token:

   • A token issued by an authorization server, typically used with OAuth 2.0.
   • This token is included in the Authorization header for each request to protected resources.

   Example:

   Authorization: Bearer <token>

3. Custom Schemes:

   • Depending on specific security requirements, custom schemes can be defined. See ADP-363 for more details.

   Example:

   Authorization: CustomScheme <credentials>

Guidance

• SHOULD favor the bearer scheme.
  • If planning to use a custom scheme, document it thoroughly.
• MUST use HTTPS to ensure the security of credentials transmitted via the Authorization header.
• SHOULD implement mechanisms for token expiry and renewal to enhance security. Short-lived tokens with refresh tokens are recommended.
• MAY define and enforce scopes and permissions to control access to various parts of your API.
• SHOULD provide clear error messages for authentication and authorization failures, using standard HTTP status codes like 401 (Unauthorized) and 403 (Forbidden).

OpenAPI Specification Example

Below is an example of how to specify the Authorization header in an OpenAPI document, using the Bearer token authentication scheme and incorporating HTTP Problem (RFC 9457) for error handling.

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
  description: An example API demonstrating the use of the Authorization header with HTTP Problem (RFC 9457) for error handling.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: A URI reference identifying the problem type.
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          description: The HTTP status code.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          format: uri
          description: A URI reference identifying the specific occurrence of the problem.
security:
  - BearerAuth: []
paths:
  /users:
    get:
      summary: Retrieve a list of users
      security:
        - BearerAuth: []
      responses:
        '200':
          description: A JSON array of user objects
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 1
                    name:
                      type: string
                      example: John Doe
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /users/{id}:
    get:
      summary: Retrieve a user by ID
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the user to retrieve
          schema:
            type: integer
      security:
        - BearerAuth: []
      responses:
        '200':
          description: A user object
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1
                  name:
                    type: string
                    example: John Doe
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'

TIP

💡 Security can be applied globally or partially to specific operations.

Reference

• MDN: Authorization
• Bearer Authentication - Swagger
• RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage
• RFC 7235 - Hypertext Transfer Protocol (HTTP/1.1): Authentication