react-native-keycloak-plugin

react-native-keycloak-plugin

This is a fork of mahomahoxd's react-native-login-keycloak module. I started from that to build some new feature using a functional style.

This plugin exposes some util methods to interact with Keycloak in order to handle the user session.

Documentation

• Install
• Setup
• API
• Utils

Install

Using npm

npm i --save react-native-keycloak-plugin

Using yarn

yarn add react-native-keycloak-plugin

Setup

App configuration

Please configure Linking module, including steps for handling Universal links
This might get changed due to not being able to close the tab on leave, ending up with a lot of tabs in the browser.
[Not needed if you're using React Native >= 0.60]

Also, add the applinks: <APPSITE HOST> entry to the Associated Domains Capability of your app.

Imports

The plugin uses an export default statement, so you can import the variable with:

import Keycloak from 'react-native-keycloak-plugin';

From that variable, you have access to all the util methods the plugin implements.

API

Keycloak.keycloakUILogin

Keycloak.keycloakUILogin(conf, [callback, { scope }])
  .then((response) => /* Your resolve */ )
  .catch((error) => /* Your reject*/ )

Method arguments:

• conf: The JSON configuration object (see the example below).
• callback: By default the plugin try to open the keycloak login url on the default browser. Using this callback you can override this behavior e.g. handling the login flow into a WebView without leaving the app.
• scope: You can override this argument if some custom Keycloak behavior is needed (e.g if you need to handle the Keycloak ID_TOKEN, you have to pass 'offline_access' as value).

config = {
  "realm": "string",
  "auth-server-url": "string",
  "appsiteUri": "string",
  "redirectUri": "string",
  "ssl-required": "string",
  "resource": "string",
  "credentials": {
    "secret": "string"
  },
  "confidential-port": "number",
}

Resolver arguments:

• response: a JSON object containing two fields:
  • tokens: a JSON containing all the tokens returned by Keycloak. If you used'info' as scope the JSON will be as shown below.
  • deepLinkUrl: The redirectUrl with some Keycloak query params added at the end.

response.tokens = {
    "access_token": "string",
    "expires_in": "number",
    "refresh_expires_in": "number",
    "refresh_token": "string",
    "token_type": "string",
    "not-before-policy": "number",
    "session_state": "string",
    "scope": "string",
}

Keycloak.login

Keycloak.login(conf, username, password, options)
    .then((response) => /* Your resolve */ )
    .catch((error) => /* Your reject*/ )

Method arguments:

• conf: The JSON configuration object (see the example above).
• username: The username to be logged in
• password: The password associated to the above username
• options: JSON containing the following fields:
  • scope: same behavior as above
  • storeInfo: boolean, whether the plugin should save the result into the AsyncStorage. Defaults to true

Keycloak.refreshLogin

Keycloak.refreshLogin(options)
    .then((response) => /* Your resolve */ )
    .catch((error) => /* Your reject*/ )

Method arguments:

• options: JSON containing the following fields (all are optional):
  • scope: same behavior as above
  • inputConf: a config object to be used
  • inputCredentials: a JSON Object shaped with { username, password }
  • storeInfo: same behavior as above

Sometimes you may need to re-login your user w/ Keycloak via the login process but, for some reason, you don't want / can't display the login page.
This method will re-login your user.

Manually handling the tokens

import Keycloak, { TokenStorage } from 'react-native-keycloak-plugin'

Logging in by the login function will save the tokens information, and the configuration object into the AsyncStorage.
Through the TokenStorage object, the plugin exports some methods that can be used to interact with these objects.

Keycloak.retrieveUserInfo

Keycloak.retrieveUserInfo({ inputConf, inputTokens })
  .then((userInfo) => /* Your resolve */ );
  .catch((error) => /* Your reject*/ )

Passing a configuration JSON object, makes available into the resolve function the JSON that describes the user inside Keycloak.

Keycloak.refreshToken

Keycloak.refreshToken({ inputConf, inputTokens })
  .then((response) => /* Your resolve */ );
  .catch((error) => /* Your reject*/ )

Passing a configuration JSON object, makes available into the resolve function the JSON containing the refreshed tokens. This information are also saved into the AsyncStorage, as described above.

Keycloak.logout

Keycloak.logout({ destroySession = true, inputConf, inputTokens })
  .then(() => /* Your resolve */ );
  .catch((error) => /* Your reject*/ )

destroySession: Since the /openid-connect/token simply returns an access token and doesn't create any session on Keycloak side, if you used the login method you want to pass false.
Passing true tries to destroy the session: pay attention that on newer Keycloak versions this raises an error if no session is present, preventing the logout.

Utils

TokensUtils.isAccessTokenExpired

import { TokensUtils } from 'react-native-keycloak-plugin';

TokensUtils.isAccessTokenExpired()
  .then(() => /* Your resolve */ );
  .catch((error) => /* Your reject*/ )

This utils method check if the access token saved into the AsyncStorage is still valid or if it's expired. Since it interact witht the AsyncStorage, a promise must be handled.

TokensUtils.willAccessTokenExpireInLessThan

import { TokensUtils } from 'react-native-keycloak-plugin';

TokensUtils.willAccessTokenExpireInLessThan(seconds)
  .then(() => /* Your resolve */ );
  .catch((error) => /* Your reject*/ )

This utils method check if the access token saved into the AsyncStorage will expire in less than <seconds> seconds. Since it interacts with the AsyncStorage, a promise must be handled.