Set Up Kong API Gateway for GCP

1.0 Introduction

This document describes how to configure the Kong API Gateway with PingFederate for authentication using the Client Credentials grant and a custom Kong plugin for Google Cloud Platform (GCP) OAuth to enable secure communication required for onboarding a GCP connection in Fortanix Key Insight.

Configuring the Kong API Gateway involves the following steps:

Set up the custom Kong plugin for GCP OAuth
Create a Kong service
Create a Kong route
Configure the JWT route plugin
Configure the GCP OAuth plugin
Create a Kong consumer
Register the PingFederate public key as a JWT credential for the consumer
Verify the configuration

2.0 Prerequisites

Before you begin the setup, ensure the following requirements are met:

PingFederate Configuration:
- A PingFederate server or Ping Identity tenant is available.
- An OAuth client application is created with the Client Credentials grant enabled.
- The following PingFederate credentials are available:
  - Client ID
  - Client Secret
  - Token Endpoint URL
For more information on retrieving the PingFederate credentials, refer to GCP Configuration Using PingFederate as an OpenID Connect Identity Provider.
A GCP project is available with the required permissions to access the GCP services (For example, Cloud KMS) and GCP APIs.

3.0 Set Up Kong Plugin for GCP OAuth

Perform the following steps to set up the Kong plugin for GCP OAuth:

Download the GCP Kong plugin file (kong-fortanix-gcp-oauth-x.x.x-x.all.rock).
Install and configure the plugin following the instructions in the Kong official documentation.
Run the following command to check the plugin license:
```
luarocks show kong-fortanix-gcp-oauth
```
Optionally, to check the actual LICENSE/NOTICE files, unzip the rock file, and check the doc directory:
```
unzip kong-fortanix-gcp-oauth-x.x.x-x.all.rock
```
Add the following entry to the Kong configuration file to enable the plugin:
```
plugins = bundled, kong-fortanix-gcp-oauth
```
Here, kong-fortanix-gcp-oauth is the name of the GCP OAuth plugin.
Restart Kong to apply the changes.

4.0 Create a Kong Service

Run the following command to create a service in Kong API Gateway:

curl -s -X POST https://<kong host>:<admin port>/services/ \
  --data "name=gcp-service" \
  --data "url= https://cloudkms.googleapis.com"

Where,

<kong host>: The hostname or IP address where the Kong Admin API is accessible. For example, kong.example.com.
<admin port>: The port on which the Kong Admin API listens. For example, 8444.

5.0 Create a Kong Route

Run the following command to create a Kong route for gcp-service and forward incoming requests to GCP:

curl -s -X POST https://<kong host>:<admin port>/services/gcp-service/routes \
  --data "name=ping-route" \
  --data "paths[]=/gcp-ping" \
  --data "strip_path=true"

NOTE
For PingFederate client credentials configuration, the API Gateway URL should be https://<kong-host>:<kong-proxy-port>/<path>.
Where,
<kong-proxy-port>: The port of Kong proxy interface.
<path>: The path configured in the Kong route. For example, gcp-ping.

Run the following command to enable the preserve_host setting to forward the incoming GCP Host header to the upstream service:

curl -s -X PATCH https://<kong host>:<admin port>/routes/ping-route \
  --data "preserve_host=true"

This step is critical because the Kong plugin uses the Host header to determine the target Google Cloud service for authentication.

Example:

cloudkms.googleapis.com

6.0 Configure JWT Route Plugin

Run the following command to configure a JWT plugin on the ping-route in Kong API Gateway. This plugin validates the tokens issued by PingFederate using the RS256 signature algorithm and the client_id claim:

curl -s -X POST https://<kong host>:<admin port>/routes/ping-route/plugins \
  --data "name=jwt" \
  --data "config.key_claim_name=client_id" \
  --data "config.claims_to_verify[]=exp" \
  --data "config.run_on_preflight=true"

Here, the client_id claim corresponds to the PingFederate Client ID used in the Client Credentials grant.

7.0 Configure GCP OAuth Plugin

Run the following command to configure the GCP OAuth plugin for the gcp-service in Kong API Gateway:

curl -s -X POST \
   --url https://<kong host>:<admin port>/services/gcp-service/plugins/ \
   --data "name=fortanix-gcp-oauth"

8.0 Create a Kong Consumer

