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 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:
import { ReapitConnectBrowserSession } from '@reapit/connect-session'
export const reapitConnectBrowserSession = new ReapitConnectBrowserSession({
connectClientId: 'SOME_CLIENT_ID',
connectOAuthUrl: 'https://connect.reapit.cloud',
connectUserPoolId: 'SOME_USER_POOL_ID',
connectLoginRedirectPath: '/some-redirect-path',
connectLogoutRedirectPath: '/some-login-path',
})
The instantiated class can then be used in your code. It exports the following methods:
import { reapitConnectBrowserSession } from './path-to-your-module'
interface ReapitConnectSession {
accessToken: string
refreshToken: string
idToken: string
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
}
}
reapitConnectBrowserSession.connectSession().then((reapitSession: ReapitConnectSession) => reapitSession)
reapitConnectBrowserSession.connectAuthorizeRedirect(redirectUri: string)
reapitConnectBrowserSession.connectLogoutRedirect(redirectUri: string)
reapitConnectBrowserSession.connectLoginRedirect(redirectUri: string)
reapitConnectBrowserSession.connectInternalRedirect
reapitConnectBrowserSession.connectIsDesktop
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:
import { useReapitConnect } from '@reapit/connect-session'
import { reapitConnectBrowserSession } from './connect-session'
export const PrivateRouteWrapper: React.FC = ({ children }) => {
const { connectSession } = useReapitConnect(reapitConnectBrowserSession)
if (!connectSession) {
return null
}
return (
<AppNavContainer>
<Menu />
</AppNavContainer>
)
}
Then in my React child components, I have access to the session values and methods eg:
import { useReapitConnect } from '@reapit/connect-session'
import { reapitConnectBrowserSession } from './connect-session'
export const SomeComponent: React.FC = () => {
const { connectSession, connectLogoutRedirect } = useReapitConnect(reapitConnectBrowserSession)
const handleLogout = () => connectLogoutRedirect('/custom-login-path')
return (
<CustomFetchComponent connectSession={connectSession}>
<Button onClick={handleLogout}>I am a logout button!</Button>
</CustomFetchComponent>
)
}
PKCE
Proof Key for Code Exchange
By default PKCE is enabled. To disable PKCE, use usePKCE
variable on ReapitConnectBrowserSession
and set it to false.
import { ReapitConnectBrowserSession } from '@reapit/connect-session'
export const reapitConnectBrowserSession = new ReapitConnectBrowserSession({
...
usePKCE: false,
})
Sign In With Reapit Button
Perhaps the simplest way to authenticate on the client side is to embed the "Sign In With Reapit Button" on your page. This is a single script served from our CDN, you instantiate with a target div, your client credentials as per the browser API and pass in a callback to receive your session object. As per the NPM module, all caching, redirection and refreshing is taken care of by the package. When you have a session, the button will change function to be a logout which will clear your cache and end your session in Reapit Connect.
The below example shows how to embed on any static or dynamic page with a single script. In the connectHasSessionCallback function we fetch a list of appointments from the Platform API to demonstrate the full flow.
<div id="reapit-connect-component"></div>
<script src="https://web-components.prod.paas.reapit.cloud/reapit-connect-component.js"></script>
<script>
const connectHasSessionCallback = (reapitConnectBrowserSession) => {
reapitConnectBrowserSession.connectSession().then(session => {
console.log('Session is', session)
fetch('https://platform.reapit.cloud/appointments', {
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${session.accessToken}`,
'api-version': '2020-01-31'
}
})
.then(res => res.json())
.then(appointments => console.log('Appointmemts are', appointments))
})
}
ReapitConnectComponent && new ReapitConnectComponent({
connectClientId: '<<clientId here>>>',
connectUserPoolId: '<<user pool id here>>>',
connectOAuthUrl: 'https://connect.reapit.cloud',
connectLoginRedirectPath: '',
connectLogoutRedirectPath: '/login',
connectContainerId: '#reapit-connect-component',
connectHasSessionCallback
})
</script>
Node Usage
This has moved to @reapit/connect-session-server