Host

The !host statement creates a host role and a host resource. A host represents an application. Conjur allows an application to authenticate to Conjur and access secrets that it has permission to access.

Syntax

- !host
  id: <name>
  owner: !<kind-of-role> <role-name>
  annotations:
    <key>: <value>
  restricted_to: <network range>

Attributes

Attributes Description

Required. Identifies the host resource name and the role name.

This id becomes the last component in the host login name.

owner

Optional. If owner is not provided, a resource inherits its owner from its policy.

If owner is provided, the role that is named as owner must already exist. You can declare the owner in the current policy if the declaration appears before any statement that references it.

annotations

Custom annotations are supported.

authn/api-key: true

Custom annotations provide a way to store meta data about a resource. Annotations are useful for human users and automated processing. Conjur API calls can retrieve annotation values from the Conjur database.

restricted_to

Restricts authentication from the specified network range. This can include:

one or more IP addresses
one or more CIDR ranges

Trusted proxies must be configured before you can use this feature. For more information, see Client IP Address Sourcing.

Usage

A host represents a workload: a server, VM, job, container, application, or any other type of coded or automated actor. Each workload has an identity (host id). Using that identity, a workload can authenticate to Conjur.

While a host can represent a script, application, or microservice, we recommend using the host resource to represent the running environment for those entities, and using a layer to represent the executing entity. See Layer for an example.

After declaring a host, you can assign permissions to that host role using the !permit statement. For example, you can give a host permission to fetch a username and password to log into an infrastructure database.

More likely, you would first use the !grant statement to add the host to a layer, and manage permissions on the layer. By using layers, you can manage multiple hosts as a set, in the same way that you manage a set of users by placing them in a group.

When you load a policy that declares a host, Conjur creates credentials specific to that host. A host uses its credentials to authenticate to Conjur. See the API documentation for a description of the two-step process required for a host to authenticate to Conjur.

Additional ways to create `hosts`

There are other ways that hosts are created in addition to explicitly declaring them in policy. When these other methods are used, you can get the host ids and an API key from the tooling that created the hosts.

A Host Factory creates multiple hosts without having to declare each one individually.
The Conjur integrations, such as Ansible, VMware Tanzu, Puppet, and Kubernetes, each include tooling to automatically create hosts relevant to the integration.

Host credentials

A host's credentials are its login name and an API key/provider authentication token.

A host needs access to its credentials to authenticate to Conjur and get access to secrets.

You must ensure that the credentials are available to the host for later use. After you load the policy, you need to save the credentials manually and make sure that the host has access to these credentials.

For a host that is long-running, such as servers and VMs, the typical way to store the credentials is in a file accessible to the host. For example: /etc/conjur.identity.
For a host that can accept configuration through the environment, such as Docker containers, CI jobs, Heroku applications, use environment variables CONJUR_AUTHN_LOGIN and CONJUR_AUTHN_API_KEY.

For short-lived hosts, such as some containers, Kubernetes Pods, or temporary VMs, the Conjur Host-Factory tooling manages identity.

Host login name

A host's login name for authenticating to Conjur is a string consisting of the constant host/ followed by the host's fully qualified id.

host/fully/qualified/id

A fully qualified ID is the entire policy namespace that describes where the host is declared in the hierarchy of policy branches, omitting root. The last component is the host id attribute in the !host statement. If a host is created by a Host Factory or a Conjur integration, you must obtain the id value from those sources.

When the string is used in an HTTP request with the API, the entire string must be URL-encoded.

The following table shows examples for host login name in plaintext and URL-encoded.

Policy where host is declared	Plaintext login name	URL-encoded login name
root	`host/host-01`	`host%2Fhost-01`
root db	`host/db/host-01`	`host%2Fdb%2Fhost-01`
root prod db	`host/prod/db/host-01`	`host%2Fprod%2Fdb%2Fhost-01`

API key or Provider authentication token

Authentication mode

Description

API key

An API key is a randomly generated secret assigned by Conjur when the host is created, if so defined in the host policy. When you load policy that creates a host, the output from the load command or API request includes the API key for each host that was created.

The following sample output shows the API keys that were generated after loading a host policy that declared two hosts:

{
"dev:host:frontend/frontend-01": "33f0ppq25sy3kx1qx630b2mvth2126nscms28bk7qy3hrwdmna86fh", 
"dev:host:frontend/frontend-02": "2w7dkpv2eszx6nvgvgvy2q2z5seq6n3gk33z1fem3z7f6493dqtwhm" 
}

A user who has the appropriate permissions on a workload (host resource) can reset (rotate) the API key if it is lost or compromised. Authenticated users with appropriate permission can get the current API key value for a host using the API or Conjur CLI.

Provider authentication token

If you want your workload to authenticate to Conjur using a provider authentication token, the host policy must include relevant provider authentication details. When the workload tries to authenticate to Conjur, the workload first uses these authentication details to get an authentication token from the relevant provider. This provider authentication token is then used to authenticate the workload to Conjur.

Examples

Create a host

The following policy declares a host.

- !host
  id: www-01
  owner: !group ops-admin
  annotations:
    description: Hypertext web server
  restricted_to: [172.17.0.3, 10.0.0.0/24]

When you load the above policy, Conjur does the following:

Creates a host resource with the name www-01 whose authentication is restricted from IP 172.17.0.3 and CIDR range 10.0.0.0/24.
Creates a host role with the name www-01.
Creates and returns an API key, which the host must use to authenticate with Conjur. Any user who is a member of the group named ops-admin (the owner of this host) can get or rotate the host's API key.

If the above host declaration appears in a policy whose id is dev, the login name for the host becomes host/dev/www-01.

Add a host to a layer

The following example adds a host to a layer role. The host role inherits all privileges permitted to the layer role.

- !grant
  role: !layer all-web-servers
  member: !host www-01

Give a host access to a secret

This example declares a variable and then permits the host role named www-01 to see that the variable exists and fetch the value of that variable.

- !variable db-password

- !permit
  role: !host www-01
  privileges:
    - read
    - execute
  resource: !variable db-password

Permissions

A role needs the following privileges to perform actions on a host resource:

Privileges required to perform actions on hosts
Action	Required privileges
Declare a new `host`	`create` privilege on the policy in which the `host` is declared
Update `host` information	`update` privilege on the `host`
Rotate a `host`'s API key	`update` privilege on the `host`
Delete a `host`	`update` privilege on the `host`
Add a `host` to a `layer`	`update` privilege on the `layer`
Get `host` information	`execute` permission on the `host`
Verify if a `host id` is defined	`read` permission on the `host`

Best practices

hosts defined in a policy are generally long-lasting (static) hosts. They should be assigned to a layer using a !grant statement and managed as part of a layer.
For short-lived hosts, use a Host Factory or one of the Conjur integrations.
Assignment to layers should be the primary way for hosts to get privileges. For example, add a host to a layer, and permit the layer to access a set of variables.
For applications, microservices, and other executables, define the underlying running environment as the host, and use a layer to represent the workload and manage secrets access. For an example, see Layer.