Package org.keycloak.protocol.oauth2.cimd.clientpolicy.executor

Class AbstractClientIdMetadataDocumentExecutor<CONFIG extends AbstractClientIdMetadataDocumentExecutor.Configuration>

java.lang.Object
org.keycloak.protocol.oauth2.cimd.clientpolicy.executor.AbstractClientIdMetadataDocumentExecutor<CONFIG>
All Implemented Interfaces:
org.keycloak.provider.Provider, org.keycloak.services.clientpolicy.executor.ClientPolicyExecutorProvider<CONFIG>
Direct Known Subclasses:
ClientIdMetadataDocumentExecutor
public abstract class AbstractClientIdMetadataDocumentExecutor<CONFIG extends AbstractClientIdMetadataDocumentExecutor.Configuration> extends Object implements org.keycloak.services.clientpolicy.executor.ClientPolicyExecutorProvider<CONFIG>
The abstract class implements OAuth Client ID Metadata Document specification (Internet Draft v00).
Author:
Takashi Norimatsu
See Also:
  • OAuth Client ID Metadata Document (CIMD) [Internet Draft]]

    Moreover, the abstract class implements Authorization part of Model Context Protocol (MCP) specification (version 2025-11-25).

  • Model Context Protocol (MCP) [2025-11-25]]

    The abstract class satisfies the following requirements of CIMD and MCP:

    • Requirements whose requirement level is MUST or SHOULD.
    • Requirements in Security Consideration.

    The abstract class provides the following features:

    • Client ID Verification: if {client_id} parameter satisfies the requirements of the specifications
    • Client ID Validation: if {client_id} parameter is valid according to the policy.
    • Fetching Client Metadata: fetch a client metadata by accessing {client_id} URL.
    • Client Metadata Verification: if a client metadata satisfies the requirements of the specifications.
    • Client Metadata Validation: if a client metadata is valid according to the policy.
    • Client Metadata Augmentation in OIDCClientRepresentation: augment a fetched client metadata.

    Roles of the abstract class and its concrete class: The abstract class covers the basic checks and processes by following the CIMD and MCP specifications while the concrete class of the abstract class provides additional checks or processes.

    For example, regarding Client ID Validation and Client Metadata Validation, the CIMD and MCP specifications allow an authorization server to implement policies that determine the valid {client_id} parameter value and client metadata. The CIMD and MCP specification show some examples of the policies roughly, but what policies are implemented in detail is up to the authorization server implementation. Therefore, the abstract class provides some of the examples and the concrete class can implement additional policies.

    Client Metadata Caching: The abstract class does not treat the following processes. It delegates them to ClientIdMetadataDocumentProvider:

    • determining if (re-)fetching a client metadata is needed
    • concrete process of caching a client metadata: create and update
    • update cache expiry time
    • augment a client metadata in ClientRepresentation
    For example, PersistentClientIdMetadataDocumentProvider persists client metadata. In the future, the provider for non-persisting a client metadata can be provided.

    Client Metadata Format: According to the CIMD specification, the client metadata format is the same as for Dynamic Client Registration except for client_id property.

  • invalid input: '<a href="https://datatracker.ietf.org/doc/html/rfc7591>OAuth 2.0 Dynamic Client Registration Protocol [RFC 7591]</a> Therefore, OIDCClientRepresentation is used for the client metadata format. The CIMD specification allows the use of additional properties (MAY requirement level), but the class does not treat them. <p>Client Metadata Augmentation in <code>OIDCClientRepresentation</code>: To successfully convert a fetched client metadata to <code>ClientRepresentation</code>, intentionally augment it. The actual example is a public client. The CIMD and MCP specification allows a public client. <code>DescriptionConverter.toInternal</code> recognize a client as a public client if token_endpoint_auth_method is "none" If a client metadata lacks token_endpoint_auth_method, it is converted to "none", meaning it is treated as a public client.'

  • Field Details

  • Constructor Details

  • Method Details

    • getLogger

      protected abstract org.jboss.logging.Logger getLogger()

    • getProvider

      protected ClientIdMetadataDocumentProvider<CONFIG> getProvider()

    • getConfiguration

      public CONFIG getConfiguration()

    • executeOnEvent

      public void executeOnEvent(org.keycloak.services.clientpolicy.ClientPolicyContext context) throws org.keycloak.services.clientpolicy.ClientPolicyException
      Specified by:
      executeOnEvent in interface org.keycloak.services.clientpolicy.executor.ClientPolicyExecutorProvider<CONFIG extends AbstractClientIdMetadataDocumentExecutor.Configuration>
      Throws:
      org.keycloak.services.clientpolicy.ClientPolicyException

    • verifyAuthorizationRequest

      protected URI verifyAuthorizationRequest(PreAuthorizationRequestContext preAuthorizationRequestContext) throws org.keycloak.services.clientpolicy.ClientPolicyException
      Verifies an authorization request to check if the request includes required parameters and follows the expected format.
      Parameters:
      preAuthorizationRequestContext - an authorization request
      Returns:
      URI redirect_uri parameter value as URI
      Throws:
      org.keycloak.services.clientpolicy.ClientPolicyException - when verification of an authorization request fails.

    • verifyClientId

      protected URI verifyClientId(String clientId) throws org.keycloak.services.clientpolicy.ClientPolicyException
      Verifies a value of client_id parameter of an authorization request to check if the value satisfies the requirements of the CIMD and MCP specifications.
      Parameters:
      clientId - a value of client_id parameter of an authorization request
      Returns:
      URI client_uri parameter value as URI
      Throws:
      org.keycloak.services.clientpolicy.ClientPolicyException - when verification of an authorization request fails.

    • validateClientId

      protected void validateClientId(URI clientIdURI) throws org.keycloak.services.clientpolicy.ClientPolicyException
      Validate a value of client_id parameter of an authorization request to check if the value meets the policies.
      Parameters:
      clientIdURI - a value of client_id parameter of an authorization request in URI
      Throws:
      org.keycloak.services.clientpolicy.ClientPolicyException - when validation of an authorization request fails.

    • checkTrustedDomain

      protected boolean checkTrustedDomain(String hostname, String trustedDomain)

    • fetchClientMetadata

      protected AbstractClientIdMetadataDocumentExecutor.OIDCClientRepresentationWithCacheControl fetchClientMetadata(URI clientIdURI, boolean isUpdate, ClientIdMetadataDocumentProvider provider) throws org.keycloak.services.clientpolicy.ClientPolicyException
      fetch a client metadata and update cache expiry time if the client metadata has been already created.
      Parameters:
      clientIdURI - a value of client_id parameter of an authorization request in URI
      isUpdate - indicates the client metadata has been already created
      provider - ClientIdMetadataDocumentProvider for updating cache expiry time
      Returns:
      OIDCClientRepresentationWithCacheControl a combination of a client metadata and Cache-Control header value accompanied by the metadata response. null if a client metadata was re-fetched but the HTTP response status code is 304 Not Modified.
      Throws:
      org.keycloak.services.clientpolicy.ClientPolicyException - when fetching a client metadata fails.

    • verifyClientMetadata

      protected URI verifyClientMetadata(URI clientIdURI, URI redirectUriURI, org.keycloak.representations.oidc.OIDCClientRepresentation clientOIDC) throws org.keycloak.services.clientpolicy.ClientPolicyException
      Verify a client metadata to check if it satisfies the requirements of the CIMD and MCP specifications.
      Parameters:
      clientIdURI - a value of {client_id} parameter of an authorization request in URI
      redirectUriURI - a value of {redirect_uri} parameter of an authorization request in URI
      clientOIDC - a client metadata
      Returns:
      URI client_id property of a client metadata in URI
      Throws:
      org.keycloak.services.clientpolicy.ClientPolicyException - when verifying a client metadata fails.

    • validateClientMetadata

      protected void validateClientMetadata(URI clientIdURI, URI redirectUriURI, org.keycloak.representations.oidc.OIDCClientRepresentation clientOIDC) throws org.keycloak.services.clientpolicy.ClientPolicyException
      Validate a client metadata to check if the value meets the policies.
      Parameters:
      clientIdURI - a value of {client_id} parameter of an authorization request in URI
      redirectUriURI - a value of {redirect_uri} parameter of an authorization request in URI
      clientOIDC - a client metadata
      Throws:
      org.keycloak.services.clientpolicy.ClientPolicyException - when validating a client metadata fails.

    • convertContentFilledList

      protected List<String> convertContentFilledList(List<String> list)

    • augmentClientOIDC

      protected void augmentClientOIDC(org.keycloak.representations.oidc.OIDCClientRepresentation oidcClient)
      Augments a re-fetched client metadata to successfully convert it to ClientRepresentation.
      Parameters:
      oidcClient - a fetched client metadata

    • invalidClientIdMetadata

      protected static org.keycloak.services.clientpolicy.ClientPolicyException invalidClientIdMetadata(String errorDetail)