Keycloak Introspect Public Client

When working with modern authentication and authorization systems, developers often encounter the need to validate access tokens issued by an identity provider. Keycloak, as an open-source identity and access management solution, provides an introspection endpoint that allows applications to check the validity and details of a token. However, when it comes to using the introspection endpoint with a public client, the process can be slightly different compared to a confidential client. Understanding how to perform Keycloak introspect with a public client is essential for developers aiming to build secure applications without exposing sensitive credentials.

Understanding Token Introspection in Keycloak

Token introspection is a method defined by the OAuth 2.0 specification, allowing resource servers or client applications to verify the status and claims of an access token. Instead of directly trusting the token, the application can send it to the introspection endpoint, where the identity provider checks if the token is active and returns metadata such as the subject, client ID, scopes, and expiration.

Why Introspection Matters

In distributed systems, relying solely on local token validation may not always be practical. Introspection ensures

• Real-time validation of whether a token is still active or revoked.
• Access to detailed metadata beyond what is in a JWT.
• Support for opaque tokens that cannot be verified locally.

Public Clients vs. Confidential Clients

In Keycloak, clients are categorized as either public or confidential. Understanding the distinction is key to knowing how introspection works in different scenarios.

Confidential Clients

Confidential clients are applications that can securely store credentials, such as a client secret. They authenticate themselves when making requests to Keycloak’s endpoints, including the introspection endpoint. For example, a backend application running on a secure server can safely hold a client secret and use it during token introspection requests.

Public Clients

Public clients, on the other hand, are applications that cannot securely store secrets. Examples include single-page applications (SPAs), mobile apps, and desktop applications. Because these clients run in environments where the source code can be inspected or modified, Keycloak does not require them to provide a secret. Instead, they rely on alternative authentication and validation flows.

Challenges of Introspection with Public Clients

One of the main challenges in using the introspection endpoint with public clients is the lack of a client secret. Since introspection requires the caller to authenticate itself to Keycloak, the absence of a secret creates a security consideration. Allowing unauthenticated calls to the introspection endpoint could expose sensitive information about tokens.

Security Concerns

If a public client directly calls the introspection endpoint, it could potentially reveal whether a given token is valid, its user, and its permissions. This could be exploited by malicious actors if the endpoint is openly accessible. Therefore, developers need to design their architecture carefully to balance usability and security.

Strategies for Handling Introspection with Public Clients

Although public clients cannot authenticate using secrets, there are approaches that can be used to validate tokens effectively.

1. Use a Backend Proxy

The most recommended approach is to delegate introspection to a backend service. Instead of calling the Keycloak introspection endpoint directly from the public client, the client sends the token to its own backend. The backend, configured as a confidential client, then makes the secure introspection call to Keycloak and returns the result to the client.

2. Rely on JWT Validation

In many cases, Keycloak issues tokens in JWT (JSON Web Token) format. Public clients can validate these tokens locally without introspection by checking the signature against the Keycloak public key, verifying claims such as expiration and audience. This method avoids exposing introspection endpoints but requires careful implementation of cryptographic checks.

3. Token Exchange Mechanism

Keycloak supports token exchange, where a public client can exchange its access token for another token through a secure backend. This can provide a safer alternative than direct introspection while still ensuring proper validation.

How to Configure Introspection in Keycloak

If a developer still needs to use introspection with a public client, configuration and permissions play a major role. By default, Keycloak requires authentication for introspection requests. Developers can

• Enableservice accountson a confidential client and use them for secure introspection.
• Create a proxy service dedicated to handling validation requests on behalf of public clients.
• Use Keycloak’s built-in features liketoken mappersto adjust the data returned in introspection responses.

Practical Example

Consider a scenario where you have a mobile app (public client) and an API server (resource server). The mobile app obtains an access token from Keycloak. When the app needs to verify the token’s validity, it should not call Keycloak’s introspection endpoint directly. Instead, it sends the token to the API server. The API server, registered as a confidential client with Keycloak, securely calls the introspection endpoint and validates the token. This ensures that the mobile app remains lightweight and does not expose sensitive endpoints to potential attackers.

Best Practices

When implementing introspection with public clients in Keycloak, several best practices can enhance security and performance

• Avoid direct introspection from public clientsAlways use a secure intermediary service.
• Leverage JWT validationUse Keycloak’s public keys to validate tokens locally when possible.
• Restrict introspection accessEnsure only authorized clients or services can call the introspection endpoint.
• Monitor token lifetimesUse shorter token lifespans with refresh tokens to reduce risk.
• Combine with fine-grained policiesApply Keycloak authorization services to enforce resource-level controls.

Common Misconceptions

There are some misconceptions around Keycloak introspection with public clients that deserve clarification

• Public clients can freely call the introspection endpoint.– This is incorrect, as Keycloak requires client authentication for introspection requests.
• JWT tokens always need introspection.– In reality, JWTs can be validated locally without contacting Keycloak.
• Introspection is the only way to validate tokens.– Developers can choose between introspection and local validation depending on the token type and architecture.

Using Keycloak introspect with a public client requires careful architectural decisions. Because public clients cannot safely hold secrets, direct introspection is generally discouraged. Instead, developers should rely on a backend proxy, JWT validation, or token exchange mechanisms to maintain security. By following best practices and understanding the distinctions between public and confidential clients, teams can ensure robust token validation while safeguarding user data. Ultimately, Keycloak provides flexible tools to handle both secure and user-friendly authentication workflows, and knowing how to use them properly is key to building modern, resilient applications.