Connect Session

A thin wrapper around the Reapit Connect OAuth API.

Managing OAuth flows can be tricky, especially redirecting, keeping sessions refreshed and cached in memory. To make this process easier, we have built the Connect Session module for any JavaScript app.

To get started run

``bash
$ yarn add @reapit/connect-session
`

Then follow the steps for either browsers, React or NodeJS below. For full documentaion here.

Basic Browser Usage

The module is intended to be browser framework agnostic although we ship a React Hook for React users (see below).

For all users, in a file at the root of the source of your project, first instantiate and export the ReapitConnectBrowserSession class.

The constructor accepts 4 parameters, of which two are optional, see comments below:

`ts
import { ReapitConnectBrowserSession } from '@reapit/connect-session'

// You should instantiate the class once only as a singleton as the module manages it's own state
export const reapitConnectBrowserSession = new ReapitConnectBrowserSession({
// The client id of your application, obtained from Reapit Developer Portal
connectClientId: 'SOME_CLIENT_ID',
// The url to the Reapit Connect instance.
connectOAuthUrl: 'https://connect.reapit.cloud',
// The relative path you want to re-direct in your application after a successful login. You will have supplied this when you registered your app.
// Defaults to '' or the root of your project if not supplied
connectLoginRedirectPath: '/some-redirect-path',
// The relative path you want to re-direct in your application after a successful logout. You will have supplied this when you registered your app.
// Defaults to '/login' if not supplied
connectLogoutRedirectPath: '/some-login-path',
// Optional in ms - default is 3hrs(10800000 ms) - after this time if your application is idle, the app will log you out and require a fresh login
connectApplicationTimeoutMs: 10800000,
// Optional in seconds - default is 300 seconds (5 minutes) - allows for clock skew when verifying tokens where the server and client clocks are not exactly in sync - this is occassionaly an issue with older Windows machines especially
connectClockSkewAllowance: 300,
// Proof Key for Code Exchange=
// By default PKCE is enabled. To disable PKCE, use usePKCE variable on ReapitConnectBrowserSession and set it to false.
usePKCE: true,
})
`

The instantiated class can then be used in your code. It exports the following methods:

`ts

import { reapitConnectBrowserSession } from './path-to-your-module'

// The definition of the reapitConnectBrowserSession
interface ReapitConnectSession {
// The accessToken is the Bearer <> you need to authenticate against the platform API.
accessToken: string
// Refresh token is provided as a convenience - in practice the module handle's refreshing and caching of your session out the box
refreshToken: string
// Id token is provided as a convenience - the parsed output is below in the loginIdentity object below
idToken: string
// The identity token has been verified as valid before decoding so that you can trust it's claims
loginIdentity: {
email: string
name: string
developerId: string | null
clientId: string | null
adminId: string | null
userCode: string | null
groups: string[]
orgName: string | null
orgId: string | null
offGroupIds: string | null
offGrouping: boolean
offGroupName: string | null
officeId: string | null
}
}

// Returns a promise containing your reapitSession object as per the interface above
reapitConnectBrowserSession.connectSession().then((reapitSession: ReapitConnectSession) => reapitSession)

// Handles redirect to authorization endpoint - in most cases, I don't need to call in my app as handled by the module
// but made public in case I want to override the redirect URI I specified in the constructor
reapitConnectBrowserSession.connectAuthorizeRedirect(redirectUri: string)

// Handles redirect to logout - defaults to constructor login uri but I can override if I like.
reapitConnectBrowserSession.connectLogoutRedirect(redirectUri: string)

// Handles redirect to login - defaults to constructor redirect uri but I can override if I like.
reapitConnectBrowserSession.connectLoginRedirect(redirectUri: string)

// String representation of the original path and query (eg '/some-path?someQuery=true'), of the page I was on before I
// started the OAuth flow. We cache this in the state object before redirecting to the authorize endpoint as a convenience
// so that I can preserve the state of my app on page refresh. Defaults to null if no state param exists in my current URI.
// You may not find this behavior desireable so the module does not perform the redirect by default, however if you do
// you will need to use this value in your code appropriate to your front end stack eg using a redirect component in React Router
reapitConnectBrowserSession.connectInternalRedirect

// A convenience getter to check if my app has been loaded inside RPS / Desktop / Agency Cloud
reapitConnectBrowserSession.connectIsDesktop

// A convenience getter to check if my app has a valid session
reapitConnectBrowserSession.connectHasSession

`

React Usage

In addition to the basic browser API, we export a React Hook to use in your React Components.

To leverage the Hook, first instantiate the class as per above. Then, around the Routes you wish to protect with Reapit Connect authentication, simply return when the session is not present as below:

`ts
// import the instantiated class, the hook and the provider
import { useReapitConnect } from '@reapit/connect-session'
import { reapitConnectBrowserSession } from './connect-session'

export const PrivateRouteWrapper: React.FC = ({ children }) => {
// Call the hook to retun a session object
const { connectSession } = useReapitConnect(reapitConnectBrowserSession)

// The session object implements the same interface as the browser class with the exception that the connectSession promise is handled wrapped in a useEffect hook and so is just an objecy or null. Here I return null from the component while I am fetching a session
if (!connectSession) {
return null
}

// I now have a session I can render my App
return (