For the complete documentation index, see llms.txt. This page is also available as Markdown.

Manage CIMD Client Domain Allow List

The Platform Management service uses INRUPT_PLATFORM_OAUTH_CLIENT_DOMAIN_ALLOW_LIST to control which CIMD clients 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.

Not the same as INRUPT_OPENID_CLIENT_DOMAIN_ALLOWLIST

The Solid OIDC Broker'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.

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:

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

    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 procedure):

    # 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 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.

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

Last updated