BCGov CSS SSO API Integration

TL/DR

1. Install package by following the steps at Installing the Package.
2. Set up the package by following the steps at Basic Setup Guide.
3. Use with @bcgov/citz-imb-kc-express or standalone.
4. Allows easy use of the BCGov Keycloak CSS SSO API in a nodejs application.

What is this package for? - Checkout General Information

---

Table of Contents

• General Information
• Installing the Package - Start Here!
• Basic Setup Guide - Setting up after installing.
• Environment Variables - Required variables for initialization.
• Module Exports - Functions available from the module.
• TypeScript Types - Available TypeScript types.
• Applications using this Solution - See an example of how to use.

General Information

• For running on a NodeJS:20 API.
• For Keycloak Gold Standard.
• Works with Vanilla JavaScript or Typescript 5.
• Use with @bcgov/citz-imb-kc-express or standalone.
• Allows for easy use of BCGov Keycloak CSS SSO API in a nodejs application.

Use this package to:

• Check, add, or remove roles from a Keycloak user in your Keycloak Integration.
• Add, update, read, or remove roles from your Keycloak Integration.
• Get a list of users in your Keycloak Integration based on a query.

---

Installing the Package

1. Add the following line to your package.json:

{
  "dependencies": {
    "@bcgov/citz-imb-kc-css-api": "https://github.com/bcgov/citz-imb-kc-css-api/releases/download/v<VERSION>/bcgov-citz-imb-kc-css-api-<VERSION>.tgz",
    // The rest of your dependencies...
  },
}

2. Replace <VERSION> with the version you wish to use. Reference releases for version numbers.

3. Run npm install to add the package.

Return to Top

Basic Setup Guide

1. Add the required environment variables from the Environment Variables section below.

2. Start using the functions provided in Module Exports.

Example use:

import { getRole, getRoleComposites } from "@bcgov/citz-imb-kc-css-api";

/**
 * @returns {object} - Below properties.
 * @property {string} name - the name of the role (ex: "Admin").
 * @property {boolean} composite - if the role is composite (containing 'child' roles).
 */
const { composite } = await getRole('Admin');

if (composite) {
  /**
   * @returns {object} - Below properties.
   * @property {object[]} data - Array of role composites.
   * @property {string} data[i].name - the name of the composite role (ex: "view-reports").
   * @property {boolean} data[i].composite - if the role is composite (containing 'child' roles).
   */
  const { data } = await getRoleComposites('Admin');
  data.forEach(({ name }) => console.log('Admin role holds composite: ', name));
}

Note

Role composites are set within the CSS SSO Dashboard.
Go to 'My Projects' > 'Integrations' > Select an Integration > 'Integration Details' > 'Role Management' > Select a Role > 'Composite Roles'.

Return to Top

Environment Variables

# Ensure the following environment variables are defined on the container.

CSS_API_CLIENT_ID= # Keycloak CSS API Service Account client_id
CSS_API_CLIENT_SECRET= # Keycloak CSS API Service Account client_secret

SSO_INTEGRATION_ID= # Keycloak integration id (dont include leading zeros)
SSO_ENVIRONMENT= # 'dev', 'test' or 'prod'. Default is 'dev'.

DEBUG= # (optional) Set to 'true' to get useful debug statements in api console.
CSS_API_URL= # (optional) CSS API url, see default value below.
# https://api.loginproxy.gov.bc.ca/api/v1

Return to Top

Module Exports

These are the functions and types exported by the @bcgov/citz-imb-kc-css-api module.

import {
  getIntegration, // Get integration details.
  getRoles, // Get all roles from integration.
  createRole, // Create a new role.
  getRole, // Get role details.
  updateRole, // Update a role name.
  deleteRole, // Remove a role.
  getRoleComposites, // Get a role's composites.
  addRoleComposite, // Add a composite to a role.
  getRoleComposite, // Get a composite role from a role.
  deleteRoleComposite, // Remove a composite role from a role.
  getUserRoles, // Get roles associated with a user.
  assignUserRoles, // Assign roles to a user.
  getUsersWithRole, // Get users associated with a role.
  unassignUserRole, // Unassign a role from a user.
  getIDIRUsers, // Get list of IDIR users by query.
  getAzureIDIRUsers, // Get list of Azure IDIR users by query.
  getGitHubBCGovUsers, // Get list of GitHub BCGov users by query.
  getGitHubPublicUsers, // Get list of GitHub Public users by query.
  getBasicBCeIDUser, // Get Basic BCeID user by guid.
  getBusinessBCeIDUser, // Get Business BCeID user by guid.
  getBothBCeIDUser, // Get Basic or Business BCeID user by guid.
} from '@bcgov/citz-imb-kc-css-api';

Return to Top

TypeScript Types

These are the TypeScript types of the @bcgov/citz-imb-kc-css-api module.

// Integration
const getIntegration: () => Promise<any>;

// Roles
const getRoles: () => Promise<any>;
const createRole: (roleName: string) => Promise<any>;
const getRole: (roleName: string) => Promise<any>;
const updateRole: (roleName: string, newRoleName: string) => Promise<any>;
const deleteRole: (roleName: string) => Promise<any>;
const getRoleComposites: (roleName: string) => Promise<any>;
const addRoleComposite: (roleName: string, newCompositeRole: string) => Promise<any>;
const getRoleComposite: (roleName: string, compositeRoleName: string) => Promise<any>;
const deleteRoleComposite: (roleName: string, compositeRoleName: string) => Promise<any>;

// Role-Mapping
// username: <guid>@<identity_provider> 
// Example : jj4vrfekurtzc2931k8mroqx3fgibrr3@idir
const getUserRoles: (username: string) => Promise<any>;
const assignUserRoles: (username: string, roleNames: string[]) => Promise<any>;
const getUsersWithRole: (roleName: string, page?: number, count?: number) => Promise<any>;
const unassignUserRole: (username: string, roleName: string) => Promise<any>;

// Users
const getIDIRUsers: (query?: IDIRUserQuery) => Promise<any>;
const getAzureIDIRUsers: (query?: IDIRUserQuery) => Promise<any>;
const getGitHubBCGovUsers: (query?: GitHubUserQuery) => Promise<any>;
const getGitHubPublicUsers: (query?: GitHubUserQuery) => Promise<any>;
const getBasicBCeIDUser: (guid: string) => Promise<any>;
const getBusinessBCeIDUser: (guid: string) => Promise<any>;
const getBothBCeIDUser: (guid: string) => Promise<any>;

type RequestParams = {
  integrationEndpoint?: boolean; // Default: false
  environmentEndpoint?: boolean; // Default: true
  endpoint: string;
  method?: "GET" | "POST" | "PUT" | "DELETE"; // Default: GET
  body?: RequestBody;
};

type RequestRoleObject = {
  name: string;
};

type RequestBody = RequestRoleObject | RequestRoleObject[] | [];

type IDIRUserQuery = {
  firstName: string;
  lastName?: string;
  email?: string;
  guid?: string;
};

type GitHubUserQuery = {
  name?: string;
  login?: string; // Username
  email?: string;
  guid?: string;
};

Important

For expected response data, reference the following swagger docs: BCGov Keycloak CSS SSO API Swagger

Return to Top

Applications using this Solution

The following applications are currently using this keycloak implementation solution:

PLAY - CITZ IMB Package Testing App

Return to Top