> For the complete documentation index, see [llms.txt](https://docs.inrupt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.inrupt.com/ess/installation/customize-configurations/customization-security/manage-cimd-client-domains.md).

# Manage CIMD Client Domain Allow List

{% hint style="success" %}
Added in version 3.5.0
{% endhint %}

The Platform Management service uses [**`INRUPT_PLATFORM_OAUTH_CLIENT_DOMAIN_ALLOW_LIST`**](https://docs.inrupt.com/ess/services/service-platform-management/access-tokens.md#inrupt_platform_oauth_client_domain_allow_list) to control which [CIMD clients](https://docs.inrupt.com/ess/services/service-platform-management/access-tokens.md#client-credentials-with-cimd) can obtain ESS Access Tokens. ESS only accepts a client whose client ID is on a host in the list. For a client on any other host, ESS rejects the token request without fetching the client's metadata document.

The allow list is empty by default, so no CIMD client can obtain a token until you add at least one host.

{% hint style="warning" %}
Adding a host to the allow list is a trust decision about every client published on that host. ESS authenticates a CIMD client, but does not review what its software does. Establish a process for approving changes to the allow list, and keep a record of each change: what changed, who approved it, when, and why. ESS does not record changes to this setting.
{% endhint %}

{% hint style="info" %}
**Not the same as `INRUPT_OPENID_CLIENT_DOMAIN_ALLOWLIST`**

The [Solid OIDC Broker](https://docs.inrupt.com/ess/services/advanced-configuration/service-oidc.md#inrupt_openid_client_domain_allowlist)'s **`INRUPT_OPENID_CLIENT_DOMAIN_ALLOWLIST`** controls which applications users can sign in to. **`INRUPT_PLATFORM_OAUTH_CLIENT_DOMAIN_ALLOW_LIST`** controls which CIMD clients can obtain tokens on their own behalf.
{% endhint %}

## Matching Rules

* ESS compares the host of the client ID with each entry. The comparison is exact and case-insensitive.
* Wildcards are not supported, and subdomains are not included: allowing `example.com` does not allow `agents.example.com`.
* If a client's metadata document uses a `jwks_uri`, its host must also be on the list.
* Enter host names only, without a scheme, port, or path.

## Example Customization

1. Go to your ESS installation directory:

   ```sh
   cd ${HOME}/ess
   ```
2. Create a **`platform-cimd-domain-allow-list.yaml`** file with the following content, listing the allowed hosts separated by commas:

   ```yaml
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: ess-platform-management
   spec:
     template:
       spec:
         containers:
         - env:
           - name: INRUPT_PLATFORM_OAUTH_CLIENT_DOMAIN_ALLOW_LIST
             value: agents.example.com,keys.example.com
           name: ess-platform-management
   ```
3. Add the file to the **`patches`** section of **`kustomization.yaml`** (i.e., step 3 of the [Applying Your Customizations](https://docs.inrupt.com/ess/installation/customize-configurations.md) procedure):

   ```yaml
   # kustomization.yaml in your ESS installation directory
   # ...  Preceding content omitted for brevity
   patches:
     - path: platform-cimd-domain-allow-list.yaml
   ```
4. Continue with the rest of the [Applying Your Customizations](https://docs.inrupt.com/ess/installation/customize-configurations.md) procedure.

Keeping this file under version control gives you a history of changes to the list.

## Remove a Host

When you remove a host from the list, ESS rejects new token requests from every client on that host. The list is checked on every request, including when a client's metadata document is cached. Tokens already issued remain valid until they expire.

Removing a host does not remove the clients' bindings to agent accounts, so adding the host back re-enables every client on it. To revoke a single client, see [Bind the Client ID to an Agent Account](https://docs.inrupt.com/ess/services/service-platform-management/access-tokens.md#step-3-bind-the-client-id-to-an-agent-account).

Token requests rejected because the host is not on the list are counted by the **`inrupt_platform_oauth_client_allowlist_rejected_total`** metric.
