Add ADR-0005: Machine credentials #5
Conversation
🤖 Assisted with GitHub Copilot (via Zed) Signed-off-by: Eric Searcy <[email protected]>
There was a problem hiding this comment.
Pull Request Overview
This PR introduces an Architecture Decision Record (ADR-0005) that establishes formal guidelines for managing machine credentials within the organization. The decision addresses the security challenges of non-interactive authentication by mandating IP restrictions, automated rotation, and credential-free alternatives where possible.
Key Changes
- Establishes a formal definition of machine credentials and their associated risks
- Mandates use of credential-free alternatives (OIDC, native service roles, marketplace integrations) when available
- Requires IP restrictions to LF-entitled ranges or automated rotation every 2 months for unrestricted credentials
- Recommends Private Key JWT authentication over client secrets for OAuth2 implementations
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
| - The runtime environment of the component(s) the credentials represent. | ||
| - VPN subnets of workstations of authorized LF staff, where the VPN uses phishing-resistant MFA for user authentication. | ||
|
|
||
| When possible, and there is no granular, LF-entitled IP range, machine credentials SHOULD by restricted to service-wide SaaS provider IP ranges. |
There was a problem hiding this comment.
Corrected spelling of 'by' to 'be'.
| When possible, and there is no granular, LF-entitled IP range, machine credentials SHOULD by restricted to service-wide SaaS provider IP ranges. | |
| When possible, and there is no granular, LF-entitled IP range, machine credentials SHOULD be restricted to service-wide SaaS provider IP ranges. |
There was a problem hiding this comment.
Overall, I approve. I would like to see additional requirements on auditing and compliance. As mentioned in a previous comment (and further elaborating here):
- All machine-to-machine token usage should be recorded in an audit log. Keep audit log entries for a period of N days (e.g., 90 days).
- All machine-to-machine token credential rotation should be recorded in an audit log. Keep audit log entries for a period of N days/months (e.g., 12 months).
- A {timeline, e.g. weekly} report containing 1. (informational) recently rotated credentials, 2. (near-term) upcoming rotations, and 3. (actionable now) expired credentials should be auto-generated and shared with the Operations team.
|
|
||
| As such, this decision requires teams to: | ||
|
|
||
| - Audit existing machine credential usage and implement IP restrictions where possible (and where not already implemented). |
There was a problem hiding this comment.
We should have unilateral machine credential usage audit logs.
There was a problem hiding this comment.
Also, we should have an audit log of when credentials are rotated. This should be a requirement, regardless of context.
There was a problem hiding this comment.
@AlanSherman what do you think about this?
Machine credential usage would ordinarily be part of the audit logs of the various validating parties ... GitHub PAT usage in GitHub audit log, Auth0 M2M usage in Auth0 logs, etc. Then again, there could be gaps ... like, does Zoom provide an audit log? Do all our providers' audit logs flow into Datadog SIEM so that we can actually capture trends or take action?
Or, do we track secret consumption itself, like k8s audit logs for secret fetches? (Or similar for AWS Secrets Manager and SSM SecureValues, for non-k8s infra?)
For rotation ... I left this spec agnostic with respect to the rotation mechanism, but should we make reference to LFX Secrets Management as mandatory for all rotations, even manual, non-automated rotations? (if the source 1P vault has changed, so the secret is being re-propagated out to app-connected vaults, we would log it, right?)
No description provided.