Keycloak as an Identity Provider for Cloudflare Access. Use Keycloak as an OIDC identity provider for Cloudflare Access (Zero Trust): configure the integration, pass groups for policies, and protect apps behind Cloudflare.
Last updated: November 2026
Cloudflare Access (part of Cloudflare Zero Trust) supports generic OIDC identity providers, so you can use Keycloak as the login source for applications protected behind Cloudflare. You register Cloudflare Access as a confidential OIDC client in Keycloak, configure the generic OIDC identity provider in the Zero Trust dashboard with your realm’s discovery endpoints, and optionally pass a groups claim so Cloudflare Access policies can allow or deny by Keycloak group membership. The result is an identity-aware proxy in front of your internal apps that delegates authentication entirely to your Keycloak realm.
How Cloudflare Access Works
Cloudflare Access is an identity-aware reverse proxy. Instead of exposing an internal application directly to the internet or relying on a VPN, you route traffic through Cloudflare. When a user visits a protected application, Access intercepts the request, checks whether the user has a valid session, and, if not, redirects them to your configured identity provider. After authentication, Access issues a signed JWT (Cf-Access-Jwt-Assertion) that it attaches to every proxied request. Your origin application can validate that JWT to confirm the request came through Cloudflare and was authenticated by your IdP.
This model maps directly onto the principles described in the zero trust authentication with Keycloak guide: verify identity before granting access, enforce policy at the network edge, and treat every request as untrusted by default.
Access supports several IdP types out of the box (Google, GitHub, Azure AD, Okta) as well as a generic OIDC option that works with any standards-compliant OIDC provider, including Keycloak. That generic OIDC path is what this guide uses.
Prerequisites
- A Cloudflare Zero Trust account (Free tier works for testing; Teams or Enterprise for production)
- A running Keycloak 26.x instance accessible over HTTPS from Cloudflare’s edge (or exposed via a Cloudflare Tunnel)
- A realm in Keycloak, this guide uses
myrealmas the placeholder - Admin access to the Keycloak admin console
If you are not yet running Keycloak in a production-ready configuration, review how to run Keycloak behind a reverse proxy to make sure your instance is correctly fronted and reachable with a valid TLS certificate.
Step 1: Register Cloudflare Access as an OIDC Client in Keycloak
Cloudflare Access authenticates users via the standard OIDC authorization code flow. Keycloak needs a client registered to represent Cloudflare Access.
Create the Client
- Open the Keycloak admin console at
https://<your-keycloak>/admin/. - Select your realm from the top-left dropdown.
- Navigate to Clients and click Create client.
- Set Client type to
OpenID Connect. - Set Client ID to
cloudflare-access(or any stable identifier you will reference later). - Click Next.
Configure the Client Settings
On the Capability config page:
- Client authentication:
On(this makes it a confidential client, which is required, Cloudflare Access sends a client secret when exchanging the authorization code for tokens) - Authorization:
Off - Authentication flow: ensure
Standard flowis checked
Click Next.
Set the Redirect URI
On the Login settings page, set Valid redirect URIs to the Cloudflare Access callback URL for your team:
https://<your-team-name>.cloudflareaccess.com/cdn-cgi/access/callback
Replace <your-team-name> with the subdomain shown in your Zero Trust dashboard under Settings > Custom Pages or the team domain listed in Settings > General. The exact value is visible at https://one.dash.cloudflare.com/<account-id>/settings/authentication.
Set Web origins to the same Cloudflare Access domain to avoid CORS issues if needed:
https://<your-team-name>.cloudflareaccess.com
Save the client.
Retrieve the Client Secret
After saving, open the Credentials tab on the client page. Copy the Client secret: you will need it when configuring the IdP in Cloudflare.
Step 2: Note the Realm Endpoints
Keycloak exposes OIDC discovery and endpoint URLs under your realm path. For Keycloak 26.x the pattern is:
| Endpoint | URL |
|---|---|
| Discovery (well-known) | https://<keycloak>/realms/myrealm/.well-known/openid-configuration |
| Authorization | https://<keycloak>/realms/myrealm/protocol/openid-connect/auth |
| Token | https://<keycloak>/realms/myrealm/protocol/openid-connect/token |
| Userinfo | https://<keycloak>/realms/myrealm/protocol/openid-connect/userinfo |
| JWKS (certs) | https://<keycloak>/realms/myrealm/protocol/openid-connect/certs |
Cloudflare Access can auto-discover these from the well-known URL, but you may need to supply them individually depending on which fields the dashboard exposes. Keep this table on hand.
For a deeper look at what these endpoints do and how the OIDC flow works end-to-end, see the OpenID Connect explained for developers guide.
Step 3: Add Keycloak as a Generic OIDC Identity Provider in Cloudflare Zero Trust
- Log into the Cloudflare Zero Trust dashboard.
- Navigate to Settings > Authentication.
- Under Login methods, click Add new and choose OpenID Connect.
Fill in the form:
| Field | Value |
|---|---|
| Name | Keycloak (display name in the login selector) |
| App ID (Client ID) | cloudflare-access (the client ID from Step 1) |
| Client secret | The secret copied from the Credentials tab |
| Auth URL | https://<keycloak>/realms/myrealm/protocol/openid-connect/auth |
| Token URL | https://<keycloak>/realms/myrealm/protocol/openid-connect/token |
| Certificate URL | https://<keycloak>/realms/myrealm/protocol/openid-connect/certs |
In the OIDC Claims section, add email to ensure Cloudflare Access can identify users by email. If you intend to use group-based policies (covered in the next section), also add groups here.
Click Save.
Test the Connection
Cloudflare provides a Test button after saving the IdP. Click it. It opens a new browser window that initiates the OIDC flow against your Keycloak realm. If your Keycloak instance is reachable and the redirect URI is correct, you should land on the Keycloak login page. After authenticating with a Keycloak user, the test page confirms success and shows the claims returned.
Common issues at this stage:
invalid_redirect_uri: The callback URL in Keycloak’s Valid redirect URIs does not match thecloudflareaccess.comcallback URL exactly.- Connection timeout: Keycloak is not publicly reachable. If it is on a private network, use a Cloudflare Tunnel to expose it without opening firewall rules.
invalid_client: The client secret is wrong or the client is not set to confidential.
Step 4: Pass Keycloak Groups to Cloudflare Access
Cloudflare Access policies can require membership in a specific identity provider group. To enforce that, Keycloak must include group names in the OIDC token, and Cloudflare must be told to look for them.
This involves two parts: a mapper in Keycloak and a claim configuration in Cloudflare.
Add a Group Membership Mapper in Keycloak
Client scopes and mappers control what appears in Keycloak’s tokens. Understanding this layer is useful background, see Keycloak client scopes vs. roles explained for a full breakdown.
For the cloudflare-access client:
- Open the client in the admin console.
- Click the Client scopes tab.
- Click the dedicated scope link (e.g.,
cloudflare-access-dedicated), then open the Mappers tab. - Click Add mapper > By configuration and select Group Membership.
Configure the mapper:
| Field | Value |
|---|---|
| Name | groups |
| Token Claim Name | groups |
| Full group path | Off (send mygroup not /mygroup) |
| Add to ID token | On |
| Add to access token | On |
| Add to userinfo | On |
Save the mapper.
Now when Keycloak issues tokens for this client, the groups claim will contain an array of group names the authenticated user belongs to:
{
"sub": "a1b2c3d4-...",
"email": "user@example.com",
"groups": ["engineering", "vpn-users"]
}
Enable Groups in the Cloudflare IdP Configuration
Return to Settings > Authentication in the Zero Trust dashboard and edit the Keycloak IdP you created. In the OIDC Claims or Optional Configuration section (the exact label varies by Cloudflare UI version), ensure groups is listed as a claim to request. Some Cloudflare UI versions show a dedicated Groups claim name field, set it to groups to match the mapper.
Save and re-run the Test to confirm the groups claim appears in the returned token preview.
Somewhere to run this that stays patched
Everything above works the same on Skycloak, because it is real upstream Keycloak rather than a fork. What changes is who handles the upgrades, backups and security patches afterwards.
Step 5: Create an Access Application and Policy
With the IdP configured and groups flowing, you can protect an application.
Add the Application
- In the Zero Trust dashboard, go to Access > Applications and click Add an application.
- Choose Self-hosted (for an internal app you expose through Cloudflare) or SaaS (for a third-party application).
- For a self-hosted app, enter the application domain (e.g.,
intranet.example.com) and the origin URL.
Build a Policy
Inside the application configuration, create a policy:
- Policy name:
Keycloak Engineering Group - Action:
Allow - Include rule: Under Identity provider groups, select your Keycloak IdP and enter the group name exactly as it appears in the
groupsclaim, for example,engineering.
This policy allows only users who are authenticated through Keycloak and whose token contains engineering in the groups array. Users in other groups or without a groups claim will see an Access block page.
You can combine multiple rules: for example, allow the engineering group and require an email domain of @example.com. Access evaluates rules with AND logic within a rule block and OR logic across multiple rules.
For a broader discussion of how this kind of access control relates to role-based access in Keycloak, see the SSO implementation guide for developers.
Step 6: Validate the Cloudflare JWT at Your Origin
After a user authenticates, Cloudflare attaches a signed JWT in the Cf-Access-Jwt-Assertion request header before forwarding the request to your origin. Your application can validate this token to confirm:
- The request arrived through Cloudflare Access (not bypassed directly).
- The user was authenticated by your Keycloak realm.
- The token has not expired and has not been tampered with.
The JWT is signed with Cloudflare’s application-specific key pair. You retrieve the public keys from:
https://<your-team-name>.cloudflareaccess.com/cdn-cgi/access/certs
A minimal Node.js validation example using the jsonwebtoken library:
const jwt = require('jsonwebtoken');
const jwksClient = require('jwks-rsa');
const client = jwksClient({
jwksUri: 'https://<your-team-name>.cloudflareaccess.com/cdn-cgi/access/certs'
});
function getKey(header, callback) {
client.getSigningKey(header.kid, function (err, key) {
const signingKey = key.getPublicKey();
callback(null, signingKey);
});
}
function validateCloudflareJwt(token, audience) {
return new Promise((resolve, reject) => {
jwt.verify(token, getKey, { audience }, (err, decoded) => {
if (err) return reject(err);
resolve(decoded);
});
});
}
// In your request handler:
const token = req.headers['cf-access-jwt-assertion'];
const payload = await validateCloudflareJwt(token, '<your-application-audience-tag>');
// payload.email contains the authenticated user's email
// payload.custom contains any custom OIDC claims (including groups if configured)
The audience (aud) is the Application Audience Tag shown in the Cloudflare Access application settings page.
If you want to understand how the JWT structure relates to Keycloak’s own token format, the OpenID Connect explained for developers post covers token anatomy in detail.
Endpoint and Configuration Reference
| Item | Value / Location |
|---|---|
| Cloudflare Access callback URL | https://<team-name>.cloudflareaccess.com/cdn-cgi/access/callback |
| Keycloak auth endpoint | https://<keycloak>/realms/<realm>/protocol/openid-connect/auth |
| Keycloak token endpoint | https://<keycloak>/realms/<realm>/protocol/openid-connect/token |
| Keycloak userinfo endpoint | https://<keycloak>/realms/<realm>/protocol/openid-connect/userinfo |
| Keycloak JWKS endpoint | https://<keycloak>/realms/<realm>/protocol/openid-connect/certs |
| Keycloak well-known discovery | https://<keycloak>/realms/<realm>/.well-known/openid-configuration |
| Cloudflare Access JWKS | https://<team-name>.cloudflareaccess.com/cdn-cgi/access/certs |
| Keycloak client type | Confidential, Standard flow |
| Groups mapper type | Group Membership, claim name: groups |
| JWT header at origin | Cf-Access-Jwt-Assertion |
Managed Keycloak Simplifies This Integration
Running the Keycloak side of this setup requires a reliable, HTTPS-accessible instance with proper CORS headers, session persistence, and a TLS certificate that Cloudflare’s edge can reach. Skycloak’s managed Keycloak hosting handles the infrastructure so you can focus on configuring clients and policies rather than operating Keycloak clusters.
Frequently Asked Questions
Can I use Keycloak with Cloudflare Access?
Yes. Cloudflare Access supports any standard OIDC identity provider through its generic OIDC integration option. You register Cloudflare Access as a confidential client in Keycloak, configure the realm’s authorization and token endpoints in the Zero Trust dashboard, and Cloudflare handles the login flow. The integration uses the standard authorization code flow with PKCE is not required on the server-side confidential client path, so a client secret suffices.
How do I pass Keycloak groups to Cloudflare Access?
Add a Group Membership mapper to the cloudflare-access client in Keycloak and set the Token Claim Name to groups. Then, in the Cloudflare Zero Trust dashboard, add groups as an OIDC claim (or set the Groups claim name field) on the Keycloak IdP configuration. Once both are in place, Cloudflare Access can read Keycloak group membership when evaluating Access policies, and you can write policies that allow or deny by group name.
What is the Cloudflare Access OIDC callback URL?
The redirect URI (callback URL) that Cloudflare Access uses for all OIDC identity providers is https://<your-team-name>.cloudflareaccess.com/cdn-cgi/access/callback. You must add this URL exactly to the Valid redirect URIs list on your Keycloak client, substituting your actual team subdomain. You can find your team name in the Zero Trust dashboard under Settings > General.
Does Keycloak need to be publicly accessible for this integration?
Cloudflare’s edge servers need to reach your Keycloak instance to complete the OIDC token exchange (the back-channel call from Cloudflare to Keycloak’s token endpoint). If Keycloak is on a private network, you can use a Cloudflare Tunnel to create an outbound-only connection that exposes Keycloak to Cloudflare without opening inbound firewall rules. Alternatively, hosting Keycloak on a public endpoint with TLS and IP allowlisting for Cloudflare’s IP ranges is another option.
Can I use Keycloak roles instead of groups in Cloudflare Access policies?
Cloudflare Access policies use the groups claim by convention. You can populate that claim from Keycloak realm roles or client roles by using a User Client Role or User Realm Role mapper instead of a Group Membership mapper, and setting the Token Claim Name to groups. This lets you express access policy in terms of Keycloak roles while presenting them to Cloudflare as groups. The tradeoff is that Cloudflare’s UI labels these as “groups” even though they originate from Keycloak roles, which can be confusing. Using actual Keycloak groups with the Group Membership mapper is generally cleaner.
Conclusion
Connecting Keycloak to Cloudflare Access as a generic OIDC identity provider requires four concrete steps: create a confidential Keycloak client with the Cloudflare callback URL, configure the OIDC IdP in the Zero Trust dashboard with your realm’s endpoints, add a Group Membership mapper so group names appear in tokens, and build Access policies that reference those groups. Once in place, every application protected by Cloudflare Access delegates its authentication to your Keycloak realm, giving you centralized identity control with Cloudflare’s edge enforcement on top.
For organizations already running Keycloak for internal SSO, this integration extends that investment to cover perimeter access without requiring a separate VPN or an additional identity provider subscription. Cloudflare handles the proxy and policy enforcement; Keycloak handles the identity and group data.
If you want to extend this pattern further, for example, adding step-up MFA requirements or device posture checks at the Keycloak layer, the zero trust authentication with Keycloak guide covers those techniques in depth.
Ready to skip the infrastructure work and focus on configuring your integrations? Skycloak managed Keycloak hosting gives you a production-ready Keycloak instance with automatic upgrades, high availability, and full OIDC support out of the box.

