Keycloak is one of the most widely adopted open-source identity and access management tools available, and getting your Keycloak OpenID Connect configuration right is the foundation for securing any application that relies on token-based authentication. Whether you're protecting a web app, an API gateway, or a service that communicates with healthcare systems over FHIR, the OIDC setup in Keycloak controls how users authenticate and how tokens get issued.

For healthcare vendors building integrations with EHR platforms like EPIC, authentication protocols like OpenID Connect aren't optional, they're required. At VectorCare, our no-code SMART on FHIR platform handles OIDC and OAuth2 complexity out of the box, so vendors can launch into EPIC's ecosystem in weeks instead of months. But we also know that many teams want to understand the underlying mechanics, especially when evaluating build-vs-buy decisions or configuring identity layers across their own infrastructure.

This guide walks you through every step of setting up Keycloak as an OpenID Connect provider, from creating realms and clients to discovering OIDC endpoints via the well-known configuration URL. By the end, you'll have a working OIDC setup and a clear picture of how each piece fits together to secure your applications.

What you need before you start

Before you touch a single configuration setting, make sure your environment is ready. A failed Keycloak setup almost always traces back to missing dependencies or misconfigured infrastructure, not to errors in the admin console itself. Running through this checklist first saves you from debugging problems that have nothing to do with your keycloak openid connect configuration.

Software and runtime dependencies

Your machine or server needs to meet a few baseline requirements before Keycloak will run reliably. Keycloak 23+ runs on Java 17 or later (the distribution zip ships with an embedded JDK, so you may not need to install Java separately if you use the provided package). If you plan to run Keycloak in a container, you need Docker 20.10+ or a compatible runtime like Podman.

If you're running Keycloak in production, always use a dedicated external database rather than the built-in H2 database, which Keycloak itself labels as unsuitable for production use.

Here is a quick reference for what you need installed:

Requirement	Minimum version	Notes
Java (bare-metal installs)	17	OpenJDK works fine
Docker (containerized installs)	20.10	Podman 3.0+ also works
PostgreSQL (recommended DB)	13	MySQL 8 or MariaDB 10.5 also supported
Keycloak	23.0	24+ recommended for the latest OIDC features
curl or Postman	Any recent version	Used for testing OIDC endpoints

Network and port access

Keycloak listens on port 8080 by default for HTTP and port 8443 for HTTPS. Those ports need to be open and reachable from the browser or application that will interact with your identity provider. For local development, localhost:8080 is sufficient. For staging or production, you need a fully resolvable hostname that your app's redirect URIs can reach.

Your DNS and firewall rules matter here. Keycloak embeds the issuer URL into every token it issues, and if that URL does not match what your application expects during token validation, the OIDC flow will break at the verification step before a single user logs in.

What you should already know

This guide assumes you have basic familiarity with HTTP and browser-based authentication flows. You do not need to be an OAuth2 expert, but you should know what a redirect URI is and roughly how a login page hands a token back to an application. Understanding the difference between authentication and authorization also helps, since Keycloak handles both and the admin console surfaces both concepts throughout the setup.

If you are starting from zero on OIDC concepts, reviewing the OpenID Connect specification overview at openid.net before continuing gives you useful context for the steps ahead. The spec is dense, but even skimming the core flow diagram clarifies what Keycloak is doing under the hood during each configuration step.

Step 1. Run Keycloak and open the admin console

Getting Keycloak running is the first concrete action in your Keycloak OpenID Connect configuration process. You have two primary options: run it as a Docker container (fastest for most teams) or download and run the distribution zip. This guide uses Docker because it gives you a clean, reproducible environment without having to manage a local Java installation separately.

Start Keycloak with Docker

The command below pulls the official Keycloak image and starts it in development mode, which disables TLS requirements so you can work locally without setting up certificates right away. Development mode is not suitable for production, but it is the right starting point for understanding the setup.

docker run -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=changeme \
  quay.io/keycloak/keycloak:24.0.1 \
  start-dev

Replace changeme with a strong, unique password even in development environments, since these credentials persist in your container layer if you commit or share the image.

