API Bites — Tactics to Secure Sensitive APIs

Security By Design

If you have read any related articles by this author, you may find the below graphic familiar. This is because an appreciation of data sensitivity and applicable security controls really must be embedded with the domain model in order to ensure robust API security.

Security by Design: Foundational to API security

Ideally, data is classified and security/regulatory controls identified during the domain modelling phase. Fine-grained data handling and security controls are implemented accordingly by the business service responsible for the data. Corresponding API specification security schemes are derived from matching security controls captured by the domain model against templated enterprise security patterns.

Underpinning the implementation of API security controls at the gateway will be enterprise tactical guidance and an Integrated Security Framework.

Understand Applicable Security Controls

There will often be one or more (likely overlapping) regulatory controls applicable to data managed by a business service. These controls should be defined by an enterprise Information Rights Management (IRM) governing body — often Cyber Security. Controls are likely to cover Integrity and confidentiality, storage/persistence, limitation and minimization, and data sovereignty. Among information processing and security controls that may be applicable to personal and sensitive data (non-exhaustive) are: GDPR (Europe), ISO 27001, 27701. ISO 27017, 27018, PCI DSS, PSD2, AICPA Trust Services Principles and Criteria, NIST, AICPA Trust Services Criteria.

While guiding patterns and tactics for data handling may be provided by enterprise architecture, it is imperative that the development team are familiar with applicable caveats and controls. Below is brief, illustrative overview of common data handling concepts and constraints.

PII

Personally Identifiable Information (PII) is information that can potentially identify an individual, either on its own or when combined with other data. Strict definitions and mandatory controls may vary across jurisdictions. In Europe, personal data processing principles are defined by the GDPR.

Purpose Limitation and Data Minimization

Data must be processed for the purposes specified upon collection. The minimum of data necessary for the purposes specified should be collected and processed. PII may be stored only as long as necessary for the specified purpose.

Data Sovereignty

Data sovereignty is the concept that data is subject to the laws and regulation of the country in which it is collected and processed, and the imperative that data must remain within the borders of the originating jurisdiction.

Data Classification

In some jurisdictions and data sharing frameworks, sensitive or classified request or response document data must be accompanied by HTTP headers identifying the sensitivity/security classification. Classification headers can drive defensive behaviors, such as controlled logging. In Australia this requirement is articulated in the National API Design Standards.

Controlling Access to Sensitive APIs

User Access — API gateways leverage mandatory API resource access tokens to ensure that authenticated end-users are authorized to access an API — however this is a low-granularity access decision that asks only “is this a registered user with a valid API use-case?”. The access token (and the OIDC identity token behind it) is intended to provide the business service with the means to ask the high-granularity access question “Does this particular user have a right to see the requested data?”.

Client Access — Most API Management platforms will provide a workflow for client API subscription approval. Consider applying this workflow when dealing with sensitive data to approve client application access to APIs.

OAuth2/OIDC Authorization

When dealing with sensitive data, an OAuth2/OIDC authorization requirement should be a given. In an OAS 3 API specification document, an OAuth2 token requirement and scopes are described by security schemes:

securitySchemes:
  OpenID:
    type: openIdConnect
    openIdConnectUrl: https://example.com/.well-known/openid-configuration
  OAuth2:            # <------
    type: oauth2
    flows:
      clientCredentials:
        tokenUrl: https://example.com/oauth/token
        scopes:
          read: Grants read access

and applied at an operation granularity:

paths:
  /users:
    get:
      summary: Get a list of users
      security:
        - OAuth2: [read]     # <------
        - OpenID: [read]     # <------
      ...

API scope definition should follow a predictable and consistent pattern within an enterprise. Expect enterprise API development standards and API security patterns to cover this topic.

Zero Trust, API scopes and authorization flows are discussed in more detail here.

API Abstraction

There must be a level of abstraction between a business API and business service implementation. The surest way to avoid the danger of exposing implementation details is to independently derive the resource API specification from a common, authoritative domain model (Model Driven Design), OR to take an API-first approach to development.