A Consumer represents an external client that interacts with APIs managed by Kong API Gateway. In this case, the consumer represents Fortanix Key Insight.

Run the following command to create a consumer (ki-consumer):

curl -s -X POST https://<kong host>:<admin port>/consumers \
  --data "username=ki-consumer"

9.0 Register PingFederate Public Key as a JWT Credential in the Consumer

Kong API Gateway requires a PingFederate public key to verify the JSON Web Token (JWT) presented by Fortanix Key Insight when scanning GCP resources.

The following sections describe the steps to retrieve the public key and add it to Kong:

9.1 Retrieve an Access Token from PingFederate

Run the following command to retrieve a client-credentials access token from PingFederate:

curl -s -X POST https://<PING DOMAIN>/as/token.oauth2 \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<PING CLIENT ID>" \
  -d "client_secret=<PING CLIENT SECRET>"

Here, replace <PING DOMAIN>, <PING CLIENT ID>, and <PING CLIENT SECRET> with the PingFederate credentials collected earlier.

9.2 Extract the `kid` from the JWT Access Token

Perform the following steps:

Set the access token obtained in Section 9.1: Retrieve an Access Token from PingFederate as an environment variable:
```
export ACCESS_TOKEN=<ACCESS_TOKEN_FROM_PING>
```
Use the following Python script to extract the kid from the JWT access token:
```
import sys, json, base64, os
token=os.environ.get("ACCESS_TOKEN")
header_b64=token.split('.')[0]
pad = '=' * (-len(header_b64) % 4)
header=json.loads(base64.urlsafe_b64decode(header_b64+pad))
print(header.get('kid',''))
```
The script reads the access token from the ACCESS_TOKEN environment variable and prints the Key ID (kid) value. Note the kid value printed by the script. This value is required in the next section.

9.3 Retrieve the PingFederate Certificate Corresponding to `kid`

Perform the following steps:

Run the following Python script to retrieve the certificate from the JWKS endpoint:

import os, json, urllib.request
jwks_url = 'https://<PING DOMAIN>/.well-known/jwks.json'
kid = "<KID_VALUE>" 
with urllib.request.urlopen(jwks_url) as resp:
    data = json.loads(resp.read().decode())
key = next((k for k in data.get('keys', []) if k.get('kid') == kid), None)
if not key:
    print('', end='')
    raise SystemExit(0)
x5c = key.get('x5c', [None])[0]
if not x5c:
    print('', end='')
    raise SystemExit(0)
print('-----BEGIN CERTIFICATE-----')
for i in range(0, len(x5c), 64):
    print(x5c[i:i+64])
print('-----END CERTIFICATE-----')

Where, replace <KID_VALUE> with the kid obtained in Section 9.2: Extract the kid from the JET Access Token.

Save the output as ping-cert.pem.
Run the following command to extract the public key from the certificate (ping-cert.pem):
```
cat ping-cert.pem | openssl x509 -pubkey -noout
```
This command prints the public key to the console.

9.4 Add the Public Key to the Kong Consumer

Run the following command to add the extracted public key (<public key>) to the Kong consumer (ki-consumer) to verify PingFederate RS256-signed tokens:

curl -s -X POST https://<kong host>:<admin port>/consumers/ki-consumer/jwt \
  --data-urlencode "key=<PING CLIENT ID>" \
  --data-urlencode "algorithm=RS256" \
  --data-urlencode "rsa_public_key=<public key>"

The key value must match the client_id claim in the PingFederate access token.

10.0 Verify the Configuration

Run the following request to a Google Cloud API to validate that the entire integration is working end-to-end:

(You may need to obtain a fresh access token from PingFederate and use it as <ACCESS TOKEN>)

curl -s \
-H "Authorization: Bearer <ACCESS TOKEN>" \
-H "Host: <GCP_HOST>" \
-H "Content-Type: application/json" \
-H "X-Scopes: https://www.googleapis.com/auth/cloud-platform.read-only" \
-H "X-Audience: <>" \
-H "X-Service-Account-Email: <>" \
-X GET https://<kong host>:<kong-proxy-port>/gcp-ping/v1/projects/<PROJECT_ID>/locations

If the configuration is successful, the response returns a list of available Google Cloud locations for the specified project.

This confirms that:

The PingFederate-issued token is successfully validated by the Kong API Gateway JWT plugin.
The GCP OAuth plugin signs the request correctly.
Kong forwards the request to the Google Cloud API.