Once the container starts, Keycloak logs output to stdout and you will see a line confirming that the server is running on http://0.0.0.0:8080. That process typically takes 15 to 30 seconds on a standard machine.

Log in to the admin console

Open your browser and navigate to http://localhost:8080. Keycloak will redirect you to the welcome page, where you click the "Administration Console" link. Enter the admin credentials you passed as environment variables in the Docker command: admin as the username and the password you set.

After you log in, you land on the master realm dashboard. The master realm is Keycloak's built-in top-level realm used exclusively for administering Keycloak itself. You will create a separate realm for your application in the next step, which is the correct approach. Never configure application clients directly inside the master realm, as mixing admin credentials with application credentials creates a serious security risk.

Step 2. Create a realm and set core realm options

A realm in Keycloak is an isolated namespace that holds its own set of users, clients, roles, and identity provider settings. Every meaningful keycloak openid connect configuration lives inside a dedicated realm, not the master realm. Creating a separate realm for your application is how you enforce security boundaries and keep administrative access cleanly separated from user-facing authentication.

Create a new realm

In the admin console, look for the realm selector dropdown in the top-left corner of the sidebar. It currently shows "master." Click it, then select "Create realm" from the dropdown. Keycloak opens a form with a single required field: the Realm ID. Use a lowercase, hyphenated name that reflects your application or tenant, such as my-app or vendor-portal. Keycloak derives the issuer URL from this ID, so keep it short and free of special characters.

After you click "Create," Keycloak switches the console into your new realm automatically. You are now inside your application's isolated environment, and everything you configure from this point forward belongs only to this realm.

Configure core realm settings

Navigate to Realm Settings in the left sidebar. The General tab lets you set a display name, which appears on the Keycloak-hosted login page that users see. Set the Frontend URL field if your Keycloak instance sits behind a reverse proxy or load balancer. This field overrides the issuer URL embedded in tokens, and getting it wrong causes token validation failures in downstream applications.

Set the Frontend URL to the fully qualified public hostname your applications resolve, not the internal Docker network address, even during staging.

Switch to the Tokens tab to configure token lifespans. The default access token lifespan is 5 minutes, which is intentionally short for security reasons. You can adjust it based on your application's session requirements, but avoid setting it above 60 minutes without a clear reason. Also confirm that Refresh Token Max Reuse is set to 0, which prevents refresh token replay attacks by invalidating a refresh token the moment it gets used.

Step 3. Create an OIDC client the right way

A client in Keycloak represents the application or service that will request tokens on behalf of users. Getting this step right is critical because a misconfigured client is one of the most common reasons a keycloak openid connect configuration breaks in production, often in ways that produce vague error messages. Navigate to "Clients" in the left sidebar of your realm and click "Create client."

Choose the correct client type

Keycloak gives you two primary authentication flows for OIDC clients: confidential and public. Confidential clients hold a client secret and authenticate with Keycloak server-to-server, which is the right choice for backend services or server-rendered web applications. Public clients do not use a secret and instead rely on PKCE (Proof Key for Code Exchange) for security, making them the correct choice for single-page applications and mobile apps where a secret cannot be kept private.

Never use a confidential client for a browser-based app where the client secret would be exposed in JavaScript source code.

Client type	Secret required	Use case
Confidential	Yes	Server-side web apps, APIs
Public	No	SPAs, mobile apps
Bearer-only	No	Resource servers that only verify tokens

Set the core client settings

On the "Create client" form, set the Client ID to a lowercase, hyphenated string like my-app-client. This identifier appears in every token Keycloak issues for this client, so keep it descriptive and stable. Once you have saved the client, changing the Client ID breaks any application already configured to use it.

After creation, open the client's Settings tab and confirm that "Client authentication" is toggled on if you chose a confidential client. Keycloak will then generate a client secret, which you retrieve under the "Credentials" tab. Paste that secret into your application's environment configuration, and treat it with the same level of care as a database password by storing it in a secrets manager, not in source code.

Step 4. Configure redirect URIs, CORS, and logout URLs

Redirect URIs are where Keycloak sends the user after authentication completes, and getting these values wrong is one of the most common reasons a keycloak openid connect configuration fails silently. Keycloak performs an exact-match check against the redirect URI in every authorization request, so even a trailing slash mismatch causes the login flow to stop with a generic "invalid redirect URI" error.

Set valid redirect URIs

Open your client's Settings tab and locate the "Valid redirect URIs" field. Add each URI your application uses after login, one per line. For local development, that typically looks like http://localhost:3000/callback. For production, use the full HTTPS URL, such as https://app.yourdomain.com/auth/callback.

Avoid using wildcards like http://localhost:* in any environment beyond local development, since wildcard URIs allow token delivery to any port on that host.

You should also set the "Valid post-logout redirect URIs" field, which controls where Keycloak sends the browser after the user signs out. If you leave this blank, Keycloak defaults to blocking post-logout redirects, which leaves users stranded on a Keycloak page after they click sign out. Add your application's logout landing page, such as https://app.yourdomain.com/logged-out, to keep the flow seamless.

Configure CORS and Web Origins

Cross-Origin Resource Sharing (CORS) matters when your frontend JavaScript calls Keycloak's token endpoint directly, which happens in public client flows using PKCE. Without correct CORS settings, the browser blocks the token exchange before it reaches your application code.

In the "Web Origins" field, add the origin of your frontend application, such as https://app.yourdomain.com. This tells Keycloak to include the correct Access-Control-Allow-Origin response header on token endpoint responses. If you are running multiple frontend environments, such as staging and production, add each origin as a separate entry. Setting the web origin to + automatically mirrors all values from your valid redirect URIs, which is a convenient shortcut during development but requires tightening before you deploy to production.

Step 5. Add users, roles, and token claims

Users, roles, and claims are the identity layer that gives your keycloak openid connect configuration real-world meaning. Without them, Keycloak can authenticate a request, but it cannot tell your application who the user is or what they are allowed to do. Configure these three elements in the correct order so your tokens carry the right information from the first login attempt.

Create a test user

Navigate to "Users" in the left sidebar of your realm and click "Add user." Fill in the username field, then save the record. After saving, open the "Credentials" tab for that user and set a temporary password. Disable the "Temporary" toggle if you want the user to skip the forced password reset on first login, which is the better choice during integration testing.

Define roles and assign them

Keycloak supports two role scopes: realm roles, which apply across all clients in the realm, and client roles, which are scoped to a single client. For most applications, realm roles are sufficient. Go to "Realm roles" in the sidebar, click "Create role," and give it a name like app-user or admin. Once you create the role, open your test user's "Role mapping" tab and assign the role directly to that user.

Prefer realm roles for roles that cross multiple clients and client roles for permissions that belong strictly to one application, since mixing the two arbitrarily makes token contents hard to audit later.

Add custom claims to tokens

Keycloak maps user attributes and roles into tokens through protocol mappers, which you configure under your client's "Client scopes" tab. Click the linked default scope, then navigate to "Mappers" and click "Add mapper." To include a user attribute like organization_id in the ID token and access token, choose "User Attribute" as the mapper type, set the attribute name, and enable the toggles for "Add to ID token" and "Add to access token."

Mapper type:     User Attribute
User Attribute:  organization_id
Token Claim Name: organization_id
Add to ID token:  ON
Add to access token: ON

This puts the value directly into the token payload so your application reads it without an extra API call to the userinfo endpoint.

Step 6. Find the OIDC discovery document and endpoints

Every Keycloak realm publishes a well-known discovery document at a predictable URL, and this document is the single most useful reference in your entire keycloak openid connect configuration workflow. Instead of hardcoding individual endpoint URLs into your application, your OIDC library fetches this document at startup and reads all the endpoint locations from it automatically, which means your application adapts correctly if endpoint paths ever change.

The well-known configuration URL

Keycloak follows the OpenID Connect Discovery specification, so the discovery document lives at a standardized path relative to your realm's issuer URL. Construct the URL using this pattern:

http://<your-keycloak-host>:<port>/realms/<realm-name>/.well-known/openid-configuration

For a local development setup using the realm name my-app, the URL looks like this:

http://localhost:8080/realms/my-app/.well-known/openid-configuration

Open that URL in your browser or run curl http://localhost:8080/realms/my-app/.well-known/openid-configuration in your terminal. Keycloak returns a JSON object listing every endpoint your application needs.

Bookmark this URL for your realm during development, since it is the fastest way to confirm that Keycloak is running and that your realm name is spelled correctly.

What the discovery document contains

The JSON response includes all the endpoints your application's OIDC library needs to complete the login flow. The most critical fields to know are listed below:

Field	Purpose
issuer	The base URL your application uses to validate token signatures
authorization_endpoint	Where the browser sends users to log in
token_endpoint	Where your server exchanges an authorization code for tokens
jwks_uri	The public key set used to verify token signatures
userinfo_endpoint	Returns claims about the authenticated user
end_session_endpoint	Initiates logout and clears the Keycloak session

Your OIDC library, whether it is a Python package, a Node.js middleware, or a Java SDK, consumes the discovery document URL directly rather than requiring you to configure each endpoint manually. Pass the well-known URL to your library's initialization function, and it handles the rest.

Step 7. Test the authorization code flow with PKCE

Testing the full authorization code flow with PKCE confirms that your keycloak openid connect configuration works end-to-end before you wire it into your application code. Running this test manually forces you to touch every step in the flow, which surfaces misconfigured redirect URIs, wrong client types, and missing PKCE settings before they cause runtime errors in a real user session.

Build the authorization request manually

PKCE requires two values you generate on the client side: a code_verifier, which is a cryptographically random string between 43 and 128 characters, and a code_challenge, which is the Base64url-encoded SHA-256 hash of the verifier. You send the challenge to Keycloak during the authorization request and then prove you hold the original verifier during the token exchange.

Generate the code_verifier fresh for every authorization request, since reusing it across sessions defeats the security guarantee PKCE provides.

Open your browser and paste the following URL, substituting your realm name, client ID, and redirect URI:

http://localhost:8080/realms/my-app/protocol/openid-connect/auth
  ?client_id=my-app-client
  &redirect_uri=http://localhost:3000/callback
  &response_type=code
  &scope=openid profile email
  &code_challenge=<your_code_challenge>
  &code_challenge_method=S256
  &state=random-state-value

Keycloak displays your login page. After you log in with your test user's credentials, Keycloak redirects the browser to your redirect URI with a short-lived code parameter appended to the URL.

Exchange the code for tokens

Copy the code value from the redirect URL, then send the following POST request using curl or Postman:

curl -X POST http://localhost:8080/realms/my-app/protocol/openid-connect/token \
  -d "grant_type=authorization_code" \
  -d "client_id=my-app-client" \
  -d "redirect_uri=http://localhost:3000/callback" \
  -d "code=<your_authorization_code>" \
  -d "code_verifier=<your_code_verifier>"

Keycloak returns a JSON object containing an access_token, an id_token, and a refresh_token. Paste the access token into jwt.io to decode the payload and confirm that your custom claims, roles, and issuer URL appear exactly as you configured them in the previous steps.

Next steps for your app

You now have a complete keycloak openid connect configuration running, with a realm, a client, users, roles, custom claims, and a verified authorization code flow with PKCE. The logical next step is connecting this identity layer to your actual application by passing the well-known discovery URL to your OIDC library and wiring the access token into your API authorization middleware.

From there, consider adding social login providers or enterprise SSO connections through Keycloak's Identity Providers section, which lets you federate authentication from Google, Microsoft Entra, or SAML-based systems without changing your application code. Review your token lifespans and refresh token rotation settings before you push to production, since those defaults rarely match real application requirements.

If your application targets healthcare systems and needs SMART on FHIR compliance on top of OIDC, launch your FHIR-ready app without building from scratch and skip months of integration work.