Building an API specification based on an existing service implementation is rarely a good idea. When ‘retro-fitting’ an existing service with APIs — go back to the domain model, or capture and validate the implicit domain model together with business and technical domain stakeholders. Derive an abstracted domain-aligned, secure, composable REST model and host the API as an anti-corruption layer if required.

For reasons of security and confidentiality, a resource identifier should be non-sequential and un-guessable, providing maximum abstraction from Personally Identifiable Information, primary keys, and time or order of creation. The resource identifier must be immutable. Consider employing a Universally Unique Identifier (UUID). E.g.

/v1/customers/d0ecdaab-d2b4-443b-818a-565314ec09a7

At a minimum:

• NEVER directly expose the internal database table structure in an API.
• NEVER expose and share internal system identifiers (such as a database ID). Use a fit-for-purpose, decoupled, non-sequential and un-guessable resource identifier.

Error Handling

Descriptive JSON errors can be enormously helpful during development and testing, and in System Integration environments. However in production environments, it is important to ensure that technology or implementation specific error messages are NEVER directly exposed.

At a minimum:

• APIs must mask system related errors behind standard HTTP status responses and abstract, enterprise consistent error messages. System level information is never exposed in error responses.
• APIs must never pass technical details (e.g. call stacks) to the client. This is the purpose of trace headers, enterprise logging and analytics.

Secret and Certificate Management

Never store secrets, keys or certificates in your repository in any form — these must be stored and encrypted in a secrets manager. When secrets are injected from a secrets manager into a CI-CD pipeline, they must not be logged.

Logging

Application and Trace Logging

Content (payload) classified as sensitive or otherwise restricted should not be logged by gateways or business services, unless over secure channels and to platforms approved for the retention of data to the appropriate classification.

• Ensure logged data is masked and sanitized to prevent exposure of credentials, tokens, Personally Identifiable Information or other sensitive business information.
• Implement an allowed list of characters to mitigate against log injection attacks. Test potential vulnerabilities.
• Understand and follow enterprise trace participation requirements

An overview of W3C Trace Context participation is provided here

Audit Logs

When a security event occurs, or an authorization decision is made, it must be logged to an enterprise security incident and event management platform (SIEM) where incidents, patterns and trends can be analyzed and acted upon. It is imperative to define the right granularity of logging and to ensure alerts and notifications are appropriately escalated.

• API developers and security teams will need to work together on event schemas and taxonomy, escalation and threat protection.
• Iterate on and refine the logging solution to achieve appropriate log/alert thresholds and content. Capture ALL authentication and authorization events.
• Logs should anticipate security related events, and should be tested during routine DevOps security testing. Novel security events in any environment should trigger analysis and refinement of triggers, logs, alerts and actions. Trace logs are invaluable in this respect.

Transport Security

Developers of APIs handing classified or sensitive data should carefully consider each of the following transport security measures:

• Transport of sensitive data must occur over HTTPS —ideally, restrict to TLS versions ’n’ or ‘n-1’ (e.g. ‘TLS 1.3 or 1.2’), and do not redirect HTTP to HTTPS.
• Unused HTTP methods should be explicitly disabled.
• Ensure that back-end APIs are locked down with mutual authentication between the API Gateway and resource server(s).

As far as it is under your control, consider the following API gateway measures:

• A minimum hashing algorithm requirement for certificates, such as SHA512 with a minimum key length of 2048.
• A Requirement for clients of external-facing APIs to present a digital certificate that has been signed by a recognized Certificate Authority (CA).

When handling highly sensitive data, the following controls might be considered:

• Mutual authentication between the client and the API Gateway
• Payload signing for integrity and verification
• Payload encryption

Data Confidentiality, Integrity and Non-Repudiation

Occasionally, regulatory controls or controls-by-agreement will dictate special handling of data to ensure Data Confidentiality, Integrity and/or Non-Repudiation.

There are a number of technologies that might be applied, and often various methods of implementation. A coherent and consistent enterprise approach can mitigate a potentially considerable maintenance burden. The following Signed and Encrypted payload tactics are offered as exemplars, however the right technologies and tactics will depend on a number of factors including tech stack, current practice and expertise, and specific data handling requirements.

