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

id:

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.

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 hostrepresents an application: a server, VM, job, container, or any other type of coded or automated actor. Each application has an identity (host id). Using that identity, an application 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 Host 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 obtain the host ids and API keys 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.

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`

Host API key

The API key is a randomly generated secret assigned by Conjur when the host is created. 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.

Here is example output from a policy load that declares two hosts:

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

A user who has the appropriate permissions on a 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.

A host needs access to its credentials to authenticate to Conjur and get access to secrets. You must ensure that the host credentials are available to the host for later use by saving the credentials on the host.

Saving the credentials is a manual process after loading the policy on the command line, or if using the API, another step in your application. Save identity in files or in environment variables.

For host that are long-running, such as servers and VMs, the typical way to store the host credentials is in a file accessible to the host. For example: /etc/conjur.identity.

For hosts 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.

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

Actions on a host resource require the following permissions.

To perform these actions...	A role needs these 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 application and manage secrets access. See Host for an example.