diagrams

Diagrams

The C4 model is used for visualising the technical architecture of the service.

Contents

• Core diagrams
  • Context diagram
  • Container diagram
  • Component diagram
• Supplementary diagrams
  • Deployment diagram
  • Infrastructure diagram
  • Testing strategy diagram
  • Certificates diagram
  • Authentication diagram

Core diagrams

Context diagram

The context diagram provides a high-level overview of the current systems that make up HMPPS Integration API as well as those that are yet to be implemented.

Container diagram

The container diagram provides a more in-depth view of the different upstreams APIs that are used to retrieve data from the HMPPS systems such as the Prison API for NOMIS.

Component diagram

The component diagram provides an overview of our code architecture.

Supplementary diagrams

Deployment diagram

The deployment diagram provides a directional flow diagram that illustrates how the application is deployed.

Infrastructure diagram

Testing strategy diagram

Certificates diagram

Certificates are used to secure the components that make up our API.

There are two levels of authentication:

1. Mutual TLS authentication which ensures requests only come from expected consumers. This requires both the client (consumer application) and server (API Gateway) to prove their identity.
2. Client certificate authentication which ensures requests only come from API Gateway. This requires only the client (API Gateway) to prove their identity.

Mutual TLS:

1. We create a root Certificate Authority (CA) certificate and a private key.
   • We store our CA certificate (truststore.pem) in an S3 bucket in order for API Gateway to verify the identity of a consumer application.
   • We store our private key in a Kubernetes secret (api-gateway-certificate-authority) so that we can generate client certificates.
2. For the consumer application, we create a client certificate (client.pem), which includes their public key. We also create their private key (client.key).
3. We send both the client certificate (client.pem) and the private key (client.key) to the consumer application to be used for mutual TLS.

Client Certificate Authentication:

1. We use Terraform to get API Gateway to create a client certificate (apigw_client.pem), which includes their public key.
   • Behind the scenes, API Gateway also creates a private key (apigw_client.key) which we do not have access to.
2. We store the client certificate (apigw_client.pem) in a Kubernetes secret.

Authentication diagram

The following diagram shows the journey of a request that originates from a user of a consumer application to our API.

1. A user makes a request to the consumer application.
2. API Gateway presents its server certificate to the consumer application to prove its identity.
3. The consumer application verifies the server certificate with our custom domain (https://integration-api.hmpps.service.justice.gov.uk) using their public certificate authority (CA).
4. The consumer application presents its client certificate to the API Gateway to prove its identity.
5. API Gateway accesses the S3 bucket that stores the root certificate authority.
6. API Gateway uses the CA certificate to verify the consumer application’s client certificate.
7. The consumer application makes a request to API Gateway.
8. API Gateway presents its client certificate to our API to prove its identity.
9. NGINX ingress verifies API Gateway's client certificate using API Gateway's CA.
10. API Gateway forwards the request to our API.