Tightening Bearer Token Authentication with Proof-of-Possession Tokens Using Kong
Access tokens
In token-based architecture, tokens represent the client’s entitlement to access protected resources. Access tokens (or bearer tokens as they're commonly known) are issued by authorization servers after successful user authentication. The tokens are passed as credentials in the request to the target APIs which inform the API that the bearer of the token is authorized to access the API and perform certain actions.
Challenges with access/bearer tokens
In the flows where access tokens grant access to protected resources, the legitimacy of the token bearer is assumed. Access is granted based on the validity of the token. There is no validation that the bearer is in fact the legitimate owner of the token. This is one of the main vulnerabilities of a bearer token.
If the tokens fall into the hands of bad actors, they can be misused. With the stolen or leaked tokens, bad actors can easily impersonate the user and obtain unauthorized access to protected resources.
For any average API provider, this is a major concern. Recently, Sourcegraph experienced a security incident with leaked admin tokens. The malicious users used their privileges to increase API rate limits for a small number of users. For environments with heightened security needs, stolen or leaked tokens are a serious security risk.
A solution to secure access tokens
A solution to this problem is constraining the tokens issued by authorization server to clients (sender-constrained tokens) so only the entity/client to whom a token was issued can use the token to access resources. This approach is also known as holder of key or proof of possession tokens.
The client presenting the access token has to prove that they are authorized to use the token. To achieve this, the authorization servers bind the tokens to the client's cryptographic keys. Resource servers can then validate the clients are in possession of those keys and grant/deny access accordingly.
Advantages of sender-constrained tokens
The primary security vulnerability of standard bearer tokens is remediated, as the legitimacy of the bearer is verified. Access to the protected resource is granted after successful validation of
- The client certificate used in the connection
- The thumbprint of the client certificate in the token matching the client certificate in the underlying connection
- Token validity
For environments with high security requirements such as financial services, e-health, and e-gov, this added layer of token security mitigates the risk of misuse of tokens as sender-constrained tokens simply cannot be replayed or redirected by an unauthorized party.
Moreover, usage of sender-constrained tokens is a must in open banking. One of the requirements of financial API (FAPI 2.0) is for the resource servers to support and verify sender-constrained access tokens using either of the methods.
Example of an access token with certificate thumbprint
Implementations of sender-constrained tokens
The RFC describes two methods to implement sender-constrained tokens
- Using Client Certificates (mTLS ) - Certificate-bound access tokens
- The Demonstration of Proof-of-Possession (DPoP) at application layer
Certificate-bound access tokens
With mTLS, the access tokens are bound to the underlying mutual TLS connection between the client and the authorization server. Such tokens are known as certificate-bound access tokens. This approach uses the Public Key Infrastructure (PKI). The CA is trusted by the Authorization server and Kong.
Figure 1 shows a sample exchange between the client, IDP, and Kong. In a request to obtain a token, the client establishes a mutual TLS session with the authorization server’s token endpoint. After a successful TLS client authentication, the authorization server will mint an access token, encode the thumbprint of (hash) the client certificate either directly in the token (JWT) or in the Introspection Response (when using opaque tokens).
To access resources protected by Kong, the client establishes a TLS connection to Kong Gateway using the same client certificate and presents the access token. The same CA is trusted by Kong as well. Kong validates the client certificate and the certificate thumbprint in the tokens to the underlying mTLS connection. Access to the protected resource is granted after successful validation of all three.
- The client certificate used in the connection
- The thumbprint of the client certificate in the token matching the client certificate in the underlying connection
- Token validity
Kong’s support of certificate-bound access tokens: How it all comes together
To support certificate-bound tokens there are requirements on all parties involved in a typical token-based flow. Following are the prerequisites for each party involved in the flow
Prerequisites
- Authorization server that is capable of generating OAuth 2.0 Mutual TLS Certificate Bound Access Tokens
- A Certificate Authority(CA) that trusted by both the Authorization Server and Kong. The CA is used to issue client certificates
- A client application with an appropriate grant type (example client credentials grant) and ability to handle sender constrained tokens via mTLS
- Kong Gateway 3.5 with OIDC and mTLS plugins
- Upstream API service to which Kong proxies the request
- Client certificates issued to clients
Configuring Kong
Kong can be instructed to handle certificate-bound access tokens with the help of two plugins:
OIDCplugin- mTLS plugin such as
TLS modifierormtls-auth
TLS Modifier plugin does not enforce a mTLS connection. However, for certificate-bound access tokens to work, a client certificate must be presented along with the token
mtls-auth The CN check/validation cannot be disabled in the plugin and hence the plugin requires consumer mapping. Consumer objects should be created and client certificates need to be mapped.
Kong supports the usage of certificate-bound access tokens in three authentication flows. In these flows, the client entity obtains an access token from the authorization server's token endpoint and presents that as a bearer in the request to Kong. If the access token is opaque, Kong exchanges it for a JWT by calling the introspection endpoint.
- JWT bearer
- Introspection
- Session (Session Authentication is only compatible with certificate-bound access tokens when used along with one of the other supported authentication methods)
OIDC plugin configuration options
OIDC plugin offers two new settings to control the behavior of the plugin for certificate-bound tokens.
With all the prerequisites met and the plugins configured to support certificate-bound tokens, Kong Gateway will enforce the incoming requests to establish a mutual TLS connection using a valid client certificate and present an access token. Kong proxies the request after successful validation of the certificate thumbprint in the token to the client certificate in the underlying connection.
For step-by-step instructions on how to enable the feature refer to OpenID Connect | Kong Docs
Conclusion
With this feature, Kong complies with the requirements of financial API (FAPI 2.0) to support and verify sender-constrained access tokens. It's not limited to open banking or financial services. Mutual TLS Sender-Constrained Tokens are a suitable implementation for any environment with high security requirements such as e-gov and e-health. The solution forces the sender to prove they are the rightful owner of the token. This added layer of security mitigates the risk of misuse of tokens as they cannot be used without proof of possession.