Note: For reasons of simplification, some of the following requirements that refer to API apply to all technical implementation variants such as XML WebServices, GraphQL or REST APIs.

B.12.1 General

  1. APIs MUST not be exposed unless required.
  2. External APIs SHOULD only be made available using a hardened service or API gateway (see [A.5.5 Isolation of External Systems}(/Controls/SSDLC_Secure-Operation#a55-isolation-of-external-systems).
  3. APIs MUST be restrictively validated, preferably using OpenAPI Schema (see B.2 - Input Validation).
  4. APIs SHOULD implement restrictive limits based on business requirements (aka rate limiting, e.g. max. requests per client within a time interval)1.

B.12.2 Authentication

  1. The strength of the authentication mechanism used MUST be adequate to the protection needs.
  2. Shared secrets used for API authentication (e.g. API keys or OAuth 2.0 Client Secrets) MUST have the following characteristics:
  3. Authentication credentials MUST be unique for each service/system and environment (e.g. serviceX in dev, serviceX test, serviceX in production).

B.12.3 Access Tokens

  1. Access to APIs with risk class >= [HIGH] SHOULD be granted using Access Tokens (OAuth 2.0 or SAML).
  2. The following requirements MUST apply to access tokens:
    • Short-lived (minutes or hours)
    • Implemented according to B.10.5 Tokens / Keys
    • Restrictive scope & audience
    • Transmitted only via HTTPS/TLS
    • Issued by a trusted and hardened access server (e.g. OIDC Identity Server or OAuth 2.0 Authorization Server)
    • created and validated using mature frameworks.
    • signed (preferably using public key cryptography)2
  3. If the token is encoded as a JSON Web Token (JWT), the encryption method MUST be verified2.

B.12.4 OAuth 2.0/OICD Requirements

  1. For user authentication (3-legged):
    • Authorization Code Grant with PKCE (or alternative authorization code binding technique, e.g. “state” binding or OICD Nounces) for both public clients (e.g. single-page applications (SPAs)3 SHOULD be used for both public and confidential clients (e.g. server-side web apps).4
    • For CSRF protection, Authorization Code Grant Flows MUST either use the “state” parameter, PKCE, or “OICD Nounces”
    • Clients MUST register (and be validated using) full redirect URI as described in RFC 6819 Section 5.2.3.5 (no pattern matching).
    • Refresh tokens MUST be secured according to B.11 - Protection of Secrets
  2. Service-to-service access SHOULD be protected using Client Credential Grants.
  3. HTTPS MUST be used for all communication.

See also requirements B.12.3 Access Tokens.

B.12.5 Frontend APIs

APIs that are used as a backend for client-side frontend (e.g. SPAs):

  1. MUST implement the same security requirements for access to external resources as the corresponding UI (authentication, validation, etc.)
  2. MUST not contain script code (e.g. JavaScript) that is directly executable
  3. MUST contain CSRF protection if working in user context (see B.7 - Secure Session Management)

B.12.6 Cross-Domain Access

  1. Cross-domain requests MUST be performed using secure mechanisms such as Cross-Origin Resource Sharing (CORS) and a restrictive policy (e.g. restricted so certain hosts or domains or with credential submission deactivated).
  2. The origin header of cross-domain requests MUST be authorized on the server side.

B.12.7 WebSockets

WebSockets MUST transfer all confidential data with wss:// schema and an additional server-side authorization of the source origin header.

  1. This control aims to prevent denial-of-service (DoS) conditions, which can occur both deliberately and accidentally, such as those triggered by a client malfunction. ↩

  2. See B.10 - Data Security for requirements about allowed algorithm and ciphers used here. ↩ ↩2

  3. See https://tools.ietf.org/html/draft-ietf-oauth-browser-based-apps-00 ↩

  4. See https://tools.ietf.org/html/draft-ietf-oauth-security-topics-14 ↩