Authorization Service

Authorization / access-control management service for the Equinox platform. It manages IAM-style Policies, Roles (role-to-policy mappings), and exposes a per-service Privilege Catalog. It also provides a service-to-service “policy action” endpoint that resolves a business’s roles and their allow-effect policies for downstream authentication flows (SAML / OIDC / Cognito).

Overview

The Auth Service is the authoring and storage system for authorization data on the Equinox platform. It does not itself decide whether a specific request from an end-user is allowed (that evaluation happens in the JWT-auth layer / consuming services). Instead, it lets administrators define what the rules are:

  • Policies — AWS IAM-style documents made of statements, each with an Effect (Allow/Deny), a list of colon-separated Actions (e.g. user:create, pim:viewProducts), a Resource, and optional AWS IAM-style Condition blocks (108 supported operators). Policies are scoped to a businessId.
  • Roles — named bundles that reference a set of Policy _ids (collection policyRoleMapping). Also scoped to a businessId.
  • Service Privilege Catalog — read-only master-seed data listing, per platform service, which privilege strings exist (grouped into view / create / update / delete). Backed by collection masterseeddata.
  • Policy Action resolution — a service-to-service read endpoint that, given a businessId (and optionally specific roleIds), returns a { roleName: [policies] } map of allow-effect policies. Used by the SSO Service and the User Service to build a caller’s effective permissions during login.

Every write/read endpoint is guarded by a JWT bearer token and a specific privilege string, and the caller must additionally be flagged isAdmin on the decoded token.

Business Value

Capability Business outcome
Centralised policy authoring (IAM-style) One consistent permission model shared across all platform services instead of ad-hoc per-service rules
Role → policy bundling Admins grant coarse-grained roles; fine-grained policies are reused and maintained in one place
Per-business (multi-tenant) scoping Every policy and role is isolated by businessId, so tenants cannot see or collide with each other’s rules
Conditional access (AWS IAM Conditions) Context-aware permissions (role, department, dates, counts, etc.) without code changes
Policy Action API Downstream auth (SSO/OIDC/Cognito) can resolve a user’s effective allow-policies in a single call
Service Privilege Catalog A discoverable master list of valid privilege strings per service, powering admin UIs
Soft-delete of policies Policies are marked DELETED (not physically removed) preserving audit/history and preventing dangling references

Who Uses It

Persona How they interact
Platform / tenant administrator Creates, updates, lists and deletes Policies and Roles via the REST API (typically through an admin console)
Admin console / front-end Calls the Policy, Role and Service-Privileges endpoints; consumes the Service Privilege Catalog to render permission pickers
SSO Service Calls GET /v1/policies/action to resolve roles + allow-policies during login
User Service Consumes the Policy Action endpoint to assemble a user’s effective privileges
Other platform services Rely on privilege strings authored here; may read the Service Privilege Catalog
Extension developers (Optional) provide a policyValidator plugin or lifecycle handlers to inject custom validation — see Extensions & Plugins for wiring caveats

Related Resources

  • Swagger UI: {baseURL}{appPrefix}/documentation
  • Error code reference: see Error Codes section
  • Localized error messages: available in English, French, and Arabic

Core Features

# Feature / Domain Description Collection
1 Policy management CRUD for IAM-style policies (create, list/search/paginate, partial update, soft-delete) scoped by businessId policy
2 Policy conditions Full AWS IAM condition support: 108 operators (String/Numeric/Date/Bool/Binary/Null + ForAnyValue/ForAllValues/IfExists qualifiers) policy
3 Role management CRUD for roles that bundle policy _ids; validates that referenced policies exist and are ACTIVE policyRoleMapping
4 Policy Action resolution Service-to-service read: resolve { roleName: [allow-policies] } for a business, optionally filtered by roleIds policyRoleMapping + policy
5 Service Privilege Catalog Read-only listing of per-service privilege definitions from master seed data masterseeddata
6 JWT authentication + privilege authorization Bearer-token auth via shared plugin; each route requires a named privilege and isAdmin n/a
7 Internationalized errors Error messages localized in English, French, and Arabic; error code returned in body and Error-Code header n/a
8 Extension points Pluggable policyValidator and pre/post lifecycle handlers via the shared plugin registry (see wiring caveats) n/a
9 In-memory mode AUTH_USE_INMEMORY=true swaps MongoDB for an in-memory adapter for local dev/tests n/a

Revision History
2026-08-05 | AN – Page created and uploaded the contents