React Keycloak
React bindings for Keycloak
Install
React Keycloak requires:
- React 16.0 or later
- a version of
keycloak-js
matching the main version (e.g."react-keycloak": "8.0.1"
=>"keycloak-js": "8.0.1-yymmdd"
)
yarn add react-keycloak
or
npm install --save react-keycloak
Getting Started
Setup KeycloakProvider
Wrap your App inside KeycloakProvider
and pass a keycloak
instance as prop
;; // Setup Keycloak instance as neededconst keycloak = ; // Wrap everything inside KeycloakProviderconst App = { return <KeycloakProvider keycloak=keycloak>...</KeycloakProvider>;};
N.B. If your using other providers (such as react-redux
) it is recommended to place them inside KeycloakProvider
.
KeycloakProvider
automatically invokes keycloak.init()
method when needed and supports the following props:
-
initConfig
, contains the object to be passed tokeycloak.init()
method, by default the following is used{ onLoad: 'check-sso', promiseType: 'native', }
for more options see Keycloak docs.
-
LoadingComponent
, a component to be displayed whilekeycloak
is being initialized, if not provided child components will be rendered immediately. Defaults tonull
-
isLoadingCheck
, an optional loading check function to customize LoadingComponent display condition. Returntrue
to display LoadingComponent,false
to hide it.Can be implemented as follow
!keycloakauthenticated; -
onEvent
, an handler function that receives events launched bykeycloak
, defaults tonull
.It can be implemented as follow
{console;}Published events are:
onReady
onAuthSuccess
onAuthError
onAuthRefreshSuccess
onAuthRefreshError
onTokenExpired
onAuthLogout
-
onTokens
, an handler function that receiveskeycloak
tokens as an object every time they change, defaults tonull
.Keycloak tokens are returned as follow
HOC Usage
When a component requires access to Keycloak
, wrap it inside the withKeycloak
HOC.
; const LoginPage = { // Here you can access all of keycloak methods and variables. // See https://www.keycloak.org/docs/latest/securing_apps/index.html#javascript-adapter-reference return <div> <button type="button" onClick= keycloak> Login </button> </div> ;}; LoginPage;
Hook Usage (React >=16.8 required)
Alternately, when a component requires access to Keycloak
, you can also use the useKeycloak
Hook.
; { // Using array destructuring const keycloak initialized = ; // or Object destructuring const keycloak initialized = ; // Here you can access all of keycloak methods and variables. // See https://www.keycloak.org/docs/latest/securing_apps/index.html#javascript-adapter-reference return <div> <div>`User is authenticated`</div> !!keycloakauthenticated && <button type="button" onClick= keycloak> Logout </button> </div> ;};
Demo
See inside src/demo
for a demo implementing this library main features.
To run the demo app:
- Clone/Download this repo
- Install dependencies (
npm install
oryarn
) - Place a valid
keycloak.json
file insidepublic
folder or setupKeycloak
instance insidesrc/demo/App.js
following Keycloak guide - Run the demo (
npm start
oryarn start
)
Note: The demo app is not meant to be production-ready nor a starter-kit but just a way to show this module components and their usage.
Credits
Library bootstrapped using DimiMikadze/create-react-library and inspired by react-redux
Made with ✨ & ❤️ by Mattia Panzeri and contributors
If you found this project to be helpful, please consider buying me a coffee.