Signed Payload

An enterprise API Gateway can be configured to support the Javascript Object Signing and Encryption (JOSE) framework and JSON Web Signature (JWS) validation.

To support data integrity and Non-Repudiation above and beyond TLS, the business service and/or the API Gateway can provide JWS Detached Content payload signing. The JWS Detached Content mechanism controls header length, allows delegation of verification to an API gateway, and may be applied to one class of clients (e.g. external) and not others (e.g. internal).

OpenAPI support for describing a signature requirement is limited. When a JWS signature is required, a mandatory ‘x-jws-signature’ header and an API description must clearly describe the requirement in the API specification.

JWS compact serialization is discussed in more detail here

Encrypted Payload

Content encryption adds little value over a direct call to an API Gateway over an encrypted HTTPS connection. The primary use-case of content encryption is to ensure confidentiality of data from end-to-end, through intermediate platforms such as API Gateways that may otherwise allow for the capture, logging or inspection of data in transit.

There will occasionally be a requirement to encrypt payload content to protect the confidentiality of protected data exchanged with one or more trusted external clients. Be aware that content encryption may have ramifications for performance, audit, message tracking, data retention and troubleshooting.

Consider using JSON Web Encryption (JWE) JSON Serialization (JWE-JS) Syntax to encrypt JSON content. JWE-JS encrypted content may be fully described in the API specification, and documents with a content-type of ‘application/jose+json’ may be validated as properly formatted JWE-JS encrypted data by the API gateway.

JSON Web Encryption-JSON Serialization is discussed in more detail here

Ruthlessly Validate the API specification and Test the Security of the API

‘Code-first’ API publishing automation can improve API security. DevOps pipelines can apply Policy-as-Code controls, enforce mandatory standards with specification document linting, and validate security schemes.

Pipeline security tests should be built and maintained against applicable security controls. These measures serve to ensure robust, secure APIs of a consistent quality, provide early feedback on document and configuration issues, and minimize blocking engagements with a centralized API management team.

When the API specification is managed outside of DevOps, ensure that API specifications are peer-reviewed, and that robust API security testing is incorporated into post-deployment/environment regression testing. Ensure that tests are maintained in alignment with applicable security controls.

API security testing concepts are discussed here: API Bites — API Testing

Run-Time Gateway Validation

Input validation is performed at the API gateway to ensure only properly formed data is received by the resource server. Input validation may be a default gateway security posture, or it may require configuration against an API in an API management portal or deployment config.

Validation may include the following — in order of increasing granularity:

• An appropriate request size limit should be defined. Requests exceeding the limit should be rejected.
• Business API validation should be applied by default. The API gateway should only forward on to business services API requests that conform to the API specification.
• An API specification should define data types and formats. Field lengths and String regular expression constraints should be considered.

Make use of Gateway Security Features

Make use of the Security policy features provided by API Gateway platforms to augment back-end API security and provide defense-in-depth.

Rate Limiting : Apply rate limiting and throttling policies. Appropriate alerts should be implemented to provide informative and actionable error information when thresholds are approaching or have been exceeded.

API Subscription Approval : Consider applying a client subscription approval workflow when dealing with sensitive data. When in place, the API cannot be invoked by individual client systems without subscription approval from the API owner or a delegate.

OAuth2/OIDC Requirement : This requirement should ideally be driven from the API specification, however if the API publishing process is ‘manual’, the requirement may need to be manually applied during API configuration. Ensure that routine security testing is in place to verify the requirement in all environments.

Input Validation : A default API Gateway request size limit, JSON threat protection and default request validation against the API specification are recommended. This will ordinarily be an enterprise platform configuration decision.

In Summary

A thorough understanding of data sensitivity and applicable security controls, API security schemes, API management features and API design tactics can reduce exposure and provide defense-in-depth. API security is not simply the developer’s problem — security-focused enterprise guidance and platforms, a commitment to security testing and a process of security by design are crucial to realizing robust API security.

A closer look at Security Platform Integration can be found here: Securing APIs with an Integrated Security Framework | by TRGoodwill | Sep, 2022 | Medium