React Keycloak

React bindings for Keycloak

---

Table of Contents

• Install
• Support
• Getting Started
  • Setup Keycloak instance
  • Setup KeycloakProvider
  • HOC Usage
  • Hook Usage (React >=16.8 required)
  • External Usage (Advanced)
• Examples
• Contributors

---

Install

React Keycloak requires:

• React 16.0 or later
• keycloak-js 9.0.2 or later

1yarn add @keycloak-react/web

or

1npm install --save @keycloak-react/web

or as a UMD package through unpkg

• one for development: https://unpkg.com/@keycloak-react/web@latest/dist/umd/react-keycloak-web.js
• one for production: https://unpkg.com/@keycloak-react/web@latest/dist/umd/react-keycloak-web.min.js

Support

version	keycloak-js version
v2.0.0+	9.0.2+
v1.x	>=8.0.2 <9.0.2

Getting Started

Setup Keycloak instance

Create a keycloak.js file in the src folder of your project (where App.js is located) with the following content

1import Keycloak from 'keycloak-js'
2
3// Setup Keycloak instance as needed
4// Pass initialization options as required or leave blank to load from 'keycloak.json'
5const keycloak = new Keycloak()
6
7export default keycloak

Setup KeycloakProvider

Wrap your App inside KeycloakProvider and pass the keycloak instance as prop

1import { KeycloakProvider } from '@keycloak-react/web'
2
3import keycloak from './keycloak'
4
5// Wrap everything inside KeycloakProvider
6const App = () => {
7  return <KeycloakProvider keycloak={keycloak}>...</KeycloakProvider>
8}

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 to keycloak.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 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

  1;(keycloak) => !keycloak.authenticated

• onEvent, an handler function that receives events launched by keycloak, defaults to null.

  It can be implemented as follow

  1;(event, error) => {
  2  console.log('onKeycloakEvent', event, error)
  3}

  Published events are:

  • onReady
  • 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

  1{
  2  "idToken": string,
  3  "refreshToken": string,
  4  "token": string
  5}

HOC Usage

When a component requires access to Keycloak, wrap it inside the withKeycloak HOC.

1import { withKeycloak } from '@keycloak-react/web'
2
3const LoginPage = ({ keycloak, keycloakInitialized }) => {
4  // Here you can access all of keycloak methods and variables.
5  // See https://www.keycloak.org/docs/latest/securing_apps/index.html#javascript-adapter-reference
6  return (
7    <div>
8      <button type="button" onClick={() => keycloak.login()}>
9        Login
10      </button>
11    </div>
12  )
13}
14
15export default withKeycloak(LoginPage)

Hook Usage (React >=16.8 required)

Alternately, when a component requires access to Keycloak, you can also use the useKeycloak Hook.

1import { useKeycloak } from '@keycloak-react/web'
2
3export default () => {
4  // Using array destructuring
5  const [keycloak, initialized] = useKeycloak()
6  // or Object destructuring
7  const { keycloak, initialized } = useKeycloak()
8
9  // Here you can access all of keycloak methods and variables.
10  // See https://www.keycloak.org/docs/latest/securing_apps/index.html#javascript-adapter-reference
11
12  return (
13    <div>
14      <div>{`User is ${
15        !keycloak.authenticated ? 'NOT ' : ''
16      }authenticated`}</div>
17
18      {!!keycloak.authenticated && (
19        <button type="button" onClick={() => keycloak.logout()}>
20          Logout
21        </button>
22      )}
23    </div>
24  )
25}

External Usage (Advanced)

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 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 🤔 💻 📖 🐛 🚧 📦 💬 👀 ⚠️ 💡

JannesD 🐛 💻

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.