API Gateway - bcgov/common-service-showcase GitHub Wiki

This section of our Wiki documents our configuration of the BC Gov API-Gateway service we use for managing access to our hosted API services.

Sections of this page

External references

What is the API Gateway?

The API Gateway is powered by Kong software and offers authentication, rate-limiting, request IP filtering and more for our APIs. It is part of the API Services Platform provided by a dedicated team (API Program Services - APS) at the Ministry of Citizen Service. They can be reached on rocketcat channel #aps-ops.

Included with the platform is the API Services Portal and Portal Directory API which provides a way to configure our Gateway service and an obnboarding interface for consumers of our hosted APIs (for example CHES and CDOGS).

Secure consumer access to our API is implemented using the OAUTH client credential grant flow. The API Services Portal provides a user interface for automating the backend keycloak configuration to support this. For more details see the APS Documentation on Protecting an API with OAuth2 Client Credential Flow.

API Services Portal

When you first log in to the Portal (https://api.gov.bc.ca/login), choose the API Providers Login. In the top menu you can change to our Namespace csst1. Our team's management tasks can be found from the main page.

Namespace Access

See in Portal.

This is where we give members of our team access to the Portal interface by clicking the 'Grant User Access' link. The team member must try to log into the Portal first, before you can find them. Users with the 'Access.Manage' permission will receive email notifications for Client Access Requests.

Service-Accounts can also be configured here. We currently have one service account that has all the permissions. You can create new ones if you need them. Service accounts can be used as basic auth credentials for getting a token (from the APS token endpoint) to use with the APS Portal API, the GWA CLI and more.

Keycloak Set up

For our Gateway services, we're using our own custom Keycloak realm in the SSO team's gold-tier service.

For each API we offer through the gateway we need to create a confidential keycloak Client. (For example: CDOGS and CHES

See APS Documentation for steps on specific configuration of the clients.

We don't currently use any roles of scopes. However we do verify the aud claim in the access token. To allow this we need to enable the audience Client Mapper at the keyclaok realm level, as decribed in the section on 'Client Mappers' here.

Authorization Profiles

This is where we define how our APIs will be secured, in our case, using the Client Credentials auth flow. Our API consumers must have a Keycloak Client (Client ID and Secret are the credentials) that acts as a 'client' with a Service Account for the Client for our API itself (eg: CDOGS or CHES) that we set up in Keycloak in the previous section above.

our Authorization Profiles can be setup either in the Portal UI or by using the Portal Directory API. Calls to the Portal Directory API must be authenticated using an access token obtained using a Service Account for our namespace.

When adding an Authorization Profile using the Portal UI you can do the following:

  • choose the 'Client Credential Flow, using Client ID and Secret' option
  • Authorization
    • Mode: Automatic
    • We no longer check client claims in the token other than audience. Client Mappers > Audience should set to the ID of our API Keycloak Client (eg: CDOGS or CHES)
  • Environment:
    • Add a dev. test and prod environment
    • idp Issuer URL is like https://dev.loginproxy.gov.bc.ca/auth/realms/comsvcauth
    • Client Registration type is managed. Here you enter the Client ID and Secret of our API Keycloak Client (eg: CDOGS or CHES)

If you did want to use roles/scopes, as we were previously in CHES, you can configure this in the Portal UI as shown in this screenshot

If you need to restore our existing configuration (for Auth Profile 1 and Auth Profile 2) you can use the Portal Directory console and PUT the the JSON in the Authorization Profile file below.

Gateway Service Configuration

The Service configuration can be created using a command line utility called GWA.

Pre-requisite: You have a service account to use with GWA to connect to your Namespace on the Gateway server.

  1. Install GWA utility on your workstation

  2. Connect to your namespace from local machine using a service account for your namespace (this creates a .env file in your current Directory):

    gwa init -P --api-version=2 --namespace=<namespace> \
  --client-id=<Client ID found in portal> \
  --client-secret=<Client Secret found in portal>

  3. Craft a Kong configuration file (see example) that defines the service and its routes for each of the endpoints of your API (eg /email, /health, etc..)

    You can generate this yaml template by parsing our OpenAPI Spec. Although this can be done in one command, I found the interactive mode in GWA preferable.

    notes:

    • API spec needs to be JSON

    • GWA didn't seem to find local files.

    • API spec 3.0.2 supported, needs to be valid spec

    • the route parameter is the desired url for your api

    • the service-url is the target service. In our case it's the OpenShift service serving our node application (found in the OCP console)

    • use interactive mode - $ gwa new

    • the following is supposed to work but doesn't currently:

    $ gwa new https://cdogs-spec-online.gov.bc.ca/api/v1/api-spec.json \
  --route-host cdogs-dev.api.gov.bc.ca \
  --service-url cdogs-app-master.2250c5-dev.svc \
  --outfile=cdogs-service-dev.yaml

    The output yaml file should look like one of the saved Gateway Service Configurations files

    The process is also documented in the APS documentation

  4. Manually edit the gateway configuration

    The config automatically generated from our API spec is not complete. For example, it does not create configuration for routes to the api spec itself (/api/v1/docs) or have the Tag annotations. So typically you will want to make some manual edits to the yaml file before publishing it to Kong (step 5).

  5. Publish the gateway configuration

    gwa pg --dry-run cdogs-service-dev.yaml

  6. You can confirm your config was completed by GET all service configurations for our namespace using the Portal Directory API. Note: at time of writing response fom APi did not return the plugin configuration on routes.

The Response from the Portal Directory has been saved to a Gateway Routes file.

  1. You can verify the routes have been added using cURL request
curl https://cdogs.api.gov.bc.ca/api/v2/health/headers

Note: The configuration of the Gateway Service can also be done using requests to the Gateway Administration API (gwa-api Swagger Consolegwa-api Postman Collection)

Network Policies with OpenShift

Because our APIs are running on OpenShift, we need to create a Network Policy in the namespace for our API app to allow the Gateway's test and prod environments to route traffic to our API. The NSP's can be found in our OpenShift project namespaces (named, for example: 'allow-traffic-from-gateway-to-cdogs-master`)

See a Network Policy at the bottom of this page as an example.

Products

Each of our APIs (eg CDOGS or CHES) can be thought of as a Product. In configuration terms, a Product is the central entity that links our API Directory entry (dataset) to our Authroization Profile and Gateway Service

Products can be managed in the Portal UI but they are easier to add using the Portal Directory API. GET'ing the config will return our current Product configuration that has been saved to a Configuration file in the section below

*Note At the time of writing there was a bug in the Portal where Product environments cannot be made active. The fix was to unlink the service (which technially works) but this seems to impact our API Metrics. There is a PR to fix it here and more background info in this RocketChat thread.

Datasets

A Dataset can be thought of as metadata about our API that is displayed in the API Directory. It can be PUT and GET using APS Portal Directory API

Our current Dataset configuration and has been saved to a Configuration file in the section below

Saved Configurations

The following files amount to our Gateway configuration for the CDOGS and CHES APIs.

Return Home

⚠️ **GitHub.com Fallback** ⚠️