ADR-020 Fine-grained Personal Access Token Standards
Status
✅ Accepted
Context
The Operations Engineering (OE) team at the Ministry of Justice (MoJ) need a standard way to use Personal Access Tokens (PATs) in the moj-operations-engineering-bot account so that we can reduce risks, improve clarity, and align with best practices in token management.
Decision
For tokens created in the the moj-operations-engineering-bot account we have agreed;
- To use Fine-grained PATs (FG-PATs) as the default in accordance with industry standards and GitHub recommendations.
- Classic tokens may be created where there is a requirement for Enterprise level permissions as this out of scope of FG-PATs.
- To name the token descriptively, referencing the project where it is used, following the Token Naming Convention detailed below.
- To include in the FG-PAT description field the full organisation/repository, project name, and the GitHub secret name is it used under.
- To use the token name for the GitHub secret name with the suffix
_BOT_PATto indicate origin. - To use a token at most in a single repository. A repository may use more than one token.
- To only enable the minimum permissions required in accordance with the principle of least priviledge (POLP).
- To set an expiration date of 1 year.
✅ Token Naming Convention
This naming convention applies principally to the tokens in the moj-operations-engineering-bot account
and corresponding naming in GitHub Secrets.
The naming convention consists of three parts which should ensure uniqueness; <business_domain>_<usage>_<permission_type>
- Business domain; this should succintly describe the business domain or blobbum for which the token is created.
For example,
DORMANT_USERS,DNS,JOIN_GITHUB. - Usage; this should describe the intended use of the token within the given business domain. For example,
- When used for everything in the business domain;
GENERAL - When used for a specific tool or integration;
SENTRY,SLACK,GITHUB,TERRAFORM.
- When used for everything in the business domain;
- Permission type; this should indicate the amount of power the token wields. For example,
ADMIN,WRITE,READare clear and sufficient.
The page in the moj-operations-engineering-bot account where tokens are listed contains the full permission list
for reference. If a token’s permission level changes then its name should be updated accordingly.
When the token is stored in as a GitHub Secret in a repository it should use the same name as in
the moj-operations-engineering-bot account with the suffix _BOT_PAT to indicate origin. The name
of the secret used in the code can vary since it is identifiable from the export to environment command.
Full examples,
Name in moj-operations-engineering-bot account |
Name in GitHub Secrets |
|---|---|
DORMANT_USERS_SLACK_ADMIN |
DORMANT_USERS_SLACK_ADMIN_BOT_PAT |
DNS_OCTODNS_WRITE |
DNS_OCTODNS_WRITE_BOT_PAT |
JOIN_GITHUB_FLASK_ADMIN |
JOIN_GITHUB_FLASK_ADMIN_BOT_PAT |
Consequences
- These standards and conventions help to manage our current secrets manually.
- Facilitate progress towards managing secrets automatically (storage and rotation controlled via a secrets manager).
- Supports direction outlined in ADR-019 to enable repository secret management in Terraform.