Calling APIs

It’s likely that your Kotlin application will call other HMPPS APIs. These APIs will be secured by HMPPS Auth so you’ll need a JWT issued by the HMPPS Auth server to authenticate.

Client Credentials

HMPPS Auth uses the Client Credentials Flow to issue JWTs for calling other APIs. These client credentials are configured in the HMPPS Auth server.

The API you wish to call is the Resource Server and HMPPS Auth is the Authorization Server

Ask in Slack channel #hmpps-auth-audit-registers for some client credentials. Raise a JIRA ticket for this, there are usually examples in that channel to copy from. They’ll need a few details about your app, including which roles you need (these are the roles used to secure the APIs you want to call) and what your Kubernetes secrets are called (see Web Clients for more on secrets).

Web Clients

Once you have client credentials configured in HMPPS Auth you’ll need a Spring WebClient that uses them to call other APIs. Our Kotlin library provides an easy way to create correctly configured WebClients.

Example

A real world example illustrates the different components required to create and use an authorised WebClient.

Mapping secrets to environment variables

HMPPS Auth injects secrets into your namespace to authenticate your requests for a JWT. These secrets need mapping from Kubernetes into environment variables that your application can read. This is done in your helm values file. In this example the Kubernetes secret name is hmpps-personal-relationships-api-client-creds.

Registering a client that uses the secrets

The client that uses these secrets needs registering with Spring Security. This is done in Spring configuration properties file application.yml using the environment variables created by helm (SYSTEM_CLIENT_ID and SYSTEM_CLIENT_SECRET). Note the name of the client registration is organisations-api.

Building the web client

Finally, we build a WebClient using an extension function provided by our Kotlin library called authorisedWebClient. Note that it references the client registration organisations-api we defined above.

Using the web client

Now you can inject your WebClient into other services to call the API.

Integration Testing

When integration testing you’ll probably want some kind of mock server to provide data from 3rd party APIs you call with your Web Client.

A common pattern we use is a Wiremock extension to stub such data. There’s an example in the Kotlin template which is used for the /health integration tests.

There are probably more sophisticated ways to achieve this nowadays but it’s simple and it works.