React Keycloak
React bindings for Keycloak
Install
React Keycloak requires:
- React 16.0 or later
keycloak-js
8.0.1 or later
yarn add @react-keycloak/web
or
npm install --save @react-keycloak/web
Getting Started
Setup KeycloakProvider
Wrap your App inside KeycloakProvider
and pass a keycloak
instance as prop
import Keycloak from 'keycloak-js';
import { KeycloakProvider } from '@react-keycloak/web';
// Setup Keycloak instance as needed
const keycloak = new Keycloak();
// Wrap everything inside KeycloakProvider
const 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
keycloak => !keycloak.authenticated;
-
onEvent
, an handler function that receives events launched bykeycloak
, defaults tonull
.It can be implemented as follow
(event, error) => { console.log('onKeycloakEvent', event, error); }
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
{ "idToken": string, "refreshToken": string, "token": string, }
HOC Usage
When a component requires access to Keycloak
, wrap it inside the withKeycloak
HOC.
import { withKeycloak } from '@react-keycloak/web';
const LoginPage = ({ keycloak, keycloakInitialized }) => {
// 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()}>
Login
</button>
</div>
);
};
export default withKeycloak(LoginPage);
Hook Usage (React >=16.8 required)
Alternately, when a component requires access to Keycloak
, you can also use the useKeycloak
Hook.
import { useKeycloak } from '@react-keycloak/web';
export default () => {
// Using array destructuring
const [keycloak, initialized] = useKeycloak();
// or Object destructuring
const { keycloak, initialized } = useKeycloak();
// 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 ${!keycloak.authenticated ? 'NOT ' : ''}authenticated`}</div>
{!!keycloak.authenticated && (
<button type="button" onClick={() => keycloak.logout()}>
Logout
</button>
)}
</div>
);
};
Examples
See inside examples
for various demo implementing this library main features.
Note: The demo apps are not meant to be production-ready nor starter-kit s but just a way to show this module components and their usage.
✨
Contributors Thanks goes to these wonderful people (emoji key):
Mattia Panzeri |
This project follows the all-contributors specification. Contributions of any kind welcome!
If you found this project to be helpful, please consider buying me a coffee.