API Clients

Overview

This page provides an overview of the identity through which requests to the Chef server are authenticated through the Server API, how the clients become registered with a valid identity, and how the API clients can be managed. See Authentication and Authorization for details on the authentication and validation process itself.

Authentication Identity

In chef, node data is separate from the identity used to authenticate requests to the Chef server, which is managed by an API client. Each API client has a public/private key pair. The public half of the key is stored in the database on the server, and the private half is kept locally by the client.

• On a node running the Chef Client, the private key is generally stored in /etc/chef/client.pem
• For an administrator using knife, the private key is generally stored in ~/.chef/USERNAME.pem

Each request to the Chef server includes a request signature in the HTTP headers. The request signature is computed from the hash of the request content and encrypted with the client's private key to verify the identity of the user or machine making the request and prevent attempts to tamper with the content.

Client Registration

When a node runs chef-client for the first time, it generally does not yet have an API client identity, and so cannot make authenticated requests to the server. This is where the validation client—named "chef-validator" by default comes in.

1. When the chef-client runs, it checks if it has a client key.
2. If the client key does not exist, it then attempts to "borrow" the validation client's identity to register itself with the server.
3. In order to do that, the validation client's private key needs to be copied to the host and placed in /etc/chef/validation.pem.

Once the client machine has registered itself with the chef server, it no longer uses the validation client for anything. It is recommended that you delete the validation client's private key from the host after the host has registered.

API clients can be managed with Knife, the Server API or the Management Console.

Managing API Clients With Knife

Knife is Chef's powerful command line tool, and can be used to create, edit, view, list, and delete API clients. Details on this use are at Managing API Clients With Knife.

Managing API Clients through the Management Console

• Open Source Chef Server users, please refer to the Managing API Clients through the Management Console article for information.
• Hosted Chef customers please refer to Managing Clients with the Hosted Chef Management Console.
• Private Chef customers should refer to the separate Private Chef Administration Documentation.

Managing API Clients through the Server API

Please refer to the Server API article for information about managing API clients through the REST API.

Making Authenticated API Requests

Anatomy of a Chef Run