Complete OIDC Client Workflow with n8n and Keycloak

What This Workflow Actually Does (In Plain English)

If you're looking to hook up n8n with Keycloak so users can log in securely using OpenID Connect (OIDC), this workflow template does exactly that. It walks through the full OIDC client flow, including support for PKCE (Proof Key for Code Exchange) to keep things extra secure.

Think of it as a ready-made login flow that:

• Accepts incoming authentication requests through a webhook
• Redirects users to Keycloak to log in
• Exchanges the authorization code for an access token
• Fetches user details from the userinfo endpoint
• Shows either a login page or a personalized welcome page

So instead of wiring all of that together manually, you get a complete, reusable OIDC client workflow in n8n, ready to plug into your app or internal tools.

When You'd Want To Use This Template

Wondering if this is for you? This workflow is a great fit if you:

• Use Keycloak as your identity provider
• Want to integrate OIDC login into an app, portal, or internal tool via n8n
• Prefer not to hand-code the full OAuth2 / OIDC flow
• Care about security and want PKCE support
• Need a simple way to show logged-in vs logged-out pages

In short, if you want to offload authentication to Keycloak while keeping your logic in n8n, this template makes your life much easier.

High-Level Flow: How the OIDC Client Works

Here's the basic story of what happens when someone hits your webhook URL:

1. n8n receives the request via a Webhook node.
2. The workflow loads all the important OIDC settings (endpoints, client ID, scope, etc.).
3. It checks any cookies to see if there is already a session.
4. If there is an authorization code in the URL, it exchanges that for an access token.
5. With the access token, it calls the userinfo endpoint to get the user's profile.
6. If everything checks out, it shows a welcome page with the user's email.
7. If not logged in yet, it shows a login form that kicks off the OIDC flow with PKCE.

Let's walk through each part of the workflow so you know exactly what's going on under the hood.

Step-by-Step: Inside the n8n OIDC Workflow

1. Webhook Trigger – Your Entry Point

Everything starts with the Webhook node. This is the URL that:

• Receives the initial request when a user visits your app entry page
• Acts as the redirect URI when Keycloak sends back the authorization code

When you configure your OIDC client in Keycloak, this webhook URL is what you'll set as the redirect_uri. It is basically the "home base" of your login flow.

2. Set Variables – Central Place for OIDC Settings

Next, the workflow uses a Set Variables node to store all the important configuration values. This keeps everything clean, editable, and in one place. In this node, you'll define things like:

• auth_endpoint – Your Keycloak authorization endpoint
• token_endpoint – Where the workflow exchanges the authorization code for a token
• userinfo_endpoint – The endpoint to get user profile data
• client_id and optionally client_secret
• scope – Usually includes openid for OIDC
• redirect_uri – The same URL as your webhook
• A flag to enable or disable PKCE

Once this is set up, you rarely need to touch the rest of the logic. Just update these values if your Keycloak config changes.

3. Parsing Cookies – Managing Sessions

Then comes a Code node that parses cookies from the incoming HTTP headers. Why does that matter?

Because cookies help you:

• Track whether a user is already authenticated
• Manage simple session data between requests

The Code node reads the Cookie header, breaks it down into usable key-value pairs, and makes that information available to the rest of the workflow.

4. Authorization Code Check – Are We Coming Back From Login?

At this point, the workflow needs to figure out what kind of request it is dealing with:

• A user visiting for the first time, or
• A user returning from Keycloak with an authorization code

This is handled by an IF node, often labeled something like "IF we have code in URI and not in PKCE mode". It checks:

• Is there an authorization code in the query string?
• Is PKCE disabled, so we can do a straightforward code exchange?

If the conditions are met, the workflow moves on to exchange that code for an access token.

5. Token Exchange – Swapping Code for Access Token

When the workflow has an authorization code and conditions are right, it uses an HTTP Request node to call the token_endpoint. This request includes:

• The code from the URL
• Your client_id (and possibly client_secret if you are using one)
• The redirect_uri
• Any PKCE-related parameters if PKCE is enabled

