@bcgov-cas/sso-express v3.2.0

sso-express

A node module exposing a developer-friendly sso/keycloak middleware for express servers

Prerequisites

• express and openid-client peer dependencies (see package.json for supported versions)
• The express-session middleware must be added to the stack before this middleware, as it assumes that req.session exists

Usage

This package exposes an express middleware

:warning: When using the exposed middleware, any request to the express server - including to static endpoints - will extend the session.

Exposed endpoints

The package configures a middleware with the following configurable endpoints:

Example usage

const ssoUtils = require("@bcgov-cas/sso-express").default;

const ssoMiddleware = await ssoUtils({
  applicationDomain: ".gov.bc.ca",
  getLandingRoute: (req) => {
    // Depending on your sso configuration
    return getLanding(req.claims);
  },
  getRedirectUri: (defaultRedirectUri, req) => {
    // can be used to add additional query params to the default redirect uri:
    const redirectUri = new URL(defaultRedirectUri);
    redirectUri.searchParams.set("redirect", "/some/path");
    return redirectUri;
  },
  bypassAuthentication: {
    login: process.env.BYPASS_AUTH_ON_LOCAL,
    sessionIdleRemainingTime: process.env.BYPASS_AUTH_ON_LOCAL,
  },
  oidcConfig: {
    oidcIssuer: `https://oidc.gov.bc.ca/auth/realm/myrealm`,
    clientId: "myappresource",
    clientSecret: "verysecuresecret", // optional
    baseUrl: "http://localhost:3000",
  },
  authorizationUrlParams: { kc_idp_hint: "idir" },
});

server.use(ssoMiddleware);

Authentication data

This middleware adds the following authentication data to the express request (req):

• The OpenId TokenSet (see the openid-client documentation) is available at req.session.tokenSet
• The OpenId claims are available at req.claims

Configuration

The constructor expects a single configuration object, with required and optional keys

Required configuration

Only the OpenId configuration key oidcConfig is mandatory

Example:

const configOptions = {
  oidcConfig: {
    oidcIssuer: `https://oidc.gov.bc.ca/auth/realm/myrealm`,
    clientId: "myappresource",
    baseUrl: "http://localhost:3000",
  },
};

Optional configuration

In addition, all these configuration keys are accepted:

  routes: {
    login: '/login',
    logout: '/logout',
    sessionIdleRemainingTime: '/session-idle-remaining-time',
    authCallback: '/auth-callback'
  }