{"id":36607432,"url":"https://github.com/sventorben/keycloak-restrict-client-auth","last_synced_at":"2026-01-12T08:46:44.565Z","repository":{"id":37090615,"uuid":"365358650","full_name":"sventorben/keycloak-restrict-client-auth","owner":"sventorben","description":"A Keycloak authenticator to restrict authorization on clients","archived":false,"fork":false,"pushed_at":"2025-12-10T19:29:46.000Z","size":1353,"stargazers_count":391,"open_issues_count":11,"forks_count":29,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-12-11T06:38:02.395Z","etag":null,"topics":["access-control","access-management","authentication","authorization","client","flow","keycloak","keycloak-authenticator","keycloak-extension","keycloak-provider","keycloak-spi","restriction","roles","roles-management","user-identity"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sventorben.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-05-07T21:38:37.000Z","updated_at":"2025-12-10T19:28:52.000Z","dependencies_parsed_at":"2023-02-14T05:45:57.817Z","dependency_job_id":"c47e7eaa-6e23-4f59-9524-73c0fc14e876","html_url":"https://github.com/sventorben/keycloak-restrict-client-auth","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/sventorben/keycloak-restrict-client-auth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sventorben%2Fkeycloak-restrict-client-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sventorben%2Fkeycloak-restrict-client-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sventorben%2Fkeycloak-restrict-client-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sventorben%2Fkeycloak-restrict-client-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sventorben","download_url":"https://codeload.github.com/sventorben/keycloak-restrict-client-auth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sventorben%2Fkeycloak-restrict-client-auth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28337599,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access-control","access-management","authentication","authorization","client","flow","keycloak","keycloak-authenticator","keycloak-extension","keycloak-provider","keycloak-spi","restriction","roles","roles-management","user-identity"],"created_at":"2026-01-12T08:46:44.009Z","updated_at":"2026-01-12T08:46:44.558Z","avatar_url":"https://github.com/sventorben.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Keycloak: Restrict user authorization on clients\n\nThis is a simple Keycloak authenticator to restrict user authorization on clients.\n\n![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/sventorben/keycloak-restrict-client-auth?sort=semver)\n![Keycloak Dependency Version](https://img.shields.io/badge/Keycloak-26.4.7-blue)\n![GitHub Release Date](https://img.shields.io/github/release-date-pre/sventorben/keycloak-restrict-client-auth)\n![Github Last Commit](https://img.shields.io/github/last-commit/sventorben/keycloak-restrict-client-auth)\n\n![CI build](https://github.com/sventorben/keycloak-restrict-client-auth/actions/workflows/buildAndTest.yml/badge.svg)\n![open issues](https://img.shields.io/github/issues/sventorben/keycloak-restrict-client-auth)\n[![CodeScene Code Health](https://codescene.io/projects/25589/status-badges/code-health)](https://codescene.io/projects/25589)\n\n## Quick introduction (Video interview with Niko Köbler)\n[![Youtube Video - Interview with Niko Köbler](https://img.youtube.com/vi/eQjOCrcit24/0.jpg)](https://www.youtube.com/watch?v=eQjOCrcit24)\n\n## What is it good for?\n\nAs a Keycloak consultant, I often receive inquiries about restricting user authorization for specific clients. People commonly ask,\n\n\u003e Can I allow certain users to authenticate with a client while denying access to others?\n\nWhile the answer used to be \"no\" for out-of-the-box Keycloak, I have developed this extension to meet this need.  but I recommend taking the time to understand the potential security implications before using this extension.\n\nSo, before using this extension, please take a moment to review the security considerations outlined in the  [security consideration](#security-considerations) section.\n\n## How does it work?\n\nThe authenticator can work either role-based or policy-based.\n\n### Role-based mode\n\nIn this mode, the authenticator uses client roles to restrict authentication. It works like this:\n\n* The authenticator checks whether a client defines a role named `restricted-access`\n    * If it does the authenticator checks whether the user has that role\n        * If it does, the authenticator returns success (i.e. authentication is successful)\n        * If it does not, the authenticator returns failure (i.e. authentication is unsuccessful)\n    * If it does not, the authenticator returns success (i.e. authentication is successful).\n\nThis means that you can enable the authenticator on a per-client basis by adding a client role named `restricted-access` to your client.\nA client with that role has the authenticator enabled. Only users with that role can authenticate to that client.\n\n### Policy-based mode\n\nIn this mode, the authenticator uses client resources, permissions and policies to restrict authentication.\nThis mode only works for confidential OIDC clients with authorization enabled.\nIt works like this:\n\n* The authenticator checks whether a client defines a resource named `Keycloak Client Resource`\n    * If it does, the authenticator checks whether policies and permission evaluate to `PERMIT`\n        * If it does, the authenticator returns success (i.e. authentication is successful)\n        * If it does not, the authenticator returns failure (i.e. authentication is unsuccessful)\n    * If it does not, the authenticator returns success (i.e. authentication is successful).\n\nThis means that you can enable the authenticator on a per-client basis by adding a resource named `Keycloak Client Resource` to your client.\nA client with that resource has the authenticator enabled. Users will only be able to authenticate to such a client if the associated policies and permission permit access.\n\n## How to install?\n\nDownload a release (*.jar file) that works with your Keycloak version from the [list of releases](https://github.com/sventorben/keycloak-restrict-client-auth/releases).\nFollow the below instructions depending on your distribution and runtime environment.\n\n### Standalone (without container)\n\nCopy the jar to the `providers` folder and execute the following command:\n\n```shell\n${kc.home.dir}/bin/kc.sh build\n```\n\n### Container image (Docker)\n\nFor Docker-based setups mount or copy the jar to `/opt/keycloak/providers`.\n\nIf you are using RedHat SSO instead of Keycloak open source, mount or copy the jar to `/opt/eap/providers/`.\n\nYou may want to check [docker-compose.yml](docker-compose.yml) as an example.\n\n### Maven/Gradle\n\nPackages are being released to GitHub Packages. You find the coordinates [here](https://github.com/sventorben/keycloak-restrict-client-auth/packages/779937/versions)!\n\nIt may happen that I remove older packages without prior notice, because the storage is limited on the free tier.\n\n## How to configure?\n\n* Create a new flow per binding (e.g. browser flow, direct grant flow etc.)\n* Add a sub-flow e.g. named `Login` and mark it as `Required`\n* Add an authenticator execution `Restrict user authentication on clients` and mark the execution as `Required`.\n* Within the `Login` sub-flow add authenticators/executions/conditionals and further sub-flows as needed (\n  see [Keycload documentation for details](https://www.keycloak.org/docs/latest/server_admin/#_authentication-flows)\n* Then bind your newly created flow as desired - either as a default for the whole realm or on a per-client basis.\n\n  See the image below for an example.\n![Example flow](docs/images/flow.jpg)\n\n* Follow instructions below in section [Client Role based mode](#client-role-based-mode) or [Resource Policy based mode](#resource-policy-based-mode) for the desired mode, respectively.\n\n\u003e ⚠️ **User identity**:\n\u003e\n\u003e The authenticator needs a user identity to check whether the user has the desired role or not. Hence, ensure that you have steps/executions in your flow prior to this authenticator that can ensure user's identity.\n\n### Client Role based mode\n\n1) Configure the authenticator by clicking on `Actions -\u003e Config` and select `client-role` as the `Access Provider`.\n![Role-based access restriction](docs/images/config-client-role-based.jpg)\n2) Add a role named `restricted-access` to the client you want to restrict access to.\n\n   See the image below for an example.\n![Client role configuration](docs/images/client-role.jpg)\n3) Afterwards, no user can authenticate to this client. To allow a user to authenticate, assign the role `restricted-access` to the user. You may do so either by assigning the role to the user directly or via groups or combined roles.\n\n#### Changing the role name\n\nYou do not like the role name `restricted-access` or you do have some kind of naming conventions in place? You can change the role name globally by configuring the provider.\n\n```properties\nspi-restrict-client-auth-access-provider-client-role-enabled=true\nspi-restrict-client-auth-access-provider-client-role-client-role-name=custom-role\n```\n\nFor details on SPI and provider configuration, please refer to [Configuring providers](https://www.keycloak.org/server/configuration-provider) guide.\n\n### Resource Policy based mode\n\n\u003e ⚠️ **OIDC only**:\n\u003e\n\u003e Policy-based mode only works with OIDC clients (`Client Protocol` must be `openid-connect`)\n\n\n1) Configure the authenticator by clicking on `Actions -\u003e Config` and select `policy` as the `Access Provider`.\n![Policy-based access restriction](docs/images/config-policy-based.jpg)\n2) Configure the `Access Type` of the client to `confidential`\n3) Set `Authorization Enabled` to `on`\n4) Go to `Authorization -\u003e Resources` and click `Create` to create a new resource\n   ![Resource configuration](docs/images/resource-config.jpg)\n5) Set the `Name` and `Display name` to `Keycloak Client Resource` and keep the other fields blank\n6) Save the resource\n   ![Resources overview](docs/images/resource.jpg)\n7) Click `Create Permission` to add permissions and policies (see [Authorization Services Guide](https://www.keycloak.org/docs/latest/authorization_services/#_permission_overview) for details)\n8) Afterwards, no user can authenticate to this client unless permissions have been granted by configured policies.\n\n### Using a custom error message\n\nIf a user tries to log in via a browser-based flow and access gets denied by the authenticator, a custom error message can be displayed.\nIn the flow choose the `Actions` button and then choose `Config`. You will see the following configuration screen.\n\n![Error message configuration](docs/images/config-message.jpg)\n\nYou can directly define a particular message or use a property, which will be used for mapping the error message. If you choose a property, the property will be looked up from your custom theme's `messages*.properties` files and therefore supports internationalization.\n\n```properties\n# messages.properties\nrestricted-access.denied=Access denied. User is missing required role 'restricted-access'\n# messages_de.properties\nrestricted-access.denied=Zugriff verweigert. Dem Benutzer fehlt die notwendige Rolle 'restricted-access'.\n```\n\nIf the field is left blank, default property `access-denied` is used. In this case you do not need a custom theme, since this property comes with Keycloak out of the box.\nFor details on how to add custom messages to Keycloak, please refer to section [Messages and Internationalization](https://www.keycloak.org/docs/latest/server_development/#messages) in the server developer guide.\n\n### Configuring Post-Authentication Flows for Identity Provider Redirects\nWhen your authentication flow includes an identity provider redirect (e.g., using the organization feature, Identity Provider Redirector, or Home IDP Discovery Extension), Keycloak does not execute subsequent steps in the authentication flow after the redirect. To work around this limitation, you can configure a post-login flow for the identity provider. This ensures that the required steps, such as authorization checks, are applied after authentication with the external identity provider.\n\nFollow these steps to configure your post-login flow:\n\n1) Create a Custom Authentication Flow:\n    * Log in to the Keycloak Admin Console with your administrator credentials.\n    * Go to `Authentication` from the left-hand menu.\n    ![AuthFlow_Authentication](https://github.com/user-attachments/assets/89021a3a-6961-4553-9556-705e74a04855)\n    * Under the `Flows` tab, click `Create Flow`.\n    ![AuthFlow_CreateFlow](https://github.com/user-attachments/assets/5e1d0602-5c46-4583-83e2-7b9756a584a7)\n    * Enter a name for the flow, such as `Restrict Authentication Post Login Flow`, and select `Generic` as the flow type.\n    * Click `Save`.\n    * After creating the flow, click `Add Step` to add steps to the flow.\n    * Add the step `Restrict User Authentication on Clients` to ensure authorization checks are applied.\n\n\n2) Assign the Post-Login Flow to the Identity Provider:\n\n    * Go to `Identity Providers` in the Keycloak Admin Console.\n    ![AuthFlow_google](https://github.com/user-attachments/assets/2c8c6d17-007b-487c-8669-05c7c7827c1d)\n    * Select the identity provider (e.g., \"Google\") used in the redirect flow.\n    * In the IDP settings, locate the `Post login flow` option.\n    * Assign the newly created authentication flow (e.g., `Restrict Authentication Post Login Flow`) to this setting.\n    ![image](https://github.com/user-attachments/assets/80e1d092-25c5-4a4b-9eb5-1f7db5a93a22)\n\nThis configuration ensures that the post-login flow is applied whenever the identity provider is used for authentication. It allows the necessary checks and steps to be enforced even though Keycloak does not execute steps following the identity provider redirect.\n\n#### Why This Configuration is Necessary\nKeycloak currently skips subsequent steps in the authentication flow after an identity provider redirect. This is a known issue tracked in the Keycloak repository [issue #10250](https://github.com/keycloak/keycloak/issues/10250#issuecomment-2556581319). Using a post-login flow as described above is the recommended workaround for scenarios where additional steps, such as client-specific authorization checks, are needed after authentication via an external identity provider.\n\n## Client Policy support\n\n\u003e ⚠️ **Feature preview**:\n\u003e\n\u003e Support for client policies is currently feature preview. I am happy to get some feedback on this.\n\u003e However, depending on feedback the feature may be changed  or even be removed again in the future.\n\nSince version 18.1.0 this extension has basic built-in support for [client policies](https://www.keycloak.org/docs/latest/server_admin/#_client_policies).\n\n### Conditions\nThis extension provides a [client policy condition](https://www.keycloak.org/docs/latest/server_admin/#condition) named `restrict-client-auth-enabled` to check whether user authentication on a client has been restricted or not.\n\n### Executors\nThis extension provides a [client policy executor](https://www.keycfloak.org/docs/latest/server_admin/#executor) named `restrict-client-auth-auto-config` to automatically enable restricted access for clients. The executor can be cofigured to either enable restricted access based on resource policies or based on client role.\n\n## Security considerations\n\n### Policy enforcement\nTo avoid any confusion, it is important to note that this extension is not a policy enforcement point (PEP).\nIt does not enforce authorization decisions. It is part of making the authorization decision, but it does not enforce it.\nClients must enforce decisions being made.\n\nAccording to the [OIDC specification/OpenID Connect Core 1.0 incorporating errata set 1](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation), it is the responsibility of the client to check the audience claims. Section 3.1.3.7. ID Token validation, point 3ff state that\n\u003e The Client MUST validate that the `aud` (audience) Claim contains its `client_id` value registered at the Issuer identified by the `iss` (issuer) Claim as an audience. [...]\n\nAnd further it is very clear about the enforcement by the client:\n\u003e The ID Token MUST be rejected if the ID Token does not list the Client as a valid audience, or if it contains additional audiences not trusted by the Client.\n\u003e If the ID Token contains multiple audiences, the Client SHOULD verify that an `azp` Claim is present.\n\u003e If an `azp` (authorized party) Claim is present, the Client SHOULD verify that its client_id is the Claim Value.\n\nSo, by design this extension cannot be a PEP.\n\nWhat this extension supports you with is authorization decision-making and communicating the outcome to the user during login flow. If configured correctly, it will prevent issuance of tokens that contain an audience or authorized party claim for a client that users do not have access to.\n\nToken issuance or non-issuance is (beside claims in the token) just one way to communicate the outcome of authorization decision-making. It is not enforcement of the decision.\n\nMake sure your clients enforce decisions correctly and ensure validation auf `aud` (audience) and `azp` (authorized party) claims.\n\nIf you are using a Keycloak adapter, make sure your clients are verifying the audience claim by enabling `verify-token-audience` in your [adapter config](https://www.keycloak.org/docs/latest/securing_apps/#_java_adapter_config).\n\n### Protect all possible flows\n\nEnsure that you protect authentication to your clients in all flows a user may access. This includes not just the browser flow or the other realm-wide flows, but also identity provider overrides and post login flows.\n\nHere is one example: suppose a user tries to log in via the built-in browser flow, at the end of which you have added the \"Restrict user authentication on clients\" step. If the \"Cookie\" or \"Forms\" alternative is used, the user will proceed to this step and be evaluated. But if it is the \"Identity Provider Redirector\" alternative which gets used, the subsequent steps will be skipped and the user will not be subject to this validation (this is a general feature of how brokering works in Keycloak authentication flows, not specific to this plugin). This extension must also be configured in the identity provider's post login flow in order to apply.\n\n#### Identity Provider redirects\nTo ensure proper enforcement of authorization checks when using identity provider redirects in your authentication flow (e.g., with the Identity Provider Redirector, organization feature, or Home IDP Discovery Extension), Keycloak does not automatically execute subsequent steps after the redirect. You must configure a post-login flow for the identity provider to apply the necessary checks. For detailed steps, refer to [Configuring Post-Authentication Flows for Identity Provider Redirects](#configuring-post-authentication-flows-for-identity-provider-redirects).\n\n### Disable the `Audience Resolve` mapper if necessary\nThe [`Audience Resolve` protocol mapper](https://www.keycloak.org/docs/latest/server_admin/#_audience_resolve) is enabled by default by client scope `roles`, but it may be necessary to remove it in some cases.\nFailing to set up audience claims correctly may result in a token containing the restricted client as an audience claim, even if the user does not have access to that client.\n\n## Frequently asked questions\n\n### Does it work with Keycloak version X.Y.Z?\n\nIf you are using Keycloak version `X` (e.g. `X.y.z`), version `X.b.c` should be compatible.\nKeycloak SPIs are quite stable. So, there is a high chance this authenticator will work with other versions, too. Check the details of latest [compatibility test run](https://github.com/sventorben/keycloak-restrict-client-auth/actions/workflows/matrix.yml) for an overview or simply give it a try.\n\nAuthenticator version `X.b.c` is compiled against Keycloak version `X.y.z`. For example, version `16.3.1` will be compiled against Keycloak version `16.y.z`.\n\nI do not guarantee what version `a.b` or `y.z` will be. Neither do I backport features to older version, nor maintain any older versions of this authenticator. If you need the latest features or bugfixes for an older version, please fork this project or update your Keycloak instance. I recommend doing the latter on regular basis anyways.\n\n### Why not use \"Allow/Deny Access\" authenticators with conditions?\n\nWith Keycloak 13 two new authenticators have been added, namely `Allow Access` and `Deny Access`. Together with `Condition - User Role` authenticator authentication may be restricted in a similar way with out-of-the-box features. So, the question is why not use that and override authentication flows on a per client basis?\n\nHere are some reasons/thoughts\n* It is not really flexible. Since `Condition - User Role` only allows for checking one concrete (realm or client-specific) role, a very complex flow handling all clients, or a totally separate flow for each individual client would be needed.\n* It simply does not work well with federated authentication (ie. identity provider redirects), since there is no way to configure client specific behaviour for `First login flow` or `Post login flows`. In other words, there is no feature like `Authentication flow overrides` at an IdP level. Hence, the same flow will be used for all clients. As said before, this becomes very complicated.\n\n### Getting error KC-SERVICES0013: Failed authentication\n\nWhen getting an error or warning like this,\n```\nWARN  [org.keycloak.authentication.DefaultAuthenticationFlow] (default task-26) REQUIRED and ALTERNATIVE elements at same level! Those alternative executions will be ignored: [auth-cookie, identity-\nprovider-redirector, null]\nWARN  [org.keycloak.services] (default task-26) KC-SERVICES0013: Failed authentication: org.keycloak.authentication.AuthenticationFlowException: authenticator: restrict-client-auth-authenticator\n```\n\nyou have mostlikely mixed required and alternative subflows/steps/authenticators at the same level in your custom flow.\nKeycloak does not support this.\n\nMake sure you do not combine required and alternative authenticators at the same level.\nSee the following image for details:\n\n![Flow explained](docs/images/flow_explained.jpg)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsventorben%2Fkeycloak-restrict-client-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsventorben%2Fkeycloak-restrict-client-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsventorben%2Fkeycloak-restrict-client-auth/lists"}