What is an API Management System? A Brief Overview
On this page
Moving to an API-driven and/or microservice based architecture requires more systems to work together. The first step is to have an identity management system in place, as described here. This allows the APIs (Microservices) to pull the identity out from the APIs and manage it centrally.
The API Management System is the logical structure to provide data and service access to the system. It is a slave system to the Identity Management System, and there is a clear separation of responsibilities between the two. The API Management System is the “police” that enforces the access control, whereas the Identity Management System is the Authority that issues the tokens that can grant access, like a passport or a driving license.
The AMS contains the following services:
The API Security Service
Responsible for ingress security to the API system.
The API Integration Service
Responsible for higher level API aggregations.
The API Management Service
Responsible for developer management, monetization and monitoring.
The API Security Service
The API Security Service ensures that access to data and capabilities exposed by downstream APIs is secured according to centrally-defined policies. To answer the question of what the caller of the API is allowed to do, it must first determine who the user is. This is done by relying on the Authentication Services, Federation Service, and STS in the Identity Management System. The identity is communicated to the API Security Service as a security token that is minted by the STS. The API Security Service trust only the STS in its own domain to provide it with token-based representations of user identities, and all identity federation and cross-domain trust brokering is performed in the Identity Management System.
Enterprise security policies could be established in an Entitlement Management System. These rules govern access, and the API Security Service enforces these. These policies may be simple role-based rules, but more fine-grained policies are more prevalent for highly regulated and valuable data access. To ensure authorized access to these, the API Security Service will use attribute-based access control that accounts for more than the role of the consumer. The policies consider the end user’s identity, the client (such as a mobile app running on a device that may or may not be enrolled in a Mobile Device Management system), the context (such as the network the device is connected to) and the action being requested.
An API Security Service is almost always implemented as a proxy that stands between the northbound API being exposed to clients and the downstream APIs being protected. It is for this reason that an API Security Service is also commonly referred to as an API gateway or API proxy. With this position and relationship to the Identity Management System, the API Security Service is used to transform the incoming security tokens into some other form of credential or token that can be consumed by the downstream services that are being proxied. This position also makes it ideally suited to perform integration and message shaping which is the other core capability of the API Management System.
The Phantom Token Flow
A common interaction pattern between the IMS and the API Security Service is to use the Phantom Token Flow. This pattern allows for tokens to be opqaue when used on the Internet, and then exchanged by the API Security Service at the Token Service for a by-value token to be used internally.
The Phantom Token Approach is a privacy-preserving token usage pattern for microservices. It combines the benefits of opaque and structured tokens. To understand the pattern it is therefore essential to understand the basic differences between these token types.
OAuth 2.0 Token Types
When OAuth 2.0 was defined tokens were intentionally kept abstract and the format was not defined. There is basically no limitation on the format of tokens that an authorization server may issue. In practice you can distinguish two types of tokens:
- Opaque tokens (by reference)
- Structured tokens (by value)
An opaque token is a random string that has no meaning to the resource server thus the token is opaque. However, there is metadata connected to the token such as its validity or the list of approved scopes that may be of relevance or even vital for the authorization decision of the resource server AKA API or microservice. In a system using solely opaque tokens the resource server cannot retrieve this kind of information from the token itself but must call the authorization server by sending a request at the introspection endpoint as illustrated below.
An opaque token can be seen as the reference to the user attributes and token metadata. Thus passing an opaque token can also be referred to as passing a token by reference.
Having to look up each token for validation will inevitably create load on the resource and authorization server as well as infrastructure. Structured token formats such as JSON web tokens (JWT) solve this problem. JWT tokens are compact and lightweight tokens that are designed to be passed in HTTP headers and query parameters. They are signed to protect the integrity of its data and can even be encrypted for privacy reasons. Since the format is well defined the resource server can decode and verify the token without calling any other system.
Structured tokens are tokens passed by value. The token contains enough data for the resource server to make its authorization decision. Often, it also contains user information. In certain cases such a token may even contain personal identifiable information (PII) or other data protected by law or regulations and the token as well as related systems become a subject to compliance requirements.
The Phantom Token Approach
The Phantom Token Approach is a prescriptive pattern for securing APIs and microservices that combines the security of opaque tokens with the convenience of JWTs. The idea is to have a pair of a by-reference and a by-value token. The by-value token (JWT) can be obtained with the help of a by-reference equivalent (opaque token). The client is not aware of the JWT and therefore we call the token the Phantom Token.
When a client asks for a token the Token Service returns a by-reference token. Instead of having the APIs and microservices call the Token Service for resolving the by-reference token for every request the pattern takes advantage of an API gateway, reverse proxy or any other middleware that is usually placed between the client and the APIs. In that way the APIs and microservices can benefit from the JWT without exposing any data to the client since the client will only retrieve an opaque token.
The client retrieves a by-reference token using any OAuth 2.0 flow.
The client forwards the token in its requests to the API.
The reverse proxy looks up the by-value token by calling the Introspection endpoint of the Token Service.
The reverse proxy replaces the by-reference token with the by-value token in the actual request to the microservice.
Benefits
The main benefit for opaque tokens is security. Access tokens are intended for the resource server, the API. However, a client may violate this rule and parse a token nevertheless. By using opaque tokens clients are prevented from implementing logic based on the content of access tokens. In addition opaque tokens for clients limit the regulated space and remove the risk of data leakages and compliance violations. It is simply not possible for the client to access or leak any data because it is not given any.
At the same time security is increased performance is optimized. The microservices will use JWT tokens that contain all the data that the service requires for processing. No need for time consuming requests. In addition the pattern can utilize caching mechanisms of the reverse proxy. A by-value token can be cached until it expires. The Curity Identity Server supports HTTP cache headers with updated values for this purpose. As a result the number of requests needed for token exchange is minimized and the system's performance is optimized.
The Phantom Token Approach is compliant with the OAuth 2.0 standard. Neither the client nor the APIs have to implement any proprietary solution for this pattern. This makes the pattern vendor neutral and applicable for any OAuth 2.0 ecosystem.
The API Integration Service
The API Integration Service is not covered in depth, but is mentioned to illustrate its place in the architecture. The integration service is used when there are many backend-APIs that need to be integrated into new services and when orchestration might be needed.
This is similar to the tradition Enterprise Service Bus (ESB) that sometimes still exists. A key point is that the API Integration Service is usually capable of Security, just as the Security Service usually is capable of integration. This doesn't mean that they should be used for that purpose, a dedicated API Security Service is a much better architectural choice for a scalable API infrastructure.
The API Management Service
The API Management Service is used when the APIs are published internally or externally for developers to request access to, and where there is a need to follow up on the usage of API and sometimes do billing or throttling based on business decisions rather than technical ones.
Since all identity management is delegated to the Identity Management System, the API Management Service should not maintain the master record of applications integrating with the system. Instead it should register new applications as Clients at the Token Service using the Dynamic Client Registration protocol.
The developer logs into the portal and requests new application credentials
The API Management Service makes a DCR request to the Token Service to create a new client
The Token Service responds with the client credentials and other properties about the new client
The developer obtains the credentials and can use them in the application
Conclusion
As the API landscape grows it's important to manage identity and trust centrally. By designing the API Management System in a way that it depends on the Identity Management System for identity removes complexity. Microservice APIs or other types of APIs can be deployed with ease since relying on the presence of JSON Web Tokens in the request makes both authentication and authorization of requests simple. The API Security Service is key to protect the API landscape, and to efficiently leverage opaque tokens on the Internet and by-value tokens internally. Find out more about Curity's API Management Platform.