User and Machine Identities
Learn more about identities to interact with resources in Hanzo KMS.
To interact with secrets and resource with Hanzo KMS, it is important to understand the concept of identities. Identities can be of two types:
- People (e.g., developers, platform engineers, administrators)
- Machines (e.g., machine entities for managing secrets in CI/CD pipelines, production applications, and more)
Both people and machines are able to utilize corresponding clients (e.g., Dashboard UI, CLI, SDKs, API, Kubernetes Operator) together with allowed authentication methods (e.g., email & password, SAML SSO, LDAP, OIDC, Universal Auth).
Learn more about the concept on user identities in Hanzo KMS.
Understand the concept of machine identities in Hanzo KMS.
Calculating Identity Counts
Understanding how to calculate your identity requirements helps with capacity planning and licensing.
User Identities
User identity count is straightforward—it equals the number of human users who need access to Hanzo KMS. This includes developers, DevOps/platform engineers, security administrators, and any other team members requiring direct Hanzo KMS access.
User identities map 1:1 with people. If you have 50 engineers who need Hanzo KMS access, that's 50 user identities.
Machine Identities
If you're familiar with cloud provider IAM concepts, Hanzo KMS machine identities work the same way:
| Cloud Provider | Equivalent Concept |
|---|---|
| AWS | IAM Roles |
| GCP | Service Accounts |
| Azure | Service Principals |
| Kubernetes | ServiceAccounts |
Just as you don't create a new IAM role for every EC2 instance or a new service account for every VM, you don't create a new Hanzo KMS machine identity for every machine. Instead, machine identities are permission-based, not machine-based—they represent a unique set of access permissions that can be shared across multiple workloads.
Key principle: If multiple machines require identical permissions to the same secrets, they share a single machine identity—just like multiple EC2 instances can assume the same IAM role.
How to Calculate Machine Identities
Consider these factors when determining your machine identity count:
| Factor | Impact on Identity Count |
|---|---|
| Unique permission sets | Each distinct combination of project access + environment access + secret paths = 1 identity |
| Number of machines | Does NOT directly increase identity count if permissions are identical |
| Authentication methods | A single identity can authenticate via multiple methods (AWS IAM, Kubernetes, GCP, Azure, etc.) simultaneously |
Examples
Scenario: 10 VMs in your production environment all need read access to the same database credentials in prod/database/*.
Machine identities needed: 1
All VMs share the same permission requirements, so they authenticate using a single machine identity. This is equivalent to having 10 EC2 instances assume the same IAM role.
Scenario: You have application servers for staging and production, each needing access to their respective environment's secrets.
Machine identities needed: 2
- 1 identity for staging servers → access to
staging/* - 1 identity for production servers → access to
prod/*
Even if you have 20 staging servers and 50 production servers, you only need 2 identities—just as you'd have separate IAM roles for staging vs. production access.
Scenario: Your CI/CD system has:
- Build pipelines that need read access to artifact registry credentials
- Deployment pipelines that need read access to cloud provider secrets and database URLs
- Security scanning pipelines that need access to scanning tool API keys
Machine identities needed: 3
Each pipeline type has distinct permission requirements, warranting separate identities.
Scenario: Your application runs across AWS EKS, GCP GKE, and Azure AKS, but all clusters need identical access to the same secrets.
Machine identities needed: 1
A single machine identity can have multiple authentication methods configured simultaneously. You would attach AWS IAM Auth, GCP IAM Auth, and Azure Auth to the same identity, allowing workloads from any cloud to authenticate to the same permission set.
Scenario: You have 15 microservices:
- 10 services need access only to shared infrastructure secrets (Redis, message queue)
- 3 services need access to payment processing secrets
- 2 services need access to third-party integration API keys
Machine identities needed: 3
Group services by their secret access requirements, not by the number of service instances or replicas.
Best Practices
While consolidating machine identities reduces management overhead, more granular identities provide stronger security through least-privilege access and reduced blast radius. The right balance depends on your security requirements.
When to Use Separate Identities
Create distinct machine identities to enforce security boundaries between:
| Boundary | Why Separate? |
|---|---|
| Different applications | Prevents one compromised app from accessing another app's secrets |
| Security tiers | Payment processing, PII handling, and general app secrets should be isolated |
| Trust levels | Internal tools vs. customer-facing services vs. third-party integrations |
| Compliance scopes | SOC 2, PCI-DSS, or HIPAA-regulated workloads may require isolation |
Blast radius consideration: If a machine identity is compromised, an attacker gains access to everything that identity can access. Design your identity boundaries around "what's the worst case if this credential leaks?"
When Consolidation is Acceptable
Sharing a machine identity across workloads is appropriate when:
- Replicas of the same application — Multiple pods/instances running identical code with identical secret needs
- Stateless workers — Horizontally scaled workers performing the same job
- Tightly coupled services — Services that are deployed together and share a security boundary
Kubernetes Best Practices
For Kubernetes environments, we recommend mapping machine identities at the namespace level:
Create a machine identity for each Kubernetes namespace that needs secrets. This aligns with Kubernetes' native isolation model and simplifies RBAC management.
Use Kubernetes Auth to bind machine identities to specific ServiceAccounts and namespaces. This ensures only pods in the authorized namespace can authenticate.
When using the KMS Agent Injector or Operator, configure namespace-scoped access rather than cluster-wide permissions.
Scenario: You have a shared Kubernetes cluster with three teams, each with their own namespace:
team-payments— handles payment processingteam-platform— runs shared infrastructure (API gateway, service mesh)team-analytics— runs data pipelines
Recommended approach: 3 machine identities
| Identity | Namespace | Access |
|---|---|---|
k8s-payments | team-payments | Payment secrets only |
k8s-platform | team-platform | Infrastructure secrets only |
k8s-analytics | team-analytics | Analytics pipeline secrets only |
This ensures that a compromised pod in team-analytics cannot access payment processing credentials, even if an attacker gains cluster-level access.
Quick Assessment Questions
When planning your machine identity strategy, consider:
- What's the blast radius? If this identity is compromised, what secrets are exposed? Design boundaries to limit damage.
- Are these workloads in the same trust boundary? Applications that shouldn't access each other's data need separate identities.
- What are your compliance requirements? Regulated workloads may require documented isolation from non-regulated systems.
- What's your authentication topology? A single identity can authenticate from multiple sources (Kubernetes + AWS IAM + GCP), so multi-cloud doesn't necessarily mean multiple identities—but multi-tenant does.
Bottom line: When in doubt, err on the side of more identities. The operational overhead of additional identities is minimal compared to the security benefits of proper isolation.
How is this guide?
Last updated on