[ADP-47] API Authentication and Authorization

Guidance

• Usernames, passwords, session tokens, API keys, and sensitive information MUST NOT appear in the URL, as this can be captured in web server logs, which makes them intrinsically valuable.

• Every API endpoint MUST use OAuth2.0 or JWT-based authentication for security, choosing the appropriate method based on your use case:

  • When to use OAuth2.0:
    • Handling authentication for third-party applications
    • Implementing delegated authorization, allowing users to authorize third-party applications to access their resources
    • Supporting multiple authentication flows, such as authorization code flow, implicit flow, and client flow
    • For more about OAuth2.0 specifications and practices, refer to ADP-54
  • When to use JWT:
    • Building stateless authentication for your own system without storing session information on the server
    • Including claims or user information in the token for use during the verification process
  • For details on OAuth2.0 authorization types, refer to ADP-54.

• Api-Key authentication MAY be considered, typically passed through the X-Api-Key header.

  • Note that Api-Keys should be rotated regularly to enhance security.

• Basic authentication SHOULD NOT be used,

  • Basic authentication is less secure as it transmits user credentials in an easily decodable format; avoid using it to protect API endpoints,

  • Do not do this:

    ```http
    GET /protected/resource HTTP/1.1
    Host: api.example.com
    Authorization: Basic <base64_encoded_credentials>
    ```
    

• All external APIs MUST be built on HTTPS,

  • All external API communications MUST use HTTPS encryption to protect data in transit from eavesdropping and man-in-the-middle attacks, ensuring proper configuration and maintenance of SSL/TLS certificates,

  • Exceptions: Internal APIs on secure internal networks MAY run without HTTPS if the following conditions are met:

    • The network is completely isolated from external access
    • All internal traffic is monitored and protected
    • The risk of internal threats is deemed acceptable

  • Note: Even for internal APIs, HTTPS is still recommended whenever possible for consistency and additional security,

  • Example: (All external API URLs should start with https://)

    GET /protected/resource HTTP/1.1
    Host: api.example.com

• Role-Based Access Control (RBAC) SHOULD be implemented,

  • Implement RBAC to effectively manage user permissions, defining roles and assigning permissions based on the principle of least privilege,
  • Best practices for RBAC implementation:
    • Define fine-grained permissions for specific actions and resources
    • Create roles that group related permissions
    • Assign users to roles rather than assigning permissions directly
    • Regularly review and audit role assignments
    • Implement a hierarchical role structure if needed for complex systems
  • Example:

    • Define fine-grained permissions:

      {
        "permissions": [
          "user:read",
          "user:create",
          "user:update",
          "user:delete",
          "report:view",
          "report:generate"
        ]
      }

    • Create roles with specific permissions:

      {
        "roles": [
          {
            "name": "admin",
            "permissions": ["user:read", "user:create", "user:update", "user:delete", "report:view", "report:generate"]
          },
          {
            "name": "manager",
            "permissions": ["user:read", "report:view", "report:generate"]
          },
          {
            "name": "user",
            "permissions": ["user:read", "report:view"]
          }
        ]
      }

    • Assign roles to users:

      {
        "users": [
          {
            "username": "alice",
            "roles": ["admin"]
          },
          {
            "username": "bob",
            "roles": ["manager"]
          },
          {
            "username": "charlie",
            "roles": ["user"]
          }
        ]
      }

• When RBAC cannot meet the needs between specific resources and specific users, ABAC MAY be needed.

Reference

• ADIDAS API: Security

Changelog

• 2024.11.04: Add security concern