Machine Identity in Conjur


Conjur enables 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 policy. A machine's identity is also used when the machine is the target of an action, for example SSH access or traffic authorization.


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 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 machine identity. Depending on your use cases and environment you may use one or more.

Method Use Case


Static machines

Host Factory Auto-configured machines deployed by orchestration tools


Auto-configured machines deployed by third-party orchestration tools and integrated as hosts into Conjur.

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 Information from the 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_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 Ppublic Conjur SSL certificate -----BEGIN CERTIFICATE-----"¦

In the example above, running conjur host create redis001 after conjur host retire redis001 will result in a duplication error.