Technical Specification: auth_service¶
Overview¶
The auth_service is a foundational microservice within the Project AI-Leap ecosystem. It acts as the central and sole authority for user identity, authentication, and authorization. All other services rely on it to verify user sessions, check permissions for protected actions, and manage the core user data model. It is designed to be highly available, secure, and the ultimate source of truth for "who a user is" and "what they are allowed to do." This is in accordance with the decisions made in ADR-001, ADR-004, and ADR-005.
Core Responsibilities¶
- User Authentication & Session Management: Handles all user login/logout flows by integrating with the corporate Google IdP for Single Sign-On (SSO) and issues internal session tokens.
- Access Control Model Foundation: Implements and enforces the hybrid Role-Based (RBAC) and Group-Based (GBAC) access control model, calculating a user's effective permissions in real-time.
- User Self-Service Profile Management: Provides endpoints for users to manage their own basic contact information.
- Administrative User Management: Offers a complete suite of administrative functions for creating, viewing, searching, and modifying user accounts, including their status and group memberships.
- Authorization Enforcement: Exposes a high-performance endpoint for other services to check if a user possesses the required permission to perform an action.
- Security Audit Trail: Automatically logs all security-sensitive events (e.g., logins, user creations, permission changes) to an immutable audit trail.
Architecture & Technology Stack¶
Architectural Style¶
The auth_service is a self-contained, containerized microservice designed for independent deployment, scaling, and maintenance. It communicates with other services over the internal network using gRPC for high-performance, strongly-typed API calls.
Technology Stack¶
| Component | Technology | Purpose |
|---|---|---|
| Runtime Environment | Nest.js (TypeScript) | Provides a structured, scalable, and type-safe backend framework for the service's logic. |
| Primary Datastore | PostgreSQL | Stores all relational data, including users, groups, roles, and permissions, ensuring strong consistency. |
| Distributed Cache | Redis | Used for caching user sessions and pre-calculated permission sets to reduce database load and latency. |
| Message Broker | RabbitMQ | Used for asynchronously publishing security audit events to a dedicated logging service or data warehouse. |
| API Protocol | gRPC | Defines the contract for all synchronous, inter-service communication, ensuring high performance. |
Important
Configuration & Security
CRITICAL: All sensitive configuration data, including database connection strings, IdP client secrets, and internal API keys, MUST be managed via environment variables injected into the container at runtime. Secrets MUST NOT be hardcoded in the source code or committed to version control.
Documentation Navigator¶
This section serves as a central index to all detailed business and technical documentation related to the auth_service.
Implemented Business Features¶
The following table lists all the business features implemented by this service. The BRD (Business Requirements Document) provides the detailed "what" and "why" for each feature.
| Feature ID | Feature Name | Link to BRD |
|---|---|---|
| 01 | User Authentication & Session Management | BRD, Use Case |
| 03 | User Self-Service Profile | BRD, Use Case |
| 04 | Access Control Model Foundation | BRD, Use Case |
| 05 | Admin: User Listing & Search | BRD, Use Case |
| 06 | Admin: User Creation | BRD, Use Case |
| 07 | Admin: User Editing & Status Management | BRD, Use Case |
| 08 | Admin: Effective Permissions View | BRD, Use Case |
| 09 | Unauthorized Access Handling | BRD, Use Case |
| 10 | Security Audit Trail | BRD, Use Case |
Detailed Technical Specifications¶
- Database Schema: View Schema
The complete PostgreSQL schema, including all tables, columns, constraints, and relationships. - gRPC API Contract: View Contract
The formal Protobuf 3 contract for all services, RPCs, and messages exposed by this service.