Skip to content

IDCS Browser Login

Folder: idcs_browser_login/

A zero-dependency, framework-agnostic Node.js package implementing the IDCS OAuth2 Authorization Code flow for a browser-facing UI: server-side session, HttpOnly cookie, and the access token never reaching the browser. Built to be imported as a local file: dependency by a recipe's Express gateway rather than re-derived — four recipes (ebs_invoice_reconciliation_ui, um_reviewer_ui, clinician_copilot_ui, finance_allocation_consolidation_ui) each independently implemented this flow before it was consolidated here.

Browser → GET /login → IDCS Authorization Code flow → GET /callback
                                                            │
                                          exchange code for tokens
                                                            │
                                          fetchUserGroups() via
                                          /admin/v1/Me (urn:opc:idm:__myscopes__)
                                                            │
                                          server-side session + HttpOnly cookie
                                                            ▼
                                          Browser never sees the access token

The group-claims gotcha this package exists to fix

This platform's IDCS tenant does not embed a groups claim in the access token for custom OAuth clients, and the OIDC userinfo endpoint doesn't carry one either — confirmed empirically across all four recipes above before this package existed. Any code that reads claims.groups off a decoded token to gate a feature finds it silently empty and locks every user out. fetchUserGroups() works around this with a self-service SCIM lookup (/admin/v1/Me?attributes=groups), authorized by the urn:opc:idm:__myscopes__ scope requested alongside the normal openid profile scopes.

Key files:

  • src/oauth.js — Authorization Code flow: redirect to IDCS, exchange code for tokens
  • src/groups.js — fetchUserGroups(), the /admin/v1/Me self-service SCIM lookup
  • src/session.js — server-side session store + HttpOnly cookie issuance
  • src/ociTokenExchange.js — optional downstream OCI token exchange for a signed session
  • examples/minimal_express_app.js — the wiring template every consuming recipe copies
npm install file:../../../inception_core/accelerators/patterns_solution/idcs_browser_login

const { registerAuthRoutes, requireSession } = require("inception-idcs-browser-login");

registerAuthRoutes(app, { /* IDCS client config */ });
app.use("/api", requireSession, apiProxyRouter);

When to use: Any recipe with a browser-facing UI that needs real IDCS SSO login — write only the recipe-specific group-name → role mapping; import this package for the OAuth2 flow, session handling, and group resolution rather than re-deriving them. See inception-recipe-builder's SKILL.md step 6 for the exact wiring instructions given to a new recipe build.