The response from this request should contain an access token that the workflow can use to call the userinfo endpoint.

6. Checking for Access Token – Did It Work?

After the token exchange, another IF node checks whether an access token was actually returned. This is often labeled something like "IF token is present".

If a valid token exists, the workflow can safely move on to the next step. If not, it can handle the error or send the user back to a login page.

7. Fetching User Info – Getting the Profile

Once the workflow has an access token, it uses another HTTP Request node to hit the userinfo_endpoint. This call usually includes:

• An Authorization: Bearer <access_token> header

The identity provider (Keycloak in this case) responds with user profile data, such as email and other claims, depending on your configuration and scopes.

8. Validating User Info – Making Sure Everything Is OK

Now the workflow needs to confirm that the userinfo response is valid. An IF node, often named "IF user info ok", checks whether:

• The userinfo request succeeded
• Expected fields like email or subject are present

If everything looks good, the workflow treats the user as authenticated and can render a personalized page.

9. Rendering Pages – Login vs Welcome

Finally, the workflow decides what to show the user. There are typically two possible outputs:

• Welcome Page
  If the user is successfully authenticated, the workflow returns an HTML page with a friendly greeting. This usually includes the user's email from the userinfo response so you can say something like "Welcome back, user@example.com".
• Login Form
  If the user is not logged in yet, the workflow returns an HTML login page. This page:
  • Presents an OIDC login form
  • Supports PKCE so the flow is secure even for public clients
  • Redirects the user to Keycloak for authentication

These HTML templates are part of the workflow, so you can tweak them to match your own brand and user experience.

Quick Setup Guide: Connecting Keycloak to the Workflow

Let's talk about how to wire this up with Keycloak. The good news is that it is pretty straightforward. Here is a simple checklist you can follow:

1. Open the Keycloak admin console.
2. Go to Realm settings and open OpenID Endpoint Configuration.
3. Copy the following URLs:
   • authorization_endpoint
   • token_endpoint
   • userinfo_endpoint

   Paste these into the Set Variables node in your n8n workflow.

4. Under Clients, create a new client and give it a name of your choice.
5. During client configuration:
   • Disable Client authentication
   • Enable only Standard flow
6. In the client's Login settings, add your n8n webhook URL to Valid redirect URIs. This must match the redirect_uri you set in the workflow.
7. Copy the client ID you created and set it in the Set Variables node as client_id.

After that, just activate the workflow in n8n and visit the webhook URL in your browser to test the login flow.

Why PKCE Matters For Your OIDC Flow

You might be wondering, "Do I really need PKCE?" In many cases, yes, you do.

PKCE (Proof Key for Code Exchange) is an extension to OAuth2 that adds an extra layer of security on top of the authorization code flow. It is especially important for:

• Public clients that cannot safely store a client secret
• Browser-based apps and mobile apps

With PKCE, the client generates a one-time secret that is used when requesting the authorization code and again when exchanging that code for a token. This helps protect against attacks where someone tries to intercept the authorization code and use it themselves.

The nice part is that this n8n workflow is already designed with PKCE support in mind, so you can take advantage of that without building the logic from scratch.

Make It Yours: Customizing the Experience

Out of the box, the template gives you a working OIDC login and welcome flow. But you do not have to stop there.

Bonus tip: You can customize the HTML templates in the workflow so they match your own branding. Change the colors, add your logo, tweak the text, or embed the login and welcome views into a larger page layout. The logic stays the same, but the user experience becomes fully yours.

Try the OIDC Client Workflow With n8n and Keycloak

If you are building a secure authentication system with OpenID Connect and want to keep your logic in n8n, this workflow template is a huge time saver. Instead of wrestling with tokens, endpoints, and redirects by hand, you get a complete, working example that you can adapt to your needs.

Use it to:

• Streamline user login flows
• Integrate Keycloak authentication into your existing tools
• Experiment with OIDC and PKCE in a visual, low-code way

Have questions, want to extend it further, or ran into something odd in your setup? Feel free to reach out or drop a comment. This kind of workflow is a great foundation to build on.