[ADP-54] OAuth2.0/OIDC for API

OAuth2.0 Overview

OAuth2.0 is an authorization framework that allows third-party applications to access a user's resources without exposing the user's credentials. It supports various authorization flows suitable for different application scenarios.

Authorization Types

1. Authorization Code Grant: Suitable for applications with a backend server, providing higher security.
   • Flow: The user is redirected to the authorization server, and after authorization, an authorization code is returned, which is then used to request an access token.
2. Implicit Grant: Suitable for single-page applications, with lower security. It is recommended to use the authorization code with PKCE instead.
   • Note: Sensitive information should not be exposed in the URL.
3. Client Credentials Grant: Used for machine-to-machine authentication.
   • Example: Used for API authentication between services.
4. Resource Owner Password Credentials: Used for trusted first-party clients and should be used with caution.
   • Recommendation: Use only in internal applications.

Guidelines

• SHOULD prioritize supporting OIDC (a superset of OAuth2.0).
• All API endpoints MUST consider using OAuth2.0 for security.
• SHOULD NOT use Basic Authentication due to its lower security.
• All external APIs MUST be built on HTTPS to protect data in transit.
• SHOULD define scopes for OAuth2.0, with the naming convention resource.permission.
• For M2M (machine-to-machine) authentication, SHOULD use the Client Credentials Grant.
• For trusted clients, SHOULD use the Authorization Code Grant.
• SHOULD consider implementing endpoint discovery as per RFC 8414.

Service Discovery Workflow

Client Requests Metadata

The client application requests the metadata endpoint of the authorization server to obtain relevant configuration. This request is typically an HTTP GET request to a fixed URL. For example:

GET https://authorization-server.com/.well-known/openid-configuration

Authorization Server Returns Metadata

The authorization server returns a JSON document containing various URLs and configuration information related to the OAuth 2.0 flows. Example metadata response:

{
  "issuer": "https://authorization-server.com",
  "authorization_endpoint": "https://authorization-server.com/auth",
  "token_endpoint": "https://authorization-server.com/token",
  "jwks_uri": "https://authorization-server.com/.well-known/jwks.json",
  "response_types_supported": ["code", "token"],
  "grant_types_supported": ["authorization_code", "client_credentials"],
  "id_token_signing_alg_values_supported": ["RS256"]
}

Error Specification

According to RFC6749, authorization failures should respond with the following object (note that since the specification itself defines the object content, this response does not apply to RFC9457 HTTP Problem).

1. HTTP Status Codes
   Depending on the type of error, different HTTP status codes should be returned to the client:

   • 400 Bad Request: The request is invalid, such as missing required parameters or incorrect parameter format.
   • 401 Unauthorized: The client failed to authenticate, typically used when client credentials are incorrect or the access_token is invalid.
   • 403 Forbidden: The client is authenticated but does not have permission to access the requested resource or perform the requested operation.
   • 500 Internal Server Error: An internal server error that causes authorization to fail.

2. Error Response Body
   The OAuth 2.0 specification requires the error response body to be in JSON format and must include the following fields:

   • error: A string describing the type of error. Defined error types include:
     • invalid_request: The request is missing a required parameter or is otherwise malformed.
     • invalid_client: Client authentication failed (e.g., invalid client_id or client_secret).
     • invalid_grant: The authorization code or refresh token is invalid, expired, or revoked.
     • unauthorized_client: The client is not authorized to use this authorization type.
     • unsupported_grant_type: The authorization type is not supported.
     • invalid_scope: The requested scope is invalid, unknown, or malformed.
   • error_description: (Optional) A more detailed description of the error to aid in debugging.
   • error_uri: (Optional) A URL pointing to a web page with more information about the error.

Example

Here is an example of an API request using OAuth2.0:

POST /token HTTP/1.1
Host: api.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTH_CODE&redirect_uri=REDIRECT_URI&client_id=CLIENT_ID&client_secret=CLIENT_SECRET

Error Handling Example

When a request fails, an appropriate error code and message should be returned:

{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid, expired, or revoked."
}

References

• OAuth 2.0 Specification
• RFC 6749: OAuth 2.0
• RFC 8414: OAuth 2.0 Authorization Server Metadata