Keycloak Client Configuration

The Sovereign Gateway for Applications

A Client in Keycloak is the “Sovereign Gateway” for an individual application or service. It represents the cryptographically defined relationship between your code and the identity provider. Whether you are securing a modern Single Page App (SPA) via OIDC with PKCE, a legacy enterprise tool via SAML 2.0, or a backend service via Client Credentials, Client configuration is where you define the specific “Truth” that each app receives. For the IAM architect, configuring clients is about enforcing Least Privilege Scopes and ensuring that sensitive user tokens are never leaked to unauthorized consumers.

CLIENTS

Integration Sovereign

Core Mission

Secure Application Integration. Establishing a rigorous, protocol-driven framework for authenticating applications and issuing scoped tokens that ensure data is only released to verified consumers.

Like a Corporate Notary: Imagine your application is a contractor trying to get into different rooms in your office. The Keycloak Client is the "Sovereign Notary." When the contractor (The App) presents their credentials, the Notary verifies who they are, checks their contract (The Client Scopes), and issues them a specific "Stamped Permit" (The Token). This permit only allows them to enter the specific rooms they were hired for. The Notary also makes sure they don't walk away with anyone else's paperwork (Token Security).

Next.js/React SPA Integration / Legacy SAML Apps / Service-to-Service Auth / Mobile App PKCE

The Client Integration Matrix

Designing for clients requires choosing the right access type and protocol for the application’s nature.

Strategic Integration Profiles

Profile	Strategic Responsibility	IAM Implementation
Public OIDC (SPA)	Browser-based Security.	Uses Authorization Code Flow + PKCE / No Client Secret (Not secure in browser).
Confidential OIDC	Server-side Security.	Uses Client Secret / ideal for backend apps and web servers.
Bearer-Only	API Protection.	The client does not initiate login; it only validates tokens issued to other clients.
SAML 2.0 Client	Legacy Enterprise.	XML metadata exchange / Handles roles and attributes via SAML assertions.

The Application Onboarding Flow

Integrating an app with Keycloak follows a “Define-Exchange-Authorized” path.

graph LR
    Define[Define Client & Scopes] --> Exchange[Metadata / Secret Exchange]
    Exchange --> Token[Token Issuance & Validation]

1

Define the Sovereign Scope

Configure the **Client ID** and **Access Type**. Crucially, define the "Client Scopes." These define which user attributes (Email, Groups, Profile) will be included in the token. Use "Optional Scopes" to ensure that the app only receives the data it explicitly asks for at runtime.

2

Secure Metadata Exchange

Configure the **Valid Redirect URIs**. This is your primary defense against "Authorization Code Injection" attacks. The App and Keycloak exchange OIDC discovery data (the `.well-known` endpoint) or SAML XML metadata to establish the cryptographic handshake parameters.

3

Protocol-Aware Token Issuance

The app initiates the auth flow. Keycloak validates the request, challenges the user, and issues the tokens. In the Client config, you can customize the **Protocol Mappers**—calculating custom claims or roles to ensure the JWT format perfectly matches what your application expects.

---

Technical Client Implementation

Configuring a ‘Public’ client for a React app using PKCE is the modern standard for web security.

OIDC Client Config (Conceptual JSON)

{
  "clientId": "sovereign-frontend-app",
  "publicClient": true,
  "protocol": "openid-connect",
  "redirectUris": ["https://app.sovereign.corp/*"],
  "webOrigins": ["https://app.sovereign.corp"],
  "attributes": {
    "pkce.code.challenge.method": "S256",
    "access.token.lifespan": "300"
  },
  "defaultClientScopes": ["profile", "email", "roles"]
}

Client Implementation Guides

Master the technical ceremonies of application integration and scope management.

PKCE Deep Dive

Understanding the 'Proof Key for Code Exchange' required for secure public clients.

SAML Assertions

Mapping Keycloak user attributes to the XML claims required by legacy SAML service providers.

Internal Client Scopes

Designing reusable scopes that can be shared across multiple applications in a realm.

Gateway Integration

Using Keycloak as the 'Sovereign Issuer' for tokens validated at your API Gateway.

Next Steps

• Explore Keycloak Client Management Guide.
• Review OIDC Specification for technical details.
• Check Client Audit Logs for monitoring token issuance events.