Generate an application key and a signed config file for self enrollment

To enroll nodes with Chef 360 Platform using self enrollment, you must submit an application key ID and the application key’s signed config file as arguments. This page explains how to create an application key and signed config file.

Application key requirements

You must create the application key using the node-manager role.
When specifying values for allowedPlatforms, ipCIDRs, ipRanges, and macAddresses in the application key, they must be a subset of the corresponding values defined for the cohort. This ensures the application key remains valid and aligned with the cohort’s configuration.

Create an application key

To create an application key, follow these steps:

Create a JSON file that defines the application key:
```
{
  "name": "<APPLICATION_KEY_NAME>",
  "description": "<APPLICATION_KEY_DESCRIPTION>",
  "type": "enrollment-cli",
  "roleId": "9af80df5-12cf-4950-a405-999124584152",
  "cohortId": "<COHORT_ID>",
  "expiryAt": "<EXPIRY_AT>",
  "allowedPlatforms": "<ALLOWED_PLATFORMS>",
  "ipCIDRs": "<IP_CIDRS>",
  "ipRanges": "<IP_RANGES>",
  "macAddresses": "<MAC_ADDRESSES>"
}
```
Replace the following:
- <APPLICATION_KEY_NAME>: the name for the application key.
- <APPLICATION_KEY_DESCRIPTION>: the application key description.
- <COHORT_ID>: the cohort ID to associate with the application key. If you plan to provide the cohort’s UUID at the time of self-enrollment or enter a specific UUID to bind the key to a particular cohort in advance, you can use an asterisk (*) as a wildcard.
- <EXPIRY_AT>: an application key expiration date and time in ISO 8601 format. For example, 2025-05-20T04:05:06Z.
- <ALLOWED_PLATFORMS>: a comma-separated list of allowed platforms. For example, linux. Supported values: windows, linux, or * to allow all platforms.
- <IP_CIDRS>: a comma-separated list of CIDR blocks. For example, 192.168.0.0/24. Use * to allow all CIDR blocks. Only CIDR blocks present in the network configuration values in the machine are supported.
- <IP_RANGES>: Comma-separated list of IP address ranges or individual IP addresses. Use both IPv4 and IPv6 formats. For example, 192.168.0.1-192.168.0.40,192.168.0.50,2001:0db8:85a3:0000:0000:8a2e:0370:7335. Use * to allow all IP ranges. Only IP addresses or ranges present in the network configuration values in the machine are supported.
- <MAC_ADDRESSES>: Comma-separated list of MAC addresses. For example, 00:11:22:33:44:AA,00:11:22:33:44:FE. Use * to allow all MAC addresses.

Create the application key with the user-account applicationkey create-applicationKey subcommand:

chef-platform-auth-cli user-account applicationkey create-applicationKey \
  --body-file <PATH_TO_APPLICATION_KEY_DEFINITION_FILE> \
  --profile <PROFILE_NAME>

The response is similar to the following:

{
  "item": {
     "id": "550e8400-e29b-41d4-a716-446655440000",
     "name": "application key name",
     "description": "description of application",
     "expiryAt": "2025-05-20T04:05:06Z",
     "enabled": true,
     "cohortId": "550e8400-e29b-41d4-a716-446655440000",
     "roleId": "9af80df5-12cf-4950-a405-999124584152",
     "ipRanges": "192.168.0.1-192.168.0.40, 192.168.0.50-192.168.0.90",
     "ipCIDRs": "192.168.1.1/24,192.168.1.2/24",
     "macAddresses": "00:11:22:33:44:AA,00:11:22:33:44:FF,00:11:22:33:44:AA,00:11:22:33:44:AB",
     "allowedPlatforms": "windows,linux",
     "type": "enrollment-cli"
  }
}

Save the application key ID. You’ll use it to create the signed config file and when you enroll nodes with the chef-node-enrollment-cli CLI.

Create a signed config file

To create a signed config file for an application key, rotate the credentials for the application key using the user-account applicationkey rotate-applicationKey subcommand:

chef-platform-auth-cli user-account applicationkey rotate-applicationKey \
  --applicationKeyId <APPLICATION_KEY_ID> \
  --profile <PROFILE_NAME>

By default, the CLI command saves the signed config file as application_config_file.txt in your current directory. You can change the output filename using the --file-name flag.

Save the signed config file. You’ll submit this file to the chef-node-enrollment-cli CLI when enrolling nodes.

Update an application key

To update an application key, follow these steps:

Create a JSON file with the fields you want to update. For example:
```
{
  "name": "<APPLICATION_KEY_NAME>",
  "description": "<APPLICATION_KEY_DESCRIPTION>",
  "type": "enrollment-cli",
  "roleId": "9af80df5-12cf-4950-a405-999124584152",
  "cohortId": "<COHORT_ID>",
  "expiryAt": "<EXPIRY_AT>",
  "allowedPlatforms": "<ALLOWED_PLATFORMS>",
  "ipCIDRs": "<IP_CIDRS>",
  "ipRanges": "<IP_RANGES>",
  "macAddresses": "<MAC_ADDRESSES>"
}
```
Replace:
- <APPLICATION_KEY_NAME> with a name for the application key.
- <APPLICATION_KEY_DESCRIPTION> with a description for the application key.
- <COHORT_ID> with the ID of the cohort that nodes will be enrolled in or an asterisk (*) as wildcard if you plan to provide the cohort’s UUID at the time of node enrollment.
- <EXPIRY_AT> with the application key’s expiration date and time in ISO 8601 format. For example, 2025-05-20T04:05:06Z.
- <ALLOWED_PLATFORMS> with a comma-separated list of allowed platforms. For example, linux. Supported Platform fields: windows, linux. You can also use * to allow all platforms.
- <IP_CIDRS> with a comma-separated list of CIDR blocks. For example, 192.168.0.0/24. You can also use * to allow all CIDR blocks. Only CIDR blocks present in the network configuration values in the machine are supported.
- <IP_RANGES> with a comma-separated list of IP address ranges or individual IP addresses. You can use both IPv4 and IPv6 formats. For example, 192.168.0.1-192.168.0.40,192.168.0.50,2001:0db8:85a3:0000:0000:8a2e:0370:7335. You can also use * to allow all IP ranges. Only IP addresses or ranges present in the network configuration values in the machine are supported.
- <MAC_ADDRESSES> with a comma-separated list of MAC addresses. For example, 00:11:22:33:44:AA,00:11:22:33:44:FE. You can also use * to allow all MAC addresses.
Update the application key with the user-account applicationkey update-applicationKey subcommand:

chef-platform-auth-cli user-account applicationkey update-applicationKey \
  --applicationKeyId <APPLICATION_KEY_ID> \
  --body-file <PATH_TO_UPDATE_FILE> \
  --profile <PROFILE_NAME>

The response confirms the updated application key details.

Troubleshooting

Use the user-account applicationkey get subcommand to verify that an application key was created or updated:

chef-platform-auth-cli user-account applicationkey get-applicationKey \
  --applicationKeyId <APPLICATION_KEY_ID> \
  --profile <PROFILE_NAME>