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

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.

Retrieve the MP GitHub credentials by logging in to the AWS Modernisation Platform account with AdministratorAccess
Navigate to the Secrets Manager github_ci_user_password secret and click Retrieve secret value
Use the credentials provided to log in to GitHub
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
Click Regenerate token and then copy the token to your clipboard
Navigate to the Secrets Manager github_ci_user_pat or github_ci_user_environments_repo_pat secret and click Retrieve secret value
Click Edit and replace the token with the new one and click Save
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.
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.

Log into the Slack API
Select Modernisation Platform Alerts App Name from your apps, then choose Incoming Webhooks.
From there, click on Add New Webhook to the Workspace, and select ‘modernisation-platform’ as the channel name.
Copy the Webhook URL and replace it in both GitHub secrets and also in the secrets manager.
Navigate to the Secrets Manager slack_webhook_url secret and click Retrieve secret value
Click Edit and replace the secret value with the new one and click Save
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.
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

Log into the Azure Portal
- Navigate to Azure Portal.
- Use your justice.gov.uk credentials to sign in.
Locate the Application or Service
- Go to Microsoft Entra ID > App registrations.
- Search for the justicedigital-panda-awsidentitycenter application.
Access Certificates & Secrets
- Click on the application.
- In the left-hand menu, select Certificates & secrets.
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.
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.
Verify Functionality
- Test the application or service to confirm that it works with the new secret.
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.

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 .

This page was set to be reviewed before 22 May 2025 by the page owner #modernisation-platform. This might mean the content is out of date.