Machine Identity

In Conjur, machines are non-human consumers of secrets, such as servers, VMs, containers, applications, microservices, Kubernetes service accounts, Ansible nodes, and other automated processes. Identifying and authorizing machines is important because we delegate authority to them in automated workflows.

Conjur provides reliable and secure identification for a machine. This identity is part of the Conjur authentication service, providing a way for the machine to prove itself for access to Conjur. Once you have that, DevOps teams can use policy to control which secrets the machine can access. Policy also manages which other users (machines and human) have access to the machine, for example, for administrative actions, SSH access, or traffic authorization.

What is an identity?

It’s a unique identifier, a secret key, and configuration information. The Identity exists as a collection of information stored in files or environment variables. The Conjur server also maintains identity information per host which is used during authentication.

Some ways to establish machine identity are: declarations in Conjur policy, using API calls, or tooling in our integrations.


Conjur uses a resource called host to represent a machine identity. A host resource is similar to a user resource (which represents a human user) in that:

  • It has its own login name (an id) and secret key (an API key). You have control over the host id. The API key is a randomly generated secret assigned by Conjur.
  • It can log in to Conjur and perform actions.
  • It can be granted roles and permissions

A host is also by default a role, which means that RBAC policy statements can grant privileges directly to the host role.

For example, here is policy that declares a host.

  - !host
      description: Hypertext web server

When you load those few lines of policy, Conjur performs quite a bit of activity, including:

  • Creates the identity for the host and stores this information.
  • Assigns an API key to the host, the secret equivalent to a user’s password.
  • Creates a Conjur resource of kind host. Hosts can be managed. Hosts can be grouped and managed together.
  • Creates a Conjur role of kind host. A role can be granted privileges to access secrets stored in Conjur. Other roles can be granted permissions on the host role to access the host.


A layer is a grouping of hosts for the purpose of managing them together, similar to a group of users. Assignment to layers is the primary way for hosts to get privileges, and also the primary way that users obtain access to hosts. For that latter purpose, users are also listed as members of a layer.

A layer consists of:

  • Hosts that belong to the layer. Hosts in the layer automatically gain the privileges granted to the layer, such the ability to fetch secret values.

  • Members are users who have privileges on the hosts in the layer. Members are automatically granted privileges on all the hosts in the layer. For example, you can streamline the management of ssh permissions on hosts by adding groups of users to a layer.

Here is the host policy we used above, with a few more lines that grant the new host all permissions already granted to the layer. The member line gives all members of the layer access to that new host.

  - !host
      description: Hypertext web server
  - !grant
    role: !layer webservers
    member: !host            * all members of the layer
                                             * can access this host

You can imagine that the webservers layer might have multiple hosts in it, with multiple administrative users or a group of users as declared members. They all have privileges to change the passwords for the hosts, rotate the API keys, or alter the policy that affects the hosts, including the ability to grant permissions for the hosts to access a secret they need. The secrets are declared elsewhere in policy as Conjur variables.

Machine Authentication to Conjur

A host needs its identity (its login name and API key) to get a short-lived signed certificate (access token) that provides access to Conjur. Conjur verifies that the access token is arriving from the machine it says it is. Only then can the host request access to secrets.

IP range limiting can be applied to specific machine and user identities to restrict authentication to specific network locations. For example, IP restrictions will prevent a malicious program or administrator from harvesting an API key from an operational server and then using it from a different network location such as a personal workstation.

Machine Authorization to Access Secrets

A major reason that a machine might authenticate to Conjur is to access a secret in Conjur. Secrets (Conjur resources of kind variables) grant permissions to hosts, layers, users, or groups that allow various levels of access, such as reading, executing (fetching the secret value), or updating.

Here are some use cases for machines needing access to secrets:

  • An application uses the Conjur API to authenticate and get a password for logging into an Oracle datbase.

  • An Ansible playbook uses the Conjur integration to authenticate, get server login credentials, and inject them into the play before starting an application.

  • A Cloud Foundry or PCF application uses the Conjur integration to authenticate, get credentials for logging into a web service, and inject the value into the environment before the application starts.

Host Factory

In situations where new machines are constantly or often generated, it could be impractical to manage individual machine identities and their relevant host policy. For example, a virtual environment is often creating new servers and new VMs; automation tools like Puppet and Chef create new hosts for each new orchestration; CF or PCF creates a machine identity for each application running in a container.

For these situations, Conjur supports a host factory service that can create multiple host identities as needed. Host factories generate host identities that authenticate separately but are managed together in a layer, automatically, with the same privileges and permissions.

Features that prevent unauthorized use of a host factory include limiting the use of Host Factory tokens by an IP range, setting tokens to expire soon after they are created, and ability to revoke a token at any time.

Applications as machines

Using the Conjur API, an application might use the following sequence to access a needed secret:

  1. Use its identity to get an access token
  2. Authenticate to Conjur
  3. Get a secret that it is authorized to get.

Our various integrations generate other methods for accessing secrets.

Machine Identity in Action

Are you ready to see more specifics about Conjur machine identity?