React-keycloak-easy NPM

React Keycloak Easy

React bindings for Keycloak

Install

React Keycloak requires:

React 16.8 or later
keycloak-js 9.0.2 or later

yarn add react-keycloak-easy

npm install --save react-keycloak-easy

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

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;

Setup KeycloakProvider

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

import { ReactKeycloakProvider } from "react-keycloak-easy";

import keycloak from "./keycloak";

// Wrap everything inside KeycloakProvider
const App = () => {
  return (
    <ReactKeycloakProvider authClient={keycloak}>...</ReactKeycloakProvider>
  );
};

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.
tokenExchangeParams, are parameters used for the token exchange process in Keycloak. Token exchange allows a client to exchange one type of token for another. This is useful for scenarios like accessing resources of another client or performing actions on behalf of another user. Example params:
```
  tokenExchangeParams={{
      client_id: "name_first_client",
      requested_token_type: "urn:ietf:params:oauth:token-type:access_token",
      audience: "name_with_exchange_client",
  }}
```
In this case, you should also track onTokens with type = 'exchange' to handle token updates:

keycloak.onTokens = (tokens) => {
  if (tokens.type === 'exchange') {
    console.log('Token exchange event:', tokens);
  }
};

Additionally, you can access values from tokenExchange and tokenExchangeParsed in Keycloak

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
```
(keycloak) => !keycloak.authenticated;
```
onEvent, an handler function that receives events launched by keycloak, defaults to null.
It can be implemented as follow
```
(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
```
{
  "idToken": string,
  "refreshToken": string,
  "token": string,
  "type": "classic" | "exchange"
}
```

Hook Usage

When a component requires access to Keycloak, you can use the useKeycloak Hook.

import { useKeycloak } from "react-keycloak-easy";

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 (
    <div>
      <div>{`User is ${
        !keycloak.authenticated ? "NOT " : ""
      }authenticated`}</div>

      {!!keycloak.authenticated && (
        <button type="button" onClick={() => keycloak.logout()}>
          Logout
        </button>
      )}
    </div>
  );
};