Integrating With the Broadcom CA Layer7 API Gateway

This tutorial describes how to integrate the Broadcom CA Layer7 API Gateway with the Curity Identity Server. The Broadcom CA Layer7 API Gateway is a security gateway that proxies HTTP traffic and performs security checks on the data and identity layers.

The Gateway will be configured to use access tokens issued by the Curity Identity Server to protect API access. In this example architecture, the Curity Identity Server sits behind the Gateway as well. But, that is not a requirement, and it does not affect the implementation of the API protection.

Phantom Tokens

This integration uses the concept of Phantom Tokens. The introspect endpoint will return a JWT version of the incoming access token referred to as a Phantom Token. To configure the introspect endpoint to return Phantom Tokens see Introspection and Phantom Tokens.

Protecting APIs

The API is protected by having the Gateway check for an access token in the incoming request’s Authorization header. For the Gateway to validate the incoming access token, it must do two things:

1. If the token hasn't been seen before, the Gateway must ping the OAuth server (Introspection).
2. The Gateway must cache the response from the OAuth server in the Gateway cache (but not in the Gateway DB, which is considerably more resource-consuming).

1. The Web-Backend makes a request towards the OAuth-protected API.
2. The Gateway first tries to find the Access Token in the cache. If there's a miss, it calls the OAuth server’s Introspect endpoint.
3. The OAuth server responds with token information and an Access Token in JSON Web Token format (JWT).
4. The Gateway caches the response for the lifetime of the token.
5. The Gateway forwards the request to the OAuth-protected service (the API), passing the JWT instead of the original access token in the Authorization header back to the protected service.

Setting up the Gateway to Validate Access Tokens

To validate an access token, a new policy fragment must be created. Its task is to perform the operations described in the previous section. The benefit of the policy fragment is that it can be included in any service published by the gateway.

1. Create a New Policy

Use the Create Policy option in the policies window, and select Included Fragment as policy type. Name it Require OAuth Token.

2. Define Cluster Properties

To make the policy portable between environments, it's recommended to use cluster properties when applicable. There are three variables and one credential that need to be defined in this policy.

Variables

From the Tasks menu, open Global Settings -> Manage Cluster-Wide Properties and add:

• oauth_introspect_client_id = the_name_of_the_gateway_client
• oauth_server_host = the hostname of the Curity Identity Server (e.g., https://idsvr.example.com:8443)
• oauth_server_introspection_path = the path of the introspection endpoint as configured in the Curity Identity Server (eg: /oauth/v2/oauth-introspect)

Credentials

From the Task menu, open Certificates, Keys and Secrets -> Manage Stored Passwords and add:

oauth_introspect_clientsecret = the client secret

3. Add the Policy Content

To add the policy content, open the newly created Require OAuth Token policy and copy the XML from the Appendix A: – Require OAuth Token fragment in this document and paste it into the window. This should create a structure that looks like the following:

After saving and activating, the policy fragment is ready to use.

4. Create Encapsulated Assertion

This step is optional but makes the enforcement easier to use. To create an encapsulated assertion, right-click on the Require OAuth Token policy in the service window and select Create Encapsulated Assertion. Enter the oauth.* variables (oauth.client_id, oauth.subject, oauth.expiration, oauth.jwt, oauth.scope) as output variables and place the assertion in the Access Control section.

Enforcing Access Token in API Policies

Now that the Require OAuth Token policy is configured, it can be included in all services that it should protect.

The included fragment (or the encapsulated assertion) should be placed at the beginning of the service policy after the Require SSL or TLS transport assertion.

Exported variables

The Require OAuth Token fragment will export the following variables:

• oauth.client_id
• oauth.subject
• oauth.expiration
• oauth.jwt
• oauth.scope

Passing the JWT to Backend APIs

After a successful lookup of the Access Token, the service will eventually route to a backend API. At this point, it should pass on the internal JWT it received from the introspect endpoint. This is done by adding the oauth.jwt to the Authorization header of the routed request.

Introspect With application/jwt as Accept Header

The Curity Identity Server can also respond to requests in the introspection endpoint with the Accept: application/jwt header. When introspecting a valid access token, The Curity Identity Server responds with 200 OK and the JWT in the response body. An expired or invalid access token causes The Curity Identity Server to respond with 204 No Content. This means that the gateway doesn’t need to parse the JSON (as when using normal introspection), making the proxying even faster. Appendix B: – Require OAuth Token, introspect with application/jwt contains a policy fragment that uses application/jwt. Also, the Curity Identity Server’s status codes on the introspection request are considered, and the Gateway responds accordingly. This fragment only exports the variable oauth.jwt, which can replace the access token in the Authorization header forwarded to the API.

Appendix A: – Require OAuth Token Fragment

Appendix B: – Require OAuth Token, introspect with application/jwt