Ignacio Lozano, Karine Pires, and Chris Sterling contributed to this blog post.
In today’s world of digital transformation, APIs are present in almost every software product. Many teams are responsible for deploying and managing a large portfolio of APIs. However, that scale and complexity of APIs also makes it complicated to control and manage access. Specifically, understanding granular usages and uncovering insights and utilization can be difficult. Enter API key management with API portal for VMware Tanzu and Spring Cloud Gateway for Kubernetes, designed to solve this problem and more. This post primarily explores the features for API key management. For information about other features, check out the latest documentation.
API key management features
As an API Consumer, you can generate API keys for single or multiple API groups configured with your API portal for VMware Tanzu. You can view the list of keys that are currently active and revoke them once they are no longer needed. Any generated key is stored in a secret store from which the configured Spring Cloud Gateway for Kubernetes can read and verify any incoming requests. HashiCorp Vault is a leading provider in secret management and hence was chosen as the inaugural integration for API key management.
Create API Key modal view
As an API Manager, in addition to all of the above features, you can also see a detailed view of all the keys generated by all users in your instance of the API portal. For each key, you can view the key name, issued on date, owner, and the API groups accessible with that key. You can also revoke keys created by any user within the API portal. A user is identified as an API Manager by inspecting a claim within the ID token from the OIDC Identity Provider. For more details on configuring API portal to inspect the right claim, see the API Manager section in the documentation.
API Keys list view for API Managers
Getting started with API Management
Note: The rest of this guide will assume that API portal is installed in the “api-portal” namespace, Spring Cloud Gateway for Kubernetes is installed in “spring-cloud-gateway” namespace, and Vault is installed in the “vault” namespace. Please substitute your custom namespace wherever needed.
Configuring Vault access
Here is a bird’s-eye view of the different pieces needed for Vault to integrate with API portal and Spring Cloud Gateway for Kubernetes. You will need to create Vault access policies for each of the two products, create service accounts in their respective namespaces, and attach those service accounts to the Vault access policies.
The next set of commands can also be set using the Vault UI if you prefer. Start by accessing the Vault instance from the command line and configuring a dedicated path for API keys to be stored.
Next, configure access policies for this exact path. API portal needs complete access to this path, whereas Spring Cloud Gateway for Kubernetes only needs the read and list permissions in this path. Create your “api-portal-policy”.
Next, create the “gateway-policy” to read all API keys.
Alternatively, you can create the “gateway-policy” to only read API keys belonging to a specific API group ID.
Connecting Vault to your Kubernetes cluster
In order for your deployments to access the Vault, you need the Kubernetes auth method that uses the Kubernetes Service Account Token.
If your Vault instance is in the same cluster as API portal and Spring Cloud Gateways, then you can run:
Next, you need to create the roles that bind namespaced service accounts to the policies you’ve created. You can create the “api-portal-role” in Vault that allows a service account named “api-portal-sa” in the “api-portal” namespace attached to the “api-portal-policy” in Vault.
Similarly, you can create the “gateway-role” for a service account named ”gateway-sa” in the “spring-cloud-gateway” namespace.
You can create the aforementioned service accounts in their respective namespaces. API portal can also automatically create service accounts during installation.
Configure API portal to enable API key management
In the values.yml file used in conjunction with the installation script for API portal, add the following properties to enable and configure API keys:
Create an Spring Cloud Gateway with API key enabled
The last step is to create a gateway with the Vault details to allow the gateway to read and list the stored API keys. Create an scg.yaml with the below details and apply it. If you add a “serverUrl”, you will also need to create an ingress to route traffic to my-gateway service from that host.
Now, any route like “my-routes” mapped to “my-gateway” will require an additional header “X-API-Key: <API Key Value>” to be passed in.
Create an API key using API portal
In order for API portal to recognize “my-gateway” and its routes, you’ll need to expose the Spring Cloud Gateway operator’s OpenAPI endpoint and, optionally, the my-gateway service too. You can create an ingress using instructions here, or use other methods to expose the operator and gateway.
Then, you can modify the source URLs configured in API portal’s values.yml and rerun the installation script. In case you would like the API portal to trust self-signed or unsecured TLS certificates, you can set the “trustInsecureSourceUrls” property.
Finally, log in to the API portal user interface, navigate to the API Keys tab and click the + API Key button. Give your key a name, select the group, generate the key, and copy the token. Keep the token safe since you can only copy it once.
Try it out
From the list of APIs on the API portal home page, click on the group card that will take you to the Swagger UI page. There, click the Authorize button and paste the API key in the header value field.
Authorization modal for passing the API key with requests
Next, click on the Try it out button and hit Execute to see a 200 OK response.
Response with 200 OK after executing the API with authorization
You can also use an HTTP client like cURL, HTTP, or Postman to test the route.
You can also see that, without the header present, the request fails: