@bcgov-cas/sso-react v2.0.0

@bcgov-cas/sso-react

A node module to handle session expiry on the client-side. This package is intended (but not limited to) to be used in conjunction with @bcgov-cas/sso-express

Components

SessionRefresher

A react effect that automatically executes a callback when certain events are fired. Includes throttling logic to avoid excessive callback invocations.

throttledTime and refreshEvents parameters are optional, and use a default value if not provided.

• Properties:

• Example: Refresh session on keydown, at most once every 10 minutes

function App() {
  const myCallback = async () => {
    await fetch("/refresh-session");
  };

  React.useEffect(
    throttleEventsEffect(myCallback, 10 * 60 * 1000, ["keydown"]),
    []
  );

  return (
    <div>
      <p>... My page content ...</p>
    </div>
  );
}

SessionTimeoutHandler

A react component that displays a session expiry modal before the session expires, and automatically re-syncs with the server when needed.

This component should only be rendered if the user is currently logged in, otherwise the modal will be displayed immediately

• Properties:

• Props object passed to the override dialog box (see LogoutWarningModal for more details). The remainingSeconds property will be updated every second.

interface WarningModalProps {
  inactivityDelaySeconds: number;
  expiresOn: number;
  onExtendSession: () => void;
  logoutPath: string;
  remainingSeconds: number;
}

LogoutWarningModal

A session expired warning modal that displays a countdown until the session expires. Rendering can be overridden by setting the renderModal property.

The renderModal function will be passed the following props - from the LogoutWarningModal component itself.:

Example

A example of usage, using a NextJS router to redirect the user to the login page when the session has expired, and a session refresher to refresh the session when the user interacts with the page.

import { useRouter } from "next/router";
import { SessionTimeoutHandler, throttleEventsEffect } from "@bcgov/sso-react";

function App() {
  const router = useRouter();

  return (
    <div>
      <SessionTimeoutHandler
        modalDisplaySecondsBeforeLogout={120}
        sessionRemainingTimePath="/session-idle-remaining-time"
        logoutPath="/logout"
        onSessionExpired={() => {
          router.push({
            pathname: "/login",
            sessionIdled: true,
          });
        }}
        resetOnChange={[router]}
        extendSessionOnEvents={{
          enabled: true,
          throttleTime: 60000,
          events: ["keydown", "scroll"],
        }}
      />
      <p>... My page content ...</p>
    </div>
  );
}

Additional Examples (doesn't require React)

To integrate with the @bcgov-cas/sso-express package, the following implementations of login, logout and register buttons can be used:

• Login (assuming the default '/login' endpoint is used):

<form action="/login" method="post">
  <button type="submit">Log in</button>
</form>

• Logout:

<form action="/logout" method="post">
  <button type="submit" className="btn btn-secondary">Logout</button>
</form>

• Register:

<a href="/register">Register</a>