Skip to content

Latest commit

 

History

History
116 lines (80 loc) · 6.84 KB

setting-up-a-new-consumer.md

File metadata and controls

116 lines (80 loc) · 6.84 KB

Setting up a new consumer

To enable a consumer to access our API, they need:

  • a client certificate for mutual TLS with a Subject Distinguished Name(SDN) and Common Name (CN) that matches the authorisation allow list configuration in the application
  • an API key

per environment.

Prerequisites

Create a client certificate

  1. Run the generate-client-certificate.sh script with the name of the environment and client.
make generate-client-certificate

This will output three files in the ./scripts/client_certificates directory:

  • a private key e.g. dev-nhs-client.key
  • a certificate signing request (CSR) e.g. dev-nhs-client.csr
  • a client certificate (public key) e.g. dev-nhs-client.pem

The private key and public key can be shared with the consumer. The private key must be kept secret and the public key can be shared freely.

Create an API key

Within the Cloud Platform Environments GitHub repository and the namespace of the environment:

  1. Create a branch.
  2. Add the client to the clients local in the locals.tf.

This local is used for the API key resource and for the resource to connect the API key to a usage plan, so when clients is updated, these resources will update.

  1. Commit, push and make a pull request.
  2. Wait for all the CI checks to pass.
  3. Check the Terraform plan in Concourse by following the Details link under the concourse-ci/status status check and clicking on the task plan-environments.

The changes should include the additions of a new API key and usage plan key as well as an update to the Kubernetes secret for storing our API keys.

  1. Ask the Cloud Platform team to review the pull request in their Slack channel.
  2. Once the pull request has been approved, merge it.

After some initial CI checks, a comment will be added to the pull request with a link to the Concourse run that will be performing Terraform apply to the namespace. (You'll receive an email when it's been added.)

  1. Follow the Concourse build link and check that the Terraform apply succeeds.

The API key will be automatically generated and saved as a Kubernetes secret for future reference.

You can retrieve this API key with the following command:

kubectl -n hmpps-integration-api-[environment] get secrets consumer-api-keys -o json | jq -r '.data.[client]'
# E.g. kubectl -n hmpps-integration-api-dev get secrets consumer-api-keys -o json | jq -r '.data.bob'

Configure allowed endpoints for the consumer

Add your client common name to the ./src/main/resources/application-[environment].yaml, listing the paths that the new client is allowed to consume. It is important that the name of the client matches the common name exactly.

To view the common name of the client certificate that was just generated, run:

openssl x509 -in ./scripts/client_certificates/[environment]-[consumer]-client.pem -text |grep Subject |grep CN

Send the credentials to the consumer

  1. Retrieve the API key for the new consumer using Kubectl.
kubectl -n hmpps-integration-api-<environment> get secrets consumer-api-keys -o json | jq -r '.data.<client>' | base64 -d
# E.g. kubectl -n hmpps-integration-api-dev get secrets consumer-api-keys -o json | jq -r '.data.dev' | base64 -d
  1. Using One-Time Secret and email, send the new consumer their:
    1. private key
    2. client certificate
    3. API key

Create new consumer subscriber queue

Create basic infrastructure

Within the Cloud Platform Environments GitHub repository and the namespace of the environment:

  1. Create a branch.
  2. Add new client subscriber terraform file. Example: event-subscriber-mapps.tf
  3. Rename client name "mapps" to new client name
  4. Add new client filter list secret. exmaple secret.tf
  5. Follow steps 3-8 in Create an API key to merge branch to main.

After the change is merged and applied, you can retrieve client queue name and ARN with the following command:

kubectl -n hmpps-integration-api-[environment] get secrets [your queue secret name] -o json
# E.g. kubectl -n hmpps-integration-api-dev get secrets event-mapps-queue  -o json

Using AWS secret for filter Policy

  1. Login to the AWS Console, navigate to Secrets Manager and navigate to the secret created in the previous step by search using the secret description. e.g. MAPPS event filter list Pre-prod
  2. Click on the secret and then click on Retrieve secret value. If this is your first time accessing the new secret, you will see an error Failed to get the secret value.
  3. Click on Set secret Value, and set the Plaintext value as: {"eventType":["default"]}. Setting filter to default will block subscriber receiving any messages. Event notifier will update the subscriber and AWS secret with actual filter list later.
  4. Save the change
  5. Create new Cloud Platform Environments GitHub repository branch
  6. Update terraform to load the secret value from AWS and update filter_policy value. Follow Example. Note: The name of aws_secretsmanager_secret module has to be same as the secret name created from step 4/5 above.
  7. Follow steps 3-8 in Create an API key to merge branch to main.