Status | Authors | Coach | DRIs | Owning Stage | Created |
---|---|---|---|---|---|
proposed |
@alberts-gitlab
@iamricecake
|
@grzesiek
@fabiopitino
|
@jocelynjane
@shampton
| devops verify | 2023-08-07 |
GitLab Secrets Manager
Summary
GitLab users need a secure and easy-to-use solution to store their sensitive credentials that should be kept confidential (“secret”). GitLab Secrets Manager is the desired system that provides GitLab users to meet that need without having to access third party tools.
Motivation
The current de-facto approach used by many to store a sensitive credential in GitLab is using a Masked Variable or a File Variable. However, data stored in variables (masked or file variables) can be inadvertently exposed even with masking. A more secure solution would be to use native integration with external secret managers such as HashiCorp Vault or Azure Key Vault.
Integration with external secret managers requires GitLab to maintain the integration with the third-party products and to assist customers in troubleshooting configuration issues. In addition, customer’s engineering teams using these external secret managers may need to maintain these systems themselves, adding to the operational burden.
Having a GitLab native secret manager would provide customers a secure method to store and access secrets without the overhead of third party tools and to leverage the tight integration with other GitLab features.
Goals
Provide GitLab users with a way to:
- Securely store secrets in GitLab
- Use the stored secrets in GitLab components (for example, CI Runner)
- Use the stored secrets in external environments (for example, production infrastructure).
- Manage access to secrets across a root namespace, subgroups and projects.
Use Cases
To help design the architecture, we need to understand how users, in their roles, would operate and use the system. Here are significant use case scenarios that can help drive our design decisions:
- As a user running a pipeline, I want a CI job to automatically fetch secrets specified in the
.gitlab-ci.yml
file. - As a DevOps engineer, I want the deployment process to fetch secrets necessary for deployment directly from GitLab Secrets Manager.
- As a DevOps engineer, I want to manually retrieve the staging database password from the GitLab Secrets Manager.
- As a project maintainer, I want to destroy all secrets in the scope of the project, when the project is being deleted.
- As a GitLab instance admin, I want to quickly rotate all runner registration tokens.
- As a FIPS compliant customer, I want GitLab Secrets Manager to encrypt/decrypt secrets using an HSM solution.
Non-functional requirements
- Security
- Compliance
- Auditability
Non-Goals
This blueprint does not cover the following:
- Secrets such as access tokens created within GitLab to allow external resources to access GitLab, e.g personal access tokens.
Decisions
- ADR-004: Use OpenBao as the secrets management service
- ADR-005: Non-hierarchical key structure for secrets in OpenBao
Superseded
These documents are part of the initial iteration of this blueprint.
- ADR-001: Use envelope encryption
- ADR-002: Use GCP Key Management Service
- ADR-003: Build Secrets Manager in Go
Proposal
The secrets manager feature will be available on both SaaS and Self-Managed installations and will consist of two core components:
- GitLab Rails
- OpenBao Server
A consumer can be:
- A user who interacts manually with a client library, API, or UI.
- An integration, for example, Vault integration on Runner.
1. GitLab Rails
GitLab Rails would be the main interface that users would interact with when managing secrets using the Secrets Manager feature.
This component is a facade to OpenBao server.
2. OpenBao Server
OpenBao Server will be a new component in the GitLab overall architecture. This component provides all the secrets management capabilities including storing the secrets themselves.
Use Case Studies
Further investigations required
- Authentication of clients other than GitLab Runner. GitLab Runner authenticates using JWT, for other types of clients, we need a secure and reliable method to authenticate requests to decrypt a secret.
- How to namespace data, roles and policies to specific tenant.
- How to allow organizations to seal/unseal secrets vault on demand.
- Infrastructure setup, including how OpenBao will be installed for self-managed instances.
- How to best implement sharing of secrets between multiple groups in GitLab.
- Establish our protocol and processes for incidents that may require sealing the secrets vault.
- How to support protected and environment specific rules for secrets.
- How to audit secret changes. Do we want to use audit socket?
- Do we want to structure project secret paths to be under namespaces to increase isolation between tenants?
- Should the secrets be revoked if a project or subgroup is moved under a different top-level group/organization?
Alternative Solutions
Other solutions we have explored:
- Separating secrets from CI/CD variables as a separate model with limited access, to avoid unintended exposure of the secret.
- Secure Files
References
The following links provide additional information that may be relevant to secret management concepts.