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 Use this runbook to rotate 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
Modernisation PAT MultiRepo modernisation_pat_multirepo Used in pipelines of the modernisation-platform repository. This is so that the CI user can read/write issues and read/update the github secrets AWS Secrets Manager Use this runbook to rotate the secret 180
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
AWS User access & secret keys N/A Used by IAM users which fall outside of the scope of SSO for programmatic access. EG. Collaborators, 3rd party applications AWS IAM User Access Key Create a new key pair and share with the user. Once they have confirmed the new key is in use remove the old key. 180
AWS SSO Entra ID azure_entraid_oidc Used for Microsoft Entra ID SCIM integration for AWS SSO AWS Secrets Manager Use this runbook to rotate the secret 180
Cortex Xsiam IAM User Access Key xsoar Used by the Cortex Xsiam platform to connect to Modernisation Platform Accounts. The IAM user (XsoarIntegration) is located in the MOJ Master account. AWS Secrets Manager Use this runbook to rotate the secret 180

Runbooks

GitHub MP CI User PAT or GitHub MP CI User Environments Repo PAT or Modernisation PAT MultiRepo

This runbook describes the process for rotating the github_ci_user_pat or github_ci_user_environments_repo_pat or modernisation_pat_multirepo secrets.

  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) and select the relevant token
  5. Click Regenerate token and then copy the token to your clipboard
  6. Navigate to the Secrets Manager github_ci_user_pat or 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”)

AWS SSO Entra ID

  1. Log into the Azure Portal
    • Navigate to Azure Portal.
    • Use your justice.gov.uk credentials to sign in.
  2. Locate the Application or Service
    • Go to Microsoft Entra ID > App registrations.
    • Search for the justicedigital-panda-awsidentitycenter application.
  3. Access Certificates & Secrets
    • Click on the application.
    • In the left-hand menu, select Certificates & secrets.
  4. Add a New Secret
    • Under Client secrets, click + New client secret.
    • Enter a description and select the expiration period (e.g., 6 months).
    • Click Add and copy the generated secret value immediately.
  5. Update AWS Secrets Manager
    • Navigate to AWS Secrets Manager.
    • Locate the secret named azure_entraid_oidc.
    • Click Retrieve secret value to view the current configuration.
    • Click Edit, replace the old secret value with the newly generated client secret, and click Save.
  6. Verify Functionality
    • Test the application or service to confirm that it works with the new secret.
  7. Remove the Old Secret
    • Once the new secret is fully functional, delete the old one to prevent misuse.
    • Click the Delete icon next to the old secret.

Cortex Xsiam User Account Access Key

  1. Request one of the root account admins to create a new access key for the user XsoarIntegration that is located in the MoJ Master account.
  2. Once created, add the two key values (secret ID and secret key) to the secret named xsoar that is localed in the Modernisation Platform account.
  3. Get in touch with the Monitoring and Integration Team via their team email address (see rubook doc) and confirm a new access key has been created.
  4. Share the new access keys via email, sending each of the two parts as separate emails.
  5. ** Once the Cortex Xsiam team have confirmed the new key has been applied and is working without error: **
    • Ask a root account admin to delete the old key from the IAM user.
    • Delete the old key from the xsoar secret.
This page was last reviewed on 22 November 2024. It needs to be reviewed again on 22 May 2025 by the page owner #modernisation-platform .