Host Factory

When a client starts a new long-lived VM or server, Conjur needs to be instructed to create it as a new application and apply the appropriate policies. Host Factory is an easy, safe and secure way to do this. It runs as a service on Conjur and provides a management API for limited-time tokens, then acts on a token holder to create new applications in Conjur and add them to a layer.

What problems does Host Factory solve?

Conjur is flexible enough to manage security policies in many ways. The owner of the new applications can set permissions on them in policy. However, that strategy doesn't scale to a large number of services with diverse policies and lifecycles. Removing the dependency on a human operator to correctly apply policies to each new application is an effective way to improve safety and compliance.

Host Factory makes it easy to control policies and maintain consistency. Applications (hosts) inherit the policy of the layer they belong to, and Host Factory allows authorized users and services to create a new application (host) and add it to the appropriate layer.

Grouping application into layers allows the operator to maintain a consistent policy for every application on the layer. They can also allow specific users and automated processes to add new applications to the layer without giving permission to see or tamper with other applications on that layer. When a new service is created, its policy is applied according to its semantic meaning, represented by membership in a layer, without the client needing to remember to perform this step or have knowledge of the current policy.

Host Factory solves the problem by making this safe, automatic, and scalable.

How does Host Factory work?

During preparation to start new servers and VMs, the operator creates a layer to which these new applications will belong and applies a policy to that layer which includes a Host Factory. They use the factory to generate one or more Host Factory tokens, each of which is represented by a random string of characters. The operator communicates the tokens securely to the person or service that will be creating the new servers and VMs. The Host Factory token has an expiration date which a policy can specify, allowing the factory to create short-lived tokens for individual jobs or long-lived ones for repeated use.

When starting a new server or VM, a client must provide it with a valid token which it will in turn send to the Host Factory. The Host Factory validates the token and responds with a new application identity for the server or VM. This application identity is automatically added to the layers that are defined in the Host Factory. Host Factory tokens can be provided to new applications via automation tools such as Puppet, and CloudFormation.

To create an application using a Host Factory, a client does not have to authenticate with Conjur in the normal way (via login name + API key). Rather, the client presents a token associated with a single Host Factory. Because it has such a specific use, a Host Factory token is the most secure way to authorize scripts and code to create applications.

How is Host Factory secured?

To operate securely, the Host Factory uses unforgeable limited-time tokens and address (CIDR) restrictions.


The administrator of the Host Factory creates tokens which then must be presented in order to operate it. The tokens are unforgeable; only the operator can create them, and each one is new and unique. Expired tokens are of no use. Furthermore, tokens can be revoked at any time, and each token has an expiration date after which it automatically expires.

In order for this security system to work, the operator must communicate the tokens securely to clients using TLS. Tokens do not need to be retained on disk after use, and should not be transmitted or stored in plaintext.

Address restrictions

Typically, clients do not need to be able to create new applications from arbitrary machines. In this case, the operator can add an extra layer of security to the Host Factory token by adding a CIDR restriction. Only clients with matching addresses will be able to use the token to create new applications.

Bootstrapping application identity

For an application to automatically obtain an identity in Conjur, a Host Factory token must be made available to the application. Host Factory provides several features to ensure that the token cannot be misused. Depending on your organization security policy, you may choose to use some or all of these features. Following is a guide to bootstrapping applications with Host Factory tokens, starting with the default security protections and followed by additional lock-down measures.

Long-lived tokens

When a Host Factory token is created, an expiration date must be specified. However, this expiration date can be far in the future.

$ conjur hostfactory create token -i myfactory -d 365

Creating a long-lived Host Factory token gives you flexibility in how you distribute the token to applications. Storing the token in a trusted location that your applications can reach may already be an established distribution pattern for your organization. For example, you can distribute the token with config management tooling like Puppet. In AWS, the token can be encrypted with KMS, stored in S3, and used by instances according to their IAM role and instance profile.

A Host Factory token always creates applications in exactly the layers specified during its Host Factory creation. The layer(s) granted to new applications by the Host Factory cannot be changed after creation. If a long-lived token is compromised, the effect of that compromise is limited to only the associated layers in your infrastructure.

CIDR-restricted tokens

If you have known network subnets that applications enter, you can limit use of Host Factory tokens by an IP range. Unless the request carrying the token originates from the specified IP range, Host Factory will return "401 Unauthorized" and will not create the new application or add it to a layer.

$ conjur hostfactory create token -i myfactory -d 365 --cidr

CIDR restriction is an enhancement to Host Factory that adds security at the network level. Note that the CIDR of a token cannot be changed after its creation.

Short-lived tokens

To further prevent unauthorized use, Host Factory tokens can be set to expire soon after they are created. As illustrated in the following script, a token can be created with a short duration, rotated and pushed to a secure store automatically. Run every 12 hours, this script will refresh the token applications use to bootstrap into layers.


$ conjur hostfactory create token -i myfactory -h 12 -t 

"¦ # Push new token to a secure store


Tokens can also be revoked at any time, regardless of their expiration timestamp. Revoked tokens cannot be restored for further use.

$ conjur hostfactory revoke token -i myfactory  -t <token>

Encrypted tokens

Tokens can also be encrypted in storage and decrypted by the application to be bootstrapped. Client data or a service like Amazon KMS can be used for encryption.

Here is a summary of the KMS workflow:

  1. Create a Host Factory token.
  2. Encrypt the token with KMS.
  3. Store the encrypted token in S3.
  4. For each Conjur layer, create an IAM role that allows S3 bucket access and KMS decryption.
  5. Assign corresponding IAM roles to EC2 instances.
  6. When a new instance starts, it pulls the encrypted token from S3, decrypts it and obtains identity.

Known client data, reported by tools like Ohai or Facter, can also be used to encrypt Host Factory tokens. Identifying sets of client data that can map to privileged layers is the critical step in this workflow.

Non-privileged tokens

An alternative workflow is to establish application identity and grant privilege with two separate operations. This simplifies establishing identity for new and existing applications by placing them in a layer that has very limited privileges. Once applications are identified, they can be added to privileged layers by manual or automatic processes that best fit your organization.

Host Factory tokens for unprivileged layers are not as sensitive because they are used only for application enrollment and not to obtain privileges.

Here is a summary of the process to create non-privileged tokens:

  1. In policy, create a special-purpose group to act as the initial owner of the unprivileged layer, the Host Factory, and the applications (host) in the layer (layer).

  2. Also in policy, create the layer and the Host Factory. Layer membership and application ownership can be modified later as required.

  3. Use the Conjur CLI to create tokens:

    $ conjur hostfactory create token -i myfactory  -d 365 -t 

    This token can now be used to create application identities that hold no privileges.

    Moving these identities to a privileged layer grants the layer's privileges to the applications. In Conjur, an application can be a member of any number of layers at the same time.

Operational details

Each Host Factory is configured to construct new hosts and add them to a fixed set of layers.

Each Host Factory acts as a distinct Conjur role, which is specified when the Host Factory is created. All hosts created by the Host Factory will be owned by this designated role.

Once a host creation request is received and authorized, the Host Factory assumes the designated role and begins carrying out the host creation process.

First, the host is created, using a unique host id chosen by the client. The client can also specify an existing host id. In this case, the Host Factory attempts to rotate the API key of the host and returns the new API key to the client.

Once the host is found or created, it is added to a fixed set of layers. These layers are specified when the Host Factory is created, and the Host Factory role must be authorized to add hosts to these layers. Define the Host Factory in a declarative security policy.


Permission to use the Host Factory (to view details, create tokens, and revoke tokens) can be granted through privilege authorization on the Host Factory. As always, the owner of the Host Factory has full control.

Host Factory tokens can be created at any time, by any role that has execute privilege on the Host Factory resource. Host Factory tokens can be revoked by any role that has update privilege on the Host Factory resource.