Retrieve shared credentials from AWS Secrets Manager
⚠️ To keep GOV.UK secure, please do not create new shared credentials or shared user accounts.
For any new service, all human users should have individual accounts and these should be linked to the person’s identity via single-sign-on.
If in doubt, ask govuk-platform-engineering@.
Sharing user accounts is bad for security and you must avoid doing so where possible. Sometimes shared accounts are unavoidable, for example where a legacy application lacks support for single-sign-on.
In cases where shared credentials are a necessary evil, we use AWS Secrets Manager to control access to them. This is the same system that we use for machine-readable secrets.
Retrieve a credential from Secrets Manager
- Log into the production AWS account. You’ll need to assume the admin role (
govuk-production-admin). - Choose Secrets Manager from the Services menu.
- Search for
2ndline. - Choose the credential that you need.
- Under Secret value, choose the Retrieve secret value button on the right-hand side.
You can also access Secrets Manager via AWS CLI commands, for example aws secretsmanager get-secret-value.
Set up OTP from 2FA seed
Some of our ‘secrets’ are for shared accounts which require 2FA to log in. They may have a “2fa-seed” part of the secret that looks a bit like this: otpauth://totp/YOUR_IDENTIFICATION?secret=YOUR_SECRET.
You can get a One-Time-Password by copying and pasting the secret (YOUR-SECRET in the example above) into totp-cli (installed via brew install totp-cli):
totp-cli instant
# paste the secret, hit Enter
The above approach requires getting the secret from Secrets Manager every time you want to log into the shared account.
Rotate a credential
Retrieve the credential, then press Edit.
Further information
For any further detail about using Secrets Manager, see the inline documentation in the AWS console or the User Guide.
Rationale for Secrets Manager
Secrets Manager replaced the previous govuk-secrets shared password store in February 2024. Using Secrets Manager gives us:
- a durable audit trail, so in a security event we can at least find out retrospectively all the times any given item was accessed and by whose IAM credentials
- access control via our existing IAM roles, so access is updated automatically for leavers and joiners, which eliminates error-prone manual processes
The Secrets Manager user interface is not primarily designed for this use case of a shared password store for teams, but it’s arguably no worse than govuk-secrets was.