Securing APIs with an Integrated Security Framework
Integrated Security Patterns, Platforms and Tactics
Securing APIs is not simply a problem for the developer to solve. Security-focused enterprise guidance and platforms, a commitment to security testing and a process of security by design are crucial to underpinning robust API security.
API gateway platforms are a key component of the enterprise security architecture and should be closely integrated with enterprise security platforms such as token services, IAM and SIEM.
This article discusses some proven security integration patterns, platforms and tactics that may guide or challenge discussion around API security. As is always the case, specific strategies should be carefully considered and tailored for a specific organisational context.
Security By Design — Data Sensitivity and Security Controls
An appreciation of data sensitivity and applicable security controls must be embedded with the domain model in order to ensure robust API security.
While individual business domains own the process and domain models, it is an enterprise responsibility to support and guide DDD processes, and to ensure that that during the domain modelling phase data is classified and regulatory controls identified.
It is essential to define and guide a clear and efficient process for the registration of business resources and data profiles to Identity Access Management (IAM) platforms.
Domain, Organisation and System On-boarding
In order to control access to APIs, a number of processes must be supported:
- Organization/domain enrollment — including creation of roles/groups and permissions attached to activities such as app creation, subscription etc.
- Registration of a client — to synchronize client Id and profile across API management and STS platforms.
- Registration of a resource — as STS clients and as IAM resources with access policies.
A shared, single point of entry process for organization and client system on-boarding for IAM and API Management platforms provides an optimal developer/user experience, reduces duplication of effort and ensures synchronicity between platforms
Organisation/Domain Onboarding
Organisations that manage sensitive data should provide a single portal and process for domain and external-organisation enrollment to both STS and API management platforms, to provide validation and to initiate workflows to establish user authorization for the management of clients and APIs belonging to the domain in APIM tooling. All API management portals should be secured by OIDC and granular authorization.
Client Application Onboarding
Similarly, a single portal and process should be offered for simultaneous registration of a client application to the STS and API management, provisioning to event platforms, and for the management of client Id, shared-secret and certificates for client system authentication. The Client Id and profile are shared across platforms. In the case of Dynamic Client Registration (RFC 7591) via the API client portal, the shared-secret is pushed from, but not retained by the API management platform. Certificate and secrets management policy (e.g. rotation) will be with IAM — consider the communication of polices and events with API clients.
Registration of API Resources
Registration of API resources and servers is a special case of client system registration. API resource servers must be registered as STS clients, resource access policies defined, and URI-Client_id mapping captured (more on that later). Resource profiles may be shared and cross-validated with API profiles. The need for OAuth2/OIDC enabled API providers to manage STS credentials in the same way as API clients suggests a common platform.
Client API Subscription and Registration of API Scopes
Client access management on API management platforms is controlled via API subscription. Subscription approval may be automatically granted in the case of open APIs, however for confidential and sensitive APIs, a subscription approval workflow will allow the API owner to approve or reject subscription on a per-client basis.
At the same time, a standard authorization/STS platform mechanism for scope management requires client systems to pre-register scopes that may be dynamically requested in an authorization/token request. Where this is the case, client scope registration should be synchronized with API subscription approval via the API client portal. This may be achieved by utilizing the Dynamic Client Registration (RFC 7591) protocol together with a customized subscription approval workflow, or templated READ and WRITE API subscription plans.
Zero-Trust
OAuth 2.x and OIDC
A zero-trust posture and mandatory OAuth2/OIDC token requirement by API gateways and resource services can provide defense-in-depth, harmonize API management (APIM) with Identity and Access Management (IAM) workflows and ensure alignment of API and event access management with an organisation’s security posture and policies.
In an OAS 3 API specification document, an OAuth2 and/or OIDC token requirement is described by security schemes. The requirement is enforced by API gateways.
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 accessAPI specification security schemes are derived from matching security controls captured by the domain model against templated enterprise security patterns.
The API security architecture must provide security platforms with a means to identify the target resource, to authorize requested access scope, and to apply threat protection based on client, user or invocation context.
System Identity Assurance
API keys are a low-assurance mechanism for identifying client systems, while OAuth2 tokens can provide high-assurance claims about the authenticated identity of client systems and end-users applicable to both API and event management contexts.
Some APIM platforms are heavily predicated on API keys to identify clients — in this case client API keys should be synchronized with Security Token Service (STS) client Ids, and validated against OAuth2 client Id claims in the gateway. This might be the OIDC “azp” claim, or a custom OAuth2 “client_id” claim. If the Ids do not match, the request should be rejected.
Scope-Based API Authorization
API Scopes
API scopes are an extension of the OAuth scope mechanism and are utilized by OAS 3 and many API management platforms to control access to API operations. API scopes represent an authorization from the owner of a business resource for a client application to call a particular business resource API.
Required API scopes are documented by security schemes in the API specification, and applied at an operation granularity. E.g.
paths:
/users:
get:
summary: Get a list of users
security:
- OAuth2: [read] # <------
- OpenID: [read] # <------
...API scopes answer only the low-granularity access question “is this client/user authorized to call this API?”. Claims presented by access and OIDC identity tokens are intended to provide the business service with the means to answer to the high-granularity access question “Does this particular user have a right to see the requested data?”.
The generated access token will include the subset of requested scopes to which the user and/or client is authorized, along with the resource audience(s) to which the scopes apply. E.g.
{
"aud": [
"https://example.com/resource-server",
"https://example.com/api-gateway"
],
"iss": "https://authorization-server.com/",
"sub": "12B34C",
"exp": 1637359973,
"iat": 1637356372,
"azp": "https://example.com/client-app",
"scope": "openid scope1 scope2"
}Resource scope and audience claims are discussed in more detail here.
API Scope Taxonomy
Agreement on an OAuth schema for client system, API scope and potentially other claims will be required. JWT schemas and semantics may be addressed with internal standards, or potentially by the adoption of national or industry digital identity frameworks.
Generic, unambiguous API scopes such as ‘read’ and ‘write’ against an API resource are possible when either or both of rfc 8693 and rfc 8707 OAuth2 framework enhancements are supported. The client may request ‘read’ and ‘write’ scopes for multiple resources, and if the user/client is authorized for that scope against ALL of the requested resources, the scope is provided.
Resource-specific, name-spaced API scopes allow tokens to encompass multiple resource services in any case, and provides opportunities for granular, domain-specific access policies — at the cost of additional complexity. API scopes will require a name-spaced taxonomy (e.g. api:[subdomain]:[resource]:[R|W]) to control clashes, complexity and sprawl.
Authorization Flows
Core OAuth2 and OIDC framework specifications lack a mechanism to identify target resources for API scope authorization and inclusion in the “aud” claim. However, RFC 8693: OAuth 2.0 Token Exchange and RFC 8707: Resource Indicators for OAuth 2.0 enhancements to the OAuth 2.0 Authorization Framework specifically provide a “resource” parameter to allow the client to specify target resources (token audience) by URI.
Support for these RFCs is highly desirable in order to enable coherent, standardized flows in support of scope-based API authorization.
Support for recent RFC enhancements may be out-of-the-box, or if still ‘on the roadmap’ for your platform, configuration and/or customization can potentially bridge the gap. Some vendors provide configuration assets on platforms such as github.Token Exchange Flow
RFC 8693 OAuth 2.0 Token Exchange provides a transparent, standardized method of propagating end-user identity and managing access to upstream business resources.
In the Token Exchange scenario, the user presents a valid token for the client application. For each new service/API context, the client application will exchange the client-side user access token for a new access token with the required resource service audience and one or more API scopes, retaining the binding to the user’s identity token.
OIDC and OAuth2 Flows
RFC 8707: Resource Indicators for OAuth 2.0 introduces a resource parameter to the OAuth 2.0 Authorization Framework. The specification allows client servers to unambiguously define the token audience in a token request or authorization redirect and supports generic, standardised scopes such as ‘read’, and ‘write’. It provides support for scenarios such as client credentials grant type token requests for server-to-server API calls, as well as OIDC authorization code flows.
Tactical Patterns — When Token Exchange and Resource Indicators are Not Yet Supported
When a neither Token Exchange nor Resource Indicators specifications can be supported, the identity of the resource service audience must be derived by the STS via a custom mechanism such as mapping from unique name-spaced scopes.
Tactical OAuth2 patterns for API scope authorization are expanded on here.
Some APIM and STS platforms are opinionated about API scope implementation, and may offer deep, proprietary APIM-STS integration to mitigate some of the complexities. Default platform mechanisms and behaviours should be examined and considered.Logging, Tracing and Security Incident and Event Management
API management and event message platform integration into analytics driven Security Incident and Event Management (SIEM) threat protection platforms is essential and will require API/Event platform and security teams to work together on event schemas and taxonomy.
The cyber security team (or specialist proxy) actively maintains solutions to monitor and protect resources. These solutions may leverage increasingly sophisticated AI tools to detect, investigate and respond to abnormal invocation patterns and user behavior. Dynamic intervention may include denying resource access at the authorization server based on specific contextual data, such as user, client, geography, time, identity assurance level or other relevant factors. Security and API gateway platforms will provide affordances to SIEM for active threat protection.
Distributed tracing can provide detailed incident data and valuable insights into interconnected systems. Native cloud tracing is easily employed but difficult to stitch together across platforms. Consider a non-proprietary, cross-platform standard such as Open Telemetry / W3C Trace Context for hybrid and multi-cloud environments.
Distributed Trace Compliant Behaviour — An Enterprise Commitment
When Open Telemetry / WC3 Trace Context is employed all systems implementing or mediating APIs must either participate in a trace by updating the trace header or propagate the trace header to guarantee that traces are not broken.Model Driven Development and Integrated DevOps
A well-defined process and complimentary tooling to enable model driven development and vertically integrated DevOps will improve the security of APIs, and reduce friction between development and maintenance of the domain model, and implementation and delivery of the model.
Model Driven Development
Data classification and applicable security controls are captured by the domain data model. API specifications are generated from the model, in conformance with API standards and security policies, and committed to source control. This process may be managed by an integrated domain data modelling platform.
Vertically Integrated DevOps and Continuous Security Testing
New and updated REST interfaces generated by domain modelling tooling are published to API management platforms simultaneously with the deployment of the business service. Deployment and testing of APIs should be automated, domain-autonomous and as frictionless as possible.
Design standards and security policy compliance is automated wherever possible. DevOps pipelines will apply Policy-as-Code controls, enforce mandatory standards with specification document linting, and will validate, or even inject API security schemes as appropriate for a given context.
Global API security testing targeting known risks and vulnerabilities (incl. OWASP top 10) is overseen by Cyber-Security specialists and is routinely reviewed and maintained. Continuous testing of security controls applicable to each business API is a delivery team responsibility and is built into integration and delivery pipelines and regression tests.
API lifecycle management and DevOps is discussed in more detail here.
API security testing concepts are discussed in more detail here
API Gateway Security Features
An enterprise integration/interoperability framework should be cognizant of the role of the API gateway in enforcing API security, and opinionated about the application of security features, including (but not limited to) the following:
- Rate Limiting : Default rate limiting and throttling policies should be applied at the API gateway. These default policies may be over-ridden on a per-API basis. Appropriate alerts and actions for approaching and exceeded thresholds should be configured. Rate-limiting headers may be applied by API gateways.
- API Subscription Approval : A client subscription approval workflow should be made available to publishers of APIs, and should apply by default to APIs classified as sensitive.
- OAuth2/OIDC Requirement : Consider enforcing a default OAuth2/OIDC Requirement for API invocation, including system-to-system API calls. Exceptions are explicitly configured otherwise. Ensure that routine security testing is in place to verify the requirement in all environments.
- Input Validation : A default API Gateway request size limit and default request validation against the API specification are recommended. Configure content-based (JSON and XML) threat protection.
- HTTPS Frontside protocol : HTTPS schemes should be mandatory. Consider removing support for unencrypted HTTP front-side. Set and enforce a TLS version policy such as ’n’ or ‘n-1’ (e.g. ‘TLS 1.3 or 1.2’). Enable only strong ciphers — weak and compromised ciphers must be disabled.
- Client Certificate Policy : Maintain a minimum hashing algorithm and key length requirement for client certificates. Require clients of external-facing APIs to present a digital certificate that has been signed by a recognized Certificate Authority (CA).
- Mutual Authentication backside : Encourage and facilitate locking down resource server APIs handing sensitive data with mutual authentication between the API Gateway and the resource API.
- Secure Management APIs : Host and harden management (control plane) APIs on a separate, dedicated interface and secure, private subnet.
- Audit Logs : Security events must be logged to an enterprise security incident and event management (SIEM) platform where incidents, patterns and trends can be analyzed and appropriately actioned.
API Development Tactics to Secure APIs
API development tactics, including abstraction, error handling and Data Confidentiality, Integrity and Non-Repudiation are briefly covered here:
API Bites — Tactics to Secure Sensitive API s | by TRGoodwill | Sep, 2022 | Medium
In Summary
Security-focused enterprise guidance and platforms, a commitment to security testing and a process of security by design are crucial to underpinning robust API security.
Security design embedded into the domain modelling process will improve understanding about data profiles and applicable security controls. Well considered and evolvable security patterns and tactics will guide the application of robust security controls, and integrated security testing will ensure compliance. Close integration with enterprise security platforms such as token services, IAM and SIEM provides opportunities to provide defence-in-depth, a higher level of client and user identity assurance, while ensuring an optimal developer experience, reduced duplication of effort and synchronicity between platforms.
