medOS Auth (AAA)
Internal scope:
ever-api-aaa· Authentication, Authorization & Accounting for the whole platform.
The AAA service is the identity and access-control authority for medOS. It owns user accounts, role/role-group/permission definitions, JWT issuance and refresh, page- and menu-level access control, third-party (OAuth / SMART-on-FHIR) app access, and an audit trail of authentication activity. It also hosts the optional biometric attestation endpoints (face and voice) used for staff login and clinician order sign-off. Every other microservice trusts the JWTs this service mints.
Responsibilities
- Authentication — login, logout, token refresh, and JWT issuance/verification.
- Authorization (RBAC) — users, roles, role-groups, permissions, and action-level ACLs resolved into the claims carried by each JWT.
- Surface access control — page-, menu-, and medical-record-menu access tied to roles, plus e-form category and department scoping.
- Third-party access — OAuth / SMART-on-FHIR app registration and scoped tokens for external app launches.
- Accounting / audit — append-only audit logging and status-trail history of auth-relevant events.
- Biometric attestation (optional) — face login and voice verification, each behind its own feature flag and subscription entitlement.
Major modules
| Module | Purpose |
|---|---|
auth | Core authentication — login, logout, refresh, JWT verify, biometric endpoints |
user / hcisUser | User account management (two model generations) |
role / hcisRole | Role definitions |
roleGroup / hcisRoleGroup | Role grouping for hierarchical RBAC |
userRole | User-to-role assignment |
hcisPermission | Permission catalog |
action / actionPermission | Actions and action-level ACLs |
hcisPage / menu / menuPermission | Page and navigation-menu access control |
menuMedicalRecord / roleMenuMedicalRecord | Medical-record menu scoping per role |
eformCategoryPermission / eformDepartment | E-form category and department access |
accessThirdParty / accessThirdPartyToken | OAuth / SMART-on-FHIR app registration and tokens |
accessToken / refreshToken | Token issuance and refresh records |
apiKeyConsole | API-key management console |
userDepartment / userJobWork | Staff department and job-assignment mapping |
auditLog / statusTrailHistory | Auth audit trail and status history |
bulkOps | Bulk user/role administration |
_sequence / _setting | Internal sequence and settings helpers |
Token & sign-in flow
Client ── POST /v2/aaa/auth/login ──▶ Auth (AAA)
│ verify credentials
│ resolve roles → permissions
▼
issue JWT (+ refresh)
│
◀──────── access + refresh ──────┘
Subsequent calls:
Client ── Bearer JWT ──▶ Gateway ──▶ any microservice (claims trusted)
Client ── POST /v2/aaa/auth/refresh ──▶ Auth (AAA) ──▶ new access token
Biometric attestation (optional)
Two opt-in modalities live on the auth module. Both ship off by default and
require an explicit feature flag plus a subscription entitlement; an
unentitled request returns a FEATURE_NOT_ENTITLED error.
- Face — challenge / sign-in / enroll endpoints. A single-use liveness challenge precedes a face login that verifies a posted face embedding; enrollment is part of the user-management add-user wizard.
- Voice — challenge / verify / enroll endpoints. Voice verification is used for clinician attestation on AI-assisted order sign-off (it files an attestation on the order, it is not a session login).
See Feature entitlement for how the subscription tier gates these capabilities.
Config flags
| Flag | Effect |
|---|---|
FACE_LOGIN_ENABLED | Enables the face challenge / sign-in / enroll endpoints |
VOICE_LOGIN_ENABLED | Enables the voice challenge / verify / enroll endpoints |
SUBSCRIPTION_TIER | Resolves whether biometric features are entitled for the tenant |
Related catalog items
ST-1…ST-8— User Account, Access Control, Audit, OAuth / Third-Party AccessSEC-7— Biometric attestation (face / voice)SEC-8— SMART-on-FHIR scope guardCP-1,CP-2— User & Role Management