secret-operator

This project implements a token-based authentication service that integrates with Google Cloud Platform (GCP) Secret Manager to provide secure access to sensitive secrets. The service ensures a one-time-use workflow for tokens and enriches authentication with metadata.

The major use case for now is to fetch secrets from GCP Secret Manager during a cloud-init process. Therefore only a one time use token is generated and used to fetch the secrets from the cloud-init process. The token is generated by the secret-operator-client tool and is used to fetch the secrets from the GCP Secret Manager. The token is valid for 15 minutes and is removed after the first use.

---

Features

• Token-based Authentication: Secure access using time-bound, metadata-enriched tokens.
• One-Time Use Tokens: Each token is valid for only one API call and is removed after use.
• Metadata Encoding: Tokens include metadata such as:
  • serviceName: The service requesting access.
  • clientIP: The IP address of the token generator.
  • nonce: A timestamp for uniqueness.
  • randomValue: Cryptographically secure random data for unpredictability.
• Secret Filtering by Labels: GCP secrets are filtered based on predefined labels associated with the serviceName.
• Command-Line Token Generator: Generate tokens locally with metadata and security enhancements.

---

Workflow

1. Token Generation

The service provides a command-line interface (CLI) to generate tokens. Each token includes:

• Metadata such as serviceName and clientIP.
• A high-resolution timestamp (nonce) for uniqueness.
• A cryptographically secure random value to prevent token prediction.

Example:

./secret-operator-client --serviceName=my-service

Output:

The generated token is printed to stdout:

Generated Token: eyJzZXJ2aWNlTmFtZSI6Im15LXNlcnZpY2UiLCJjbGllbnRJUC...<rest_of_token>

---

2. Token Usage

Clients use the generated token to authenticate with the API. The workflow is as follows:

1. Client:

   • Generates a token with the secret-operator-client CLI.

2. Service:

   • Decodes and validates the token.
   • Extracts the serviceName and retrieves secrets associated with the service from GCP Secret Manager.
   • Returns the requested secrets in the response.
   • Invalidates the token to ensure one-time usage.

API Request Example:

POST /retrieve-secrets
Authorization: eyJzZXJ2aWNlTmFtZSI6ImR1b.....JBIn0

---

3. Metadata in the Token

Each token encodes the following metadata as a Base64-encoded JSON:

Field	Description
serviceName	The name of the service requesting secrets.
clientIP	The IP address of the machine that generated the token.
nonce	A high-resolution timestamp (nanoseconds).
randomValue	A cryptographically secure random string for additional entropy.

Example Token Metadata (Decoded):

{
  "serviceName": "my-service",
  "clientIP": "192.168.1.1",
  "nonce": 1702495430335210000,
  "randomValue": "3eLmP6K0z9eFYQkZtXvNnA"
}

---

Security Features

1. One-Time Use Tokens: Tokens are removed after their first use to prevent reuse.
2. Token Expirary: Tokens expires after 15 minutes
3. Metadata Enrichment: Includes client information and service-specific data.
4. Unpredictable Tokens: The inclusion of a nonce and random value ensures each token is unique.
5. Scoped Secrets: Secrets are filtered based on labels matching the serviceName in the token.

---

Command-Line Token Generator

The token-generator tool is a simple CLI utility for creating tokens. The generated tokens can be used directly with the authentication API.

Usage

secret-operator-client --serviceName=<SERVICE_NAME>

Example:

secret-operator-client --serviceName=my-service

Output:

Generated Token: eyJzZXJ2aWNlTmFtZSI6Im15LXNlcnZpY2UiLCJjbGllbnRJUC...<rest_of_token>

---

Future Enhancements

• Rate Limiting: Limit the number of tokens generated or used per client.
• Enhanced Logging: Add logs for token validation and secret access requests.
• Code Rerfactoring: Reduce code duplication in client and server package by moving it to shared package. Also add unit tests and try to reach test coverage of 90 %

---

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue for feature requests or bug reports.

---