Fork of https://github.com/react-keycloak/react-keycloak.git with updated packages for Keycloak >=17. React bindings for Keycloak javascript adapter.
npm install @react-keycloak-fork/webkeycloak-js 17.0.0 or later
shell
yarn add @react-keycloak-fork/web
`
or
`shell
npm install --save @react-keycloak-fork/web
`
Getting Started
$3
Create a keycloak.js file in the src folder of your project (where App.js is located) with the following content
`js
import Keycloak from 'keycloak-js'
// Setup Keycloak instance as needed
// Pass initialization options as required or leave blank to load from 'keycloak.json'
const keycloak = new Keycloak()
export default keycloak
`
$3
Wrap your App inside ReactKeycloakProvider and pass the keycloak instance as prop
`js
import { ReactKeycloakProvider } from '@react-keycloak-fork/web'
import keycloak from './keycloak'
// Wrap everything inside KeycloakProvider
const App = () => {
return (
...
)
}
`
N.B. If your using other providers (such as react-redux) it is recommended to place them inside ReactKeycloakProvider.
ReactKeycloakProvider automatically invokes keycloak.init() method when needed and supports the following props:
- initOptions, contains the object to be passed to keycloak.init() method, by default the following is used
{
onLoad: 'check-sso',
}
for more options see Keycloak docs.
- LoadingComponent, a component to be displayed while keycloak is being initialized, if not provided child components will be rendered immediately. Defaults to null
- isLoadingCheck, an optional loading check function to customize LoadingComponent display condition. Return true to display LoadingComponent, false to hide it.
Can be implemented as follow
`js
;(keycloak) => !keycloak.authenticated
`
- onEvent, an handler function that receives events launched by keycloak, defaults to null.
It can be implemented as follow
`js
;(event, error) => {
console.log('onKeycloakEvent', event, error)
}
`
Published events are:
- onReady
- onInitError
- onAuthSuccess
- onAuthError
- onAuthRefreshSuccess
- onAuthRefreshError
- onTokenExpired
- onAuthLogout
- onTokens, an handler function that receives keycloak tokens as an object every time they change, defaults to null.
Keycloak tokens are returned as follow
`json
{
"idToken": string,
"refreshToken": string,
"token": string
}
`
$3
When a component requires access to Keycloak, you can use the useKeycloak Hook.
`js
import { useKeycloak } from '@react-keycloak-fork/web'
export default () => {
// Using 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 (
{User is ${
!keycloak.authenticated ? 'NOT ' : ''
}authenticated}
{!!keycloak.authenticated && (
)}
)
}
`
$3
If you need to access keycloak instance from non-React files (such as sagas, utils, providers ...), you can import the instance directly from the keycloak.js file.
The instance will be initialized by react-keycloak but you'll need to be carefull when using the instance and avoid setting/overriding any props, you can however freely access the exposed methods (such as refreshToken, login, etc...).
Examples
See inside examples folder of @react-keycloak-fork/react-keycloak-examples repository for various demo implementing this library main features.
Guides and Articles
- Migration guide for @react-keycloak-fork/web v2.x to v3.x can be found here MIGRATION.md.
- Secure React Routes & Component with Keycloak, a (slightly outdated) guide on how to setup Keycloak and create secured contents in a React app, thanks to @cagline for the detailed article.
Alternatives
If you need to connect using a more generic OIDC client instead of keycloak.js`, consider using one of the following libraries: