From bb0824723d7a32a0c7dead7728ac9537856584f7 Mon Sep 17 00:00:00 2001
From: Sviatoslav Likhtarchyk <Sviatoslav_Likhtarchyk@epam.com>
Date: Fri, 3 Jul 2026 15:33:59 +0300
Subject: [PATCH] docs(config): document authorized apps public key domain
 allowlist (epmcdme-13325)

## Summary
Document the new AUTHORIZED_APPS_ALLOWED_KEY_DOMAINS setting that restricts
which domains authorized-application public_key_url entries may point at.

## Changes
- add Public Key URL Domain Allowlist section under Authorized Applications Configuration
- document validation rules (https-only, no IP literals, subdomain matching, fail-closed empty default)
- update the example public_key_url to a placeholder domain
---
 .../codemie/api-configuration.md              | 23 ++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/docs/admin/configuration/codemie/api-configuration.md b/docs/admin/configuration/codemie/api-configuration.md
index a8302ca3..00ab824d 100644
--- a/docs/admin/configuration/codemie/api-configuration.md
+++ b/docs/admin/configuration/codemie/api-configuration.md
@@ -927,7 +927,7 @@ External applications that can access CodeMie APIs via JWT authentication are co
 ```yaml
 authorized_applications:
   - name: app-name # Application identifier
-    public_key_url: https://app.com/.well-known/public-key # JWT verification key URL
+    public_key_url: https://app.trusted.example/.well-known/public-key # JWT verification key URL, must use https and match an allowed domain
     # OR
     public_key_path: /path/to/public/key.pem # Local public key file
     allowed_resources: # Permitted resource types
@@ -946,6 +946,27 @@ Control granular access to CodeMie resources:
 - `USER` - User profile management
 - `PROJECT` - Project-level access
 
+### Public Key URL Domain Allowlist
+
+`public_key_url` values are validated against a domain allowlist before the key is fetched — once when the configuration loads (fails fast on startup) and again immediately before each fetch (defense in depth). This stops a tampered or misconfigured entry from pointing at an attacker-controlled host.
+
+| Parameter                             | Type          | Default | Description                                                                                                            |
+| ------------------------------------- | ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `AUTHORIZED_APPS_ALLOWED_KEY_DOMAINS` | list\[string] | `[]`    | Domains permitted to host `public_key_url` keys. A host matches if it equals a listed domain or is a subdomain of one. |
+
+Validation rules:
+
+- `public_key_url` must use `https`.
+- The URL host must not be an IP literal.
+- The URL host must equal, or be a subdomain of, one of the configured domains.
+- An empty allowlist (the default) rejects every URL-based key — only `public_key_path` (local file) entries are permitted until at least one domain is configured.
+
+Override with a JSON array via environment variable:
+
+```bash
+AUTHORIZED_APPS_ALLOWED_KEY_DOMAINS=["trusted.example","keys.trusted.example"]
+```
+
 ---
 
 ## See Also