docs: update MCP authz server guide for Keycloak 26.6 CIMD support

[Copilot]

Keycloak 26.6 supports OAuth Client ID Metadata Document via PR keycloak#45285. Updates mcp-authz-server.adoc to reflect this.

Description

• Standards Compliance table: OAuth Client ID Metadata Document changed from "Not supported" to "Supported", with a WARNING block noting that this support is an experimental feature in {project_name} that may introduce breaking changes in future versions
• MCP version compliance table: 2025-11-25 entry updated from "Partially Supported without Resource Indicators for OAuth 2.0 and OAuth Client ID Metadata Document" to "Partially Supported without Resource Indicators for OAuth 2.0"
• For MCP 2025-11-25 section: Added configuration instructions for:
  • Setting up the client profile for OAuth Client ID Metadata Document — client policy profile executor with options: Allow http scheme, Trusted domains, Restrict same domain, Required properties, Only Allow Confidential Client
  • Setting up the client policy for OAuth Client ID Metadata Document — client policy condition (URI scheme + Trusted domains) that triggers the executor profile when client_id is a URL matching the configured scheme/domain, followed by a summary of how the overall configuration works together
  • System-wide settings for the Client ID Metadata Document executor — documents min-cache-time, max-cache-time, and upper-limit-metadata-bytes SPI options that control caching and metadata size limits, configured via --spi-client-policy-executor--client-id-metadata-document<property>=<value> command-line options (not configurable through the Admin Console)
• Added a WARNING block noting that the OAuth Client ID Metadata Document support is an experimental feature in {project_name} that may introduce breaking changes in future versions, and documenting the cimd feature flag (--features=cimd) requirement
• Visual Studio Code desktop integration section: Added step-by-step instructions for configuring {project_name} to support Microsoft Visual Studio Code desktop as an MCP client using OAuth Client ID Metadata Document, focusing on localhost callbacks for desktop usage, including:
  • Starting {project_name} with the cimd feature flag
  • Explanation that VS Code desktop uses localhost callbacks (http://127.0.0.1:<port>/callback) for the OAuth redirect, and why this requires Restrict same domain: OFF
  • Setting up the client profile with trusted domains vscode.dev and 127.0.0.1, with Restrict same domain: OFF (VS Code desktop uses localhost redirect URIs not on the vscode.dev domain) and Only Allow Confidential Client: OFF (VS Code desktop is a public client)
  • Setting up the client policy with client-id-uri condition targeting https URIs on the vscode.dev domain
• Section headings and body text use user-friendly names rather than Java class names, as the document targets non-programmer readers

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[tnorimat]

@copilot could you add the warning showing that OAuth Client ID Metadata Document support is still experimental feature, so it might cause breaking change about that in the future version of keycloak {project_name}.

[Copilot]

@copilot could you add the warning showing that OAuth Client ID Metadata Document support is still experimental feature, so it might cause breaking change about that in the future vers...

Added in 4b59eb3. Changed the NOTE: to a WARNING: block stating that the OAuth Client ID Metadata Document support is an experimental feature in {project_name} and may introduce breaking changes in future versions.

[tnorimat]

@copilot Could you change the section name Setting up the ClientIdMetadataDocumentExecutor profile to Setting up the client profile for OAuth Client ID Metadata Document ? Because the readers of this document is not a programmer so showing the class name is not appropriate.

[Copilot]

@copilot Could you change the section name Setting up the ClientIdMetadataDocumentExecutor profile to Setting up the client profile for OAuth Client ID Metadata Document ? Because ...

Done in 9a063e1. Renamed both section headings:

• "Setting up the ClientIdMetadataDocumentExecutor profile" → "Setting up the client profile for OAuth Client ID Metadata Document"
• "Setting up the ClientIdUriSchemeCondition policy" → "Setting up the client policy for OAuth Client ID Metadata Document"

[tnorimat]

@copilot Could you change the sentense

The `ClientIdMetadataDocumentExecutor` is a client policy executor that processes an authorization request whose `client_id` parameter is a URL pointing to a Client ID Metadata Document.

to

To process an authorization request whose `client_id` metadata is a URL pointing to a Client ID Metadata Document, you need to create the profile including `client-id-metadata-document` executor
``` ? Because the reader of this document is not a programmer, so showing the class name is not appropriate.

[Copilot]

@copilot Could you change the sentense

The `ClientIdMetadataDocumentExecutor` is a client policy executor that processes an authorization request whose `client_id` parameter is a...

Updated in a3535c4. Also applied the same pattern to the ClientIdUriSchemeCondition paragraph for consistency.

[tnorimat]

@copilot could you add explanation and the way of configuration about setting items CONFIG_MIN_CACHE_TIME, CONFIG_MAX_CACHE_TIME and CONFIG_UPPER_LIMIT_METADATA_BYTES defined in AbstractClientIdMetadataDocumentExecutorFactory ? Please not that these setting items are system-wide configuration and cannot be configured by admin console.

[Copilot]

@copilot could you add explanation and the way of configuration about setting items CONFIG_MIN_CACHE_TIME, CONFIG_MAX_CACHE_TIME and CONFIG_UPPER_LIMIT_METADATA_BYTES defined in `Abstr...

Added in e60051b. Added a new "System-wide settings for the Client ID Metadata Document executor" subsection documenting min-cache-time (default: 300s), max-cache-time (default: 259200s), and upper-limit-metadata-bytes (default: 5000 bytes) with their descriptions, defaults, and an example using --spi-client-policy-executor--client-id-metadata-document--<property>=<value> command-line syntax.

[tnorimat]

@copilot could you move the following sentence to the end of the section "Setting up the client policy for OAuth Client ID Metadata Document" ?

With this configuration, when an MCP client sends an authorization request with a `client_id` value that is an `https` URL matching a trusted domain, {project_name} fetches the Client ID Metadata Document from that URL and uses the metadata to process the request.

[tnorimat]

@copilot to the end of the document, could you add how to configure keycloak to support MCP client of microsoft visual studio code that support OAuth Client ID Metadata Document ?

[Copilot]

@copilot to the end of the document, could you add how to configure keycloak to support MCP client of microsoft visual studio code that support OAuth Client ID Metadata Document ?

Added in ae729d5. Added a new "Visual Studio Code integration" section at the end of the document with:

• An overview of VS Code as an MCP client using CIMD with client_id URLs on vscode.dev
• A note that VS Code is a public client using PKCE
• Step-by-step instructions for starting Keycloak with the cimd feature
• Setting up the client profile with Restrict same domain: OFF (VS Code desktop uses localhost redirect URIs) and Only Allow Confidential Client: OFF
• Setting up the client policy with trusted domain pattern (.*\.)?vscode\.dev to match both vscode.dev and insiders.vscode.dev

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• code.visualstudio.com
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)
• den.dev
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)
• guptadeepak.com
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)
• insiders.vscode.dev
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)
• vscode.dev
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[tnorimat]

@copilot VS Code likely has both web-based redirects using HTTPS and potentially localhost callbacks for desktop usage. Could you only consider localhost callbacks for desktop usage and rewrite the section "Visual Studio Code integration
" ?

[Copilot]

@copilot VS Code likely has both web-based redirects using HTTPS and potentially localhost callbacks for desktop usage. Could you only consider localhost callbacks for desktop usage an...

Rewritten in 3d12ac9. The section is now titled "Visual Studio Code desktop integration" and focuses on localhost callbacks for desktop usage. Key changes:

• Added a paragraph explaining that VS Code desktop uses localhost callbacks (http://127.0.0.1:<port>/callback) for the OAuth redirect
• Clarified why Restrict same domain must be OFF (redirect URI is on 127.0.0.1, not on vscode.dev)
• Updated all references from "VS Code" to "VS Code desktop" throughout the section

[tnorimat]

@copilot could you omit https://insiders.vscode.dev/mcp-client and insiders.vscode.dev and rewrite the section "Visual Studio Code integration" ?

[Copilot]

@copilot could you omit https://insiders.vscode.dev/mcp-client and insiders.vscode.dev and rewrite the section "Visual Studio Code integration" ?

Done in cc8efef. Removed all references to insiders.vscode.dev and https://insiders.vscode.dev/mcp-client. The trusted domain pattern is now simplified to vscode\.dev in both the client profile and client policy configuration steps.

[tnorimat]

@copilot Could you replace vscode\.dev with vscode.dev ?

[Copilot]

@copilot Could you replace vscode\.dev with vscode.dev ?

Done in 7ef050b. Replaced vscode\.dev with vscode.dev in both the client profile and client policy trusted domains configuration steps.

[tnorimat]

@copilot In section "Setting up the client profile for VS Code desktop", step 5, could you add 127.0.0.1 to Trusted domains ?

[Copilot]

@copilot In section "Setting up the client profile for VS Code desktop", step 5, could you add 127.0.0.1 to Trusted domains ?

Done in 973f8a5. Added 127.0.0.1 to the Trusted domains in step 5, so it now reads: vscode.dev, 127.0.0.1.

[tnorimat]

@copilot In section "Standards Compliance MCP requires" could you add the warning showing that OAuth Client ID Metadata Document support by {project_name} is still experimental feature?

[Copilot]

@copilot In section "Standards Compliance MCP requires" could you add the warning showing that OAuth Client ID Metadata Document support by {project_name} is still experimental feature...

Done in 167841e. Added a WARNING block right after the Standards Compliance table noting that the OAuth Client ID Metadata Document support in {project_name} is an experimental feature that may introduce breaking changes in future versions.