Identity Propagation in an API Gateway Architecture

The power of end-to-end user security context with APIs

Robert Broeckelmann is a principal consultant at Levvel. He focuses on API management, integration, and identity–especially where these three intersect. He’s worked with clients across the financial, healthcare, and retail fields. Lately, he’s been working with Apigee Edge and WebSphere DataPower.

As enterprises continue to expand their usage of APIs, the need to keep those APIs secure increases as well. One way to bolster security and improve auditing and authentication is the transmission of an authenticated user’s security context from the front end of a request pipeline, beyond the API gateway, and all the way to the back-end implementation of an API or service.

End-to-end transmission of an authenticated user’s security context benefits API-based systems by enhancing overall security, eliminating the use of generic (privileged) accounts, providing a secure audit mechanism (of traffic traversing the system), and supporting advanced authentication use cases.

This pattern can in some instances cause some complexity, but, as you’ll read in this post, it provides some valuable benefits.

End-to-end identity propagation

However, there are several benefits to propagating the authenticated user security context all the way to the API provider:

• Support for processing Attribute Based Access Control (ABAC) authorization decisions based upon the end-user identity at the API provider.   
• Avoidance of generic service accounts with super-user privileges to connect to the backend.
• Provision of a secure audit mechanism for the user who initiated requests that hit each layer of the infrastructure.
• Maintenance of certain compliance requirements
• Value in SOA and microservice architecture implementations
• Support for authentication protocol translation

Token exchange functionality

This is where token exchange functionality such as that defined by the OAuth2 Token Exchange protocol (grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer with requested_token_use=on_behalf_of; in the most recent spec drafts "on_behalf_of" was changed to "subject_token"), the WS-Trust (active clients with On-Behalf-Of and ActAs) spec, and Windows Kerberos extensions (Protocol Transition and Constrained Delegation, which is based upon Kerberos) can be used.

It’s important to note that this activity requires the intermediary to play an active role in making this specific request; the identity provider must grant explicit rights to the intermediary to be allowed to make this request.

This token exchange functionality essentially enables an actor to exchange a token (such as SAML2 or JWT) with one audience (presumably its own) for a token that describes the same user, but with a different audience from an identity provider. This is done in a secure manner, meaning there are significant limits placed upon which audience the new token may reference.

Two common forms of this token exchange are delegation, where the protocol provides a concept of the intermediary that is making the call (such as the WS-Trust ActAs), and impersonation, where the protocol provides no concept of the intermediary (such as WS-Trust On-Behalf-Of). The OAuth2 Token Exchange spec defines similar concepts for OAuth2 and OpenID Connect (OIDC); however, it uses the terms to mean the opposite of how they are used here.

The API gateway scenario

Now, the entire request/response pipeline, from the front-end consumer to the backend implementation, can use RESTful APIs.

With an API gateway intermediary in place, the whole model will look something like this:

Let's make some assumptions and set some requirements for this scenario:

• The access token is a digitally signed bearer token (JWT).
• All system actors are part of the same security realm (in other words, they use the same identity provider). This identity provider can authenticate all end users of the front-end application.
• Every system actor (API gateway, API provider, and, possibly, the datastore) must validate the identity token (authenticate the request) attached to an incoming request.
• This token validation includes audience restriction enforcement, which further ensures the token is only used where it is supposed to be (the granularity of the audience depends on several factors, including desired reusability of the token, resource authorization policy, and organization security standards).
• All communication occurs over TLS v1.2 or better.
• All communication occurs with RESTful APIs using JSON as the payloads (where appropriate)
• All security details will be implemented with spec-based security (more on that below)
• For added protection, use mutually authenticated SSL between actors where the server component only accepts connections from a single actor (between the API gateway and API provider, for example). This assumes that a single client certificate describes a single system or possibly a single node within a system. There shouldn’t be sharing of certificates across systems.

OAuth2 and OpenID Connect

In particular, OpenID Connect can be used to perform the initial authentication of the end user signing into the mobile application as described in the blog posts here and here.

As outlined in the diagram above, the result of that initial authentication includes an OIDC ID token and OAuth2 access token. The ID token must be validated per the spec, then information contained in it can be relied upon to describe the authenticated user.

If additional information is needed, the mobile app can make a call to the IdP OIDC UserInfo Endpoint to obtain more information about that user. Additionally, the OAuth2 access token that is provided should be cached on the mobile app and included with the authorization header of each API request per the OAuth2 Bearer Token Usage spec. When the mobile app needs data from the backend, it makes an API request to the API gateway.

Now, if the OAuth2 access token is also a JWT token, that makes the downstream authentication (access token validation by the API gateway) easier. If it is an opaque token, then the system actor must be able to support passing the access token into an IdP OAuth2 Introspection Endpoint to validate the token.

All of these details are discussed in great detail in my OAuth2 blog post and OIDC Series. Regardless of the validation process, the token must be validated and, if successful, then the claims provided through that access token (JWT) are available to the system for authorization decisions.

Securing each step of the request’s journey

Some type of coarse-grained authorization decision will likely be made at this point, the details of which are beyond the scope of this conversation. Finally, the access token that was passed into the API gateway with the request needs to be replaced with an access token whose scope matches the downstream actor’s (API provider’s) scope.

This is accomplished with a Token Exchange Grant call defined by the OAuth2 Token Exchange spec. The new access token is placed into the API request (replacing the existing token) and that request is routed to the API provider layer.

When the request arrives at the API layer, the access token is extracted and validated in the same fashion as the input token at the API gateway layer. Likewise, the UserInfo endpoint can be queried for additional information, a fine-grained authorization decision can be enforced, and possibly a new downstream token obtained for the datasource tier. For the last component, this assumes that the datastore layer can process an OAuth2 access token.

The request that is sent to the datastore is almost certainly going to look different than the one that was sent to the API provider. There may also be multiple datasource queries for a single API request. Implementing the OAuth2 access token check at the datastore will likely require a custom authentication module on the target datastore in order to implement the desired behavior.

An example of a database that supports something like this is DB2 with DB2 Connect using Kerberos authentication. More details on that implementation can be seen here.

The authentication and identity propagation model described here isn’t applicable if:

• the end user's security context isn’t extended to the backend
• generic service accounts are used
• OAuth2 Client Credential Grant is used
• any of the other assumptions listed earlier in this post are not true 

Furthermore, using a spec-based approach to implement a complex identity pattern such as end-to-end identity propagation provides a layer of insulation between your solution and the identity provider vendor, making it easier to change out the identity provider later if needed.

Read other posts that Robert has contributed to the Apigee blog.