Best Practices for Service Accounts¶
Credential Management¶
Treat client_secret as a secret. The secret is shown only once at creation and once on each regeneration. Store it in a secrets manager (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, etc.) immediately. Never store it in source code, configuration files checked into version control, or CI/CD environment variables that are logged.
Regenerate secrets periodically. Rotate secrets on a regular schedule and whenever a secret may have been exposed. After regeneration, update the secret in your secrets manager before the old sessions expire.
Set an expiry date. For accounts tied to a specific project, team, or time-bounded integration, configure an expiry date. Expired accounts are automatically rejected without manual intervention.
Access Control¶
Apply the principle of least privilege. Assign only the scopes needed for the intended use case:
| Use case | Recommended scope |
|---|---|
| CI/CD policy validation only | read |
| IaC pipeline managing policies | write |
| Administrative automation | admin |
Avoid granting admin scope unless the integration genuinely requires administrative operations.
Restrict by IP address. Configure an IP allowlist whenever the calling system has a stable IP or CIDR range. This limits the impact of a compromised credential to traffic from the allowed range. Use CIDR notation for ranges rather than listing individual IPs.
One account per integration. Create separate Service Accounts for each distinct system or pipeline rather than sharing credentials. This limits blast radius if a secret is compromised, and makes audit logs easier to attribute.
Session Handling¶
Revoke sessions when no longer needed. In short-lived automation (CI pipelines, one-off scripts), call POST /api/v1/service-account/auth/revoke at the end of the job to invalidate the session immediately rather than waiting for the 24-hour TTL to expire.
Cache session tokens within a job. Within a single pipeline run, authenticate once and reuse the token. Authenticating on every API call creates unnecessary load and audit log noise.
Verify the session before long-running jobs. If a pipeline may run for an extended period, call GET /api/v1/service-account/auth/verify near the start to confirm the token is still valid before performing operations that depend on it.
Policy Management¶
Test policies with the validate endpoint before enabling them. Use POST /api/v1/service/policies/validate to dry-run a certificate request against a new policy before setting is_enabled: true. This prevents misconfigured policies from unexpectedly blocking legitimate certificate requests.
Use soft-fail rules during roll-out. When introducing a new policy rule, set "fail": "soft" initially so violations appear as warnings rather than blocks. Monitor warnings in the audit log before switching to "fail": "hard".
Prefer specific matching criteria. Scope matching_criteria.domains to the exact domains and subdomains the policy should govern. Overly broad domain patterns can apply policies to certificates they were not intended to cover.
Monitoring and Auditing¶
Review the audit log regularly. Service Account authentication events, policy changes, and validation results are all recorded. Periodic review helps detect unexpected usage, such as authentications from unexpected IPs or policy changes made outside of approved pipelines.
Alert on authentication failures. Repeated INVALID_CREDENTIALS or IP_NOT_ALLOWED errors may indicate a misconfiguration, a compromised credential being tested, or an integration pointing at the wrong account. Configure alerting on these events where possible.
Disable rather than delete inactive accounts. Disabling an account suspends access while preserving the audit history. Delete only when you are certain the account and its history are no longer needed.