Skip to main content

How to Rotate Secrets

Introduction

We don’t have many secrets on stored on the Modernisation Platform, but they are rotated regularly, every 180 days.

This guide advises where secrets are stored and how to rotate them.

Name Secret Name
Useage
 Location How to rotate
property
 Days to rotate
PagerDuty Organisation Level Token pagerduty_token Used by PagerDuty Terraform to manage most PagerDuty resources AWS Secrets Manager Contact Operations Engineering to issue a new token and update the secret. 180
PagerDuty User Level API Token pagerduty_userapi_token PagerDuty api user level token, used to link services to Slack channels. A valid PD and Slack user needed (to authorise against a slack user), needed in addition to the org level token AWS Secrets Manager Log in to PagerDuty as your user, create the token and authorise it against Slack 180
PagerDuty Integration Keys pagerduty_integration_keys Map of integration keys generated and updated by Terraform PagerDuty integration resources when users create services, used to push alerts to those services AWS Secrets Manager Destroy and recreate the PagerDuty integration resource in Terraform 180
PagerDuty Modernisation Platform Team user N/A Used for dead-end notifications as all schedules need a user Not stored Use password reset process if needed N/A
Slack Webhook URL slack_webhook_url Used to post alarms to Slack AWS Secrets Manager Use this runbook to rotate the secret 180
GitHub MP CI User PAT github_ci_user_pat Used to create PRs etc in GitHub actions and deploy GitHub resources via Terraform AWS Secrets Manager Use this runbook to rotate the secret 180
GitHub MP CI User Environments Repo PAT github_ci_user_environments_repo_pat Used in reusable pipelines of the modernisation-platform-environments repository. This is so that the CI user can post comments in PRs, e.g. tf plan/apply output. AWS Secrets Manager Log in as the Modernisation Platform CI User and generate a new PAT, revoke the old one and update the secret. 180
GitHub MP CI User Password github_ci_user_password Used to log in and set the PAT AWS Secrets Manager Log in to GitHub as the user and reset the password, update the secret 180
Environment Management environment_management A Map of account names to IDs, and data for environment management, such as organizational unit IDs AWS Secrets Manager Does not need rotating, not really a secret and regenerated on each account creation N/A
Nuke ID List nuke_account_ids Account IDs to be auto-nuked on weekly basis. This secret is used by GitHub actions job nuke.yml inside the environments repo, to find the Account IDs to be nuked. AWS Secrets Manager Not really a secret, should not be rotated N/A
Nuke Block List nuke_account_blocklist Account IDs to be excluded from auto-nuke. AWS-Nuke (https://github.com/rebuy-de/aws-nuke) requires at least one Account ID to be present in this blocklist, while it is recommended to add every production account to this blocklist. AWS Secrets Manager Not really a secret, should not be rotated N/A
Circle CI ID mod-platform-circleci CircleCI organisation ID for ministryofjustice, used for OIDC IAM policies AWS Secrets Manager Not really a secret, should not be rotated N/A
ModernisationPlatformOrganisationManagement IAM user in MoJ root account N/A Used to perform limited activities in the root account. No longer used as replaced by OIDC but user kept for breakglass purposes. Not stored No active access keys, if keys or password needed contact Operations Engineering N/A
Modernisation Platform Account Root User Password N/A Only used during initial platform set up, log in prevented via SCP and no password or keys set Not stored Disable or move account to a non SCP protected OU and follow the password reset steps N/A

Runbooks

GitHub MP CI User PAT

This runbook describes the process for rotating the github_ci_user_pat secret.

  1. Retrieve the MP GitHub credentials by logging in to the AWS Modernisation Platform account with AdministratorAccess
  2. Navigate to the Secrets Manager github_ci_user_password secret and click Retrieve secret value
  3. Use the credentials provided to log in to GitHub
  4. Once logged in click on the profile icon and then Settings > Developer settings > Personal access tokens > Tokens (classic) > Generate new token (classic)
  5. Fill out the details:
    • In the Note field give the token a descriptive name e.g. "Modernisation Platform GitHub Terraform"
    • Set Expiration value to "No Expiration"
    • Set Scopes by ticking the following boxes:
      • workflow
      • admin:org (write:org | read:org | manage_runners:org)
      • user:email
      • project (read:project)
  6. Click Generate token and then copy the token to your clipboard
  7. Navigate to the Secrets Manager github_ci_user_pat secret and click Retrieve secret value
  8. Click Edit and replace the token with the new one and click Save
  9. Run the Github resources Workflow manually on the main branch. This will populate the GH secret with the value that you have just updated in AWS Secrets Manager.
  10. Wait for another workflow to run which uses the secret to confirm that the new token has taken effect successfully. (The secrets status will show as “Last used within the last week”)
  11. When you are confident the new secret is working successfully you can delete the old PAT token in GitHub

GitHub MP CI User Environments Repo PAT

This runbook describes the process for rotating the github_ci_user_environments_repo_pat secret.

  1. Retrieve the MP GitHub credentials by logging in to the AWS Modernisation Platform account with AdministratorAccess
  2. Navigate to the Secrets Manager github_ci_user_password secret and click Retrieve secret value
  3. Use the credentials provided to log in to GitHub
  4. Once logged in click on the profile icon and then Settings > Developer settings > Personal access tokens > Tokens (Fine-grained tokens) > GITHUB_CI_USER_ENVIRONMENTS_REPO_PAT
  5. Click Regenerate token and then copy the token to your clipboard
  6. Navigate to the Secrets Manager github_ci_user_environments_repo_pat secret and click Retrieve secret value
  7. Click Edit and replace the token with the new one and click Save
  8. Run the Github resources Workflow manually on the main branch. This will populate the GH secret with the value that you have just updated in AWS Secrets Manager.
  9. Wait for another workflow to run which uses the secret to confirm that the new token has taken effect successfully. (The secrets status will show as “Last used within the last week”)

Slack Webhook URL

This runbook describes the process for rotating the slack_webhook_url secret.

  1. Log into the Slack API
  2. Select Modernisation Platform Alerts App Name from your apps, then choose Incoming Webhooks.
  3. From there, click on Add New Webhook to the Workspace, and select ‘modernisation-platform’ as the channel name.
  4. Copy the Webhook URL and replace it in both GitHub secrets and also in the secrets manager.
  5. Navigate to the Secrets Manager slack_webhook_url secret and click Retrieve secret value
  6. Click Edit and replace the secret value with the new one and click Save
  7. Run the Github resources Workflow manually on the main branch. This will populate the GH secret with the value that you have just updated in AWS Secrets Manager.
  8. Wait for another workflow to run which uses the secret to confirm that the new token has taken effect successfully. (The secrets status will show as “Last used within the last week”)

Cortex Xsiam User Access Key

This runbook covers the rotation of the access key for the cortex_xsiam_user account in the Core Logging account.

  1. Email the Monitoring & Integration team via monitoring-and-integration-platform@justice.gov.uk to confirm a new key pair is being created which will need to be applied to their Cortex Xsiam system.
  2. Once they have responded confirming they are ready for the key, create a new one for the cortex_xsiam_user in the Core Logging account and email that to the named person who responded. This avoids the key being shared too widely.
  3. When the M&I team have confirmed the new key has been applied and the console shows it in use, delete the existing key.
This page was last reviewed on 22 November 2023. It needs to be reviewed again on 22 May 2024 by the page owner #modernisation-platform .
This page was set to be reviewed before 22 May 2024 by the page owner #modernisation-platform. This might mean the content is out of date.