Portal:Toolforge/Admin/API Gateway

This page contains information about the API Gateway component of toolforge.

About

When users want to interact with the toolforge APIs, they have to go through the API Gateway.

The API Gateway has several functions:

Authentication
Aggregation

The code is hosted in gitlab here.

Components

The API Gateway has two components, an nginx process and a webservice.

nginx: takes care of the TLS termination, cert verification and request forwarding. It populates the ssl-client-subject-dn header before doing an auth request to the webservice.
websevice: takes care of a couple of things:
- Exposes the aggregated API definition from all the internal toolforge APIs (ex. Jobs API, Builds API, ...)
- Has an /auth endpoint to authorize the requests that pass through the Gateway. Currently (see the code for exact flow) it uses the ssl-client-subject-dn header that nginx extracted from the certificate to retrieve the username and tool that is trying to do the request, and verifies that they match. There's some exceptions like the deployment with deploy tokens though.

Authentication

Internal toolforge components

Other toolforge components (ex. Components API) can authenticate to the API Gateway by using a signed k8s certificate with a special CN that's allowed in the superusers setting for the API Gateway.

Users

Users (ex. toolforge jobs) authenticate using the user's own k8s certificate, that was generated by the maintain-kubeusers component in their homes.

Aggregation

The API Gateway acts as aggregator for all the internal Toolforge APIs, allowing a single openapi spec to be presented, and centralizing the requests and the authentication.

Each internal API is exposed under their own path, for example builds-api is under the /builds/* set of paths.

Backends

The backends are configured via Helm values. The communication between the gateway and the API gateway must be encrypted via internal CA certificates issued by the api-gateway-backend-ca ClusterIssuer.

Backend services can access the tool and user data by the X-Toolforge-Tool and X-Toolforge-User headers.