Key Concepts » Machine Identity
Machine Identity in Conjur Enterprise
Conjur Enterprise allows you to define users and groups and grant them privileges on resources in your environment. Authenticating and authorizing non-human actors is the other part of the puzzle. We refer to any non-human actor in your environment as a “machine”. For example, a machine can be, but is not limited to, a server in a datacenter, VM in the cloud or a Docker container. Identifying and authorizing machines is important because we delegate authority to them in automated workflows.
A machine identity is part of Conjur’s authentication ("authn") system, allowing the machine to prove to the Conjur server that it is authorized ("authz") to access secrets and execute resources as defined in a Conjur policy. A machine’s identity is also used when the machine is the target of an action, for example SSH access or traffic authorization.
Example
When a VM first starts, it runs a configuration management tool to apply configuration. Some of the configuration to be applied is placing credentials (database passwords, SSL certificates, etc). Assigning machine identity allows you to grant the VM access to fetch the credentials it needs via Conjur security policy. Credential access is recorded to an immutable audit log. Changing or revoking access to credentials does not require further system configuration.
Applying machine identity
There are different methods to apply Conjur machine identity. Depending on your use cases and environment you may use one or more.
| Method | Use Case |
|---|---|
| conjurize (part of the Conjur CLI) | Static machines configured and deployed by hand |
| Host Factory | Auto-configured machines deployed by orchestration tools |
Storing and securing machine identity
An identity exists on the host as a collection of information which can be stored in files or environment variables.
This information includes a unique identifier, a secret key, and configuration information.
Storage using files
| file | type | contains | security concerns |
|---|---|---|---|
| /etc/conjur.identity | netrc | identifier and secret key | only accessible by root |
| /etc/conjur.conf | yaml | configuration | only writable by root |
| /etc/conjur.pem | certificate | info from conjur server | only writable by root |
"/etc/conjur.identity" contains the machine’s API key and should be kept secret.
A good practice is to symlink this file from /dev/shm.
The remaining files contain no confidential information and can be shared freely.
Storage using environment variables
Machine identity can also be applied through the environment.
This is useful for tooling that accepts configuration through the environment (Docker containers, CI jobs, Heroku apps, etc).
| variable | description | example |
|---|---|---|
| CONJUR_ACCOUNT | account specified during Conjur setup | myorg |
| CONJUR_APPLIANCE_URL | Conjur HTTPS endpoint | https://conjur.myorg.com/api |
| CONJUR_AUTHN_API_KEY | host API key | sb0ncv1yj9c4w2e9pb1a2s… |
| CONJUR_AUTHN_LOGIN | host identity | host/production/redis001 |
| CONJUR_AUTHN_TOKEN | Conjur JSON access token, Base64 encoded | eyJkYXRhIjNTdjOWJkNWQ1ZDgyYTU0In0… |
| CONJUR_POLICY_ID | policy namespace (for variables) | redis-v1 |
| CONJUR_SSL_CERTIFICATE | public Conjur SSL cert | -----BEGIN CERTIFICATE-----… |
CONJUR_AUTHN_TOKEN requires CLI version 5.2.0 or greater.
Identity Lifecycle
Identities never expire, but they can be retired when they are no longer needed.
Retiring a machine identity removes all of its privileges to resources in Conjur and transfers
ownership of the identity to the attic user.
Example
$ conjur host retire redis001
Since identities are retired and not deleted, new identities cannot use the same name as retired identities. Identities should be treated as unique global identifiers.
In the example above, running conjur host create redis001 after conjur host retire redis001
will result in a duplication error.