To use COMS in OIDC or FULL authentication mode (see a description of the different Authentication Modes) and make use of features such as user-specific object permissions, connect COMS and your Line of Business (client) application to the same SSO realm.

For this guide we will set up:

• An instance of COMS API running in OIDC auth mode
• Our Vue Scaffold node application which represents a Line of Buisness app that is calling the COMS api.

We can generate SSO Clients using the Pathfinder's self-serve Common Hosted Sign-On App.

• Go to Pathfinder's Common Hosted Sign-On App and following 'Request Integration' steps.

• Download your 'Installation JSON' which contains the values you can put into your COMS environment variables (for example: in your parameters you pass to the COMS docker image at run time or in your <COMS>/app/config/local.json if you are testing this locally)

Installation JSON:

{
  "confidential-port": 0,
  "auth-server-url": "https://dev.oidc.gov.bc.ca/auth",
  "realm": "onestopauth-both",
  "ssl-required": "external",
  "resource": "coms-1234",
  "credentials": {
    "secret": "*****"
  }
}

• Pass the SSO client details to your instance of COMS:

docker run -it --rm -p 3000:3000 \
-e KC_CLIENTID=<resource from JSON> \
-e KC_CLIENTSECRET=<credentials.secret from JSON> \
-e KC_REALM=<realm from JSON> \
-e KC_SERVERURL=<auth-server-url from JSON> \
-e KC_ENABLED=true \                                # required
-e DB_ENABLED=true \                                # required
...                                                 # Database credentials
...                                                 # Object Storage credentials
docker.io/bcgovimages/common-object-management-service:<tag>

For help running COMS see our Application README

we tested this using one of our Vue Scaffold node application, using two SSO clients in the shared realm. one for the frontend (public) and one for the backend (confidential).

Note: the LoB and COMS need to share the same realm so that the JWT is valid for both the LoB app and the COMS api, and a claim in the JWT (for example the sub key) can be used as a verified identifier of the logged in user in both applications. When creating a client using the SSO app, you can choose to have your client in one of 4 different realms (depending if you want IDIR, BCeID basic/Business or both and Auzer).

You can put the generated SSO client details into environment variables for your LoB app, for example via the vue-scaffold/app/config/local.json file:

{
  "frontend": {
    "apiPath": "api/v1",
    "basePath" : "/app",
    "keycloak": {
      "realm": "onestopauth-both",
      "clientId": "coms-showcase-frontend-localhost-91011",
      "serverUrl": "https://dev.oidc.gov.bc.ca/auth"
    }
  },
  "server": {
    "apiPath": "/api/v1",
    "basePath" : "/app",
    "bodyLimit": "30mb",
    "keycloak": {
      "clientId": "coms-showcase-5678",
      "realm": "onestopauth-both",
      "serverUrl": "https://dev.oidc.gov.bc.ca/auth",
      "clientSecret": "REDACTED"
    },
    "logLevel": "http",
    ...

For more instructions on how to configure your app to use the SSO realm see: Pathfinder's Developers Guide and BC Gov's Keycloak Example apps.

A note about the Vue-Scaffold keycloak adapter: For the Vue-Scaffold application, we had to modify the way we load keycloak by addng additonal options from the main.js file:

function loadKeycloak(config) {
  Vue.use(VueKeycloakJs, {
    init: { onLoad: 'check-sso', flow: 'standard', pkceMethod: 'S256'},
    config: { ..

Verify that our Line of Business app is able to call the COMS api and that JWT's can be shared by SSO clients in the same sso realm.

1. start the LoB app and log in through the browser via SSO

2. Copy JWT that was returned from Keycloak (from browser network dev inspector)

3. Use this JWT in an Auth header (type Bearer Token) of a POST /object/ request to the COMS api. This could be done using Postman or in a component built into the Vue-Scaffold (see our COMS Showcase app for an example). The response from request should be 201, attached files uploaded to S3

4. COMS database created a record in the user table (by parsing the JWT)