Authentication Service - Minos

The Authentication Service (auth-service) is a critical security component within the Dante GPU Rental Platform. It functions as the central authority for user identity management, handling user registration, secure credential verification, and the issuance and management of JSON Web Tokens (JWTs) for authorizing access to platform resources. Built with Python and the FastAPI framework, this service is designated as Production Ready.

Service Identifier: auth-service/

Primary Language: Python 3.10+ (utilizing FastAPI)

Database: PostgreSQL

Port: 8000 (as per platform service startup order)

I. Strategic Importance and Core Mandate

The auth-service plays a pivotal role in safeguarding the Dante GPU Rental Platform by:

• Centralizing User Identity: Managing all user accounts (GPU providers, renters/consumers, administrators) in a unified manner.

• Enforcing Secure Authentication: Implementing robust mechanisms for verifying user credentials.

• Facilitating Token-Based Authorization: Issuing JWTs that enable stateless authentication and authorization across the platform's microservices, primarily validated by the API Gateway.

• Managing Roles: Defining and assigning user roles, which form the basis for Role-Based Access Control (RBAC) throughout the platform.

II. Core Responsibilities and Functional Capabilities

The auth-service is engineered to deliver the following key functionalities:

A. User Account Management:

• Registration (POST /api/v1/auth/register): Enables new users to create accounts on the platform. This involves collecting necessary details (e.g., email, password) and securely storing them.

• Login (POST /api/v1/auth/login): Authenticates users by verifying their submitted credentials against the stored records. Upon successful authentication, it issues JWTs.

• Profile Storage: Maintains user profile information within its dedicated PostgreSQL database.

B. JWT-Based Authentication & Token Management:

• JWT Issuance: Generates JWTs (access tokens and potentially refresh tokens) upon successful user login. These tokens are essential for accessing protected API endpoints.

  • Access Tokens: Short-lived tokens carrying user identity and role information, used to authorize API requests.

  • Refresh Tokens (POST /api/v1/auth/refresh): If implemented, longer-lived tokens used to obtain new access tokens without requiring users to re-authenticate, enhancing user experience. The presence of a /refresh endpoint suggests this capability.

• Token Structure: JWTs issued by the service adhere to standard structure (header, payload, signature) and include:

  • Standard Claims: iss (issuer), sub (subject - user ID), aud (audience), exp (expiration time), iat (issued at).

  • Custom Claims: User roles (e.g., provider, renter, admin) for RBAC.

• Secure Token Generation: Utilizes strong secret keys (JWT_SECRET or SECRET_KEY from .env) for signing JWTs, ensuring their integrity. The python-jose library is employed for JWT operations.

C. Credential Security:

• Password Hashing: Uses the passlib library to securely hash user passwords with strong, salted hashing algorithms (e.g., bcrypt, Argon2) before storing them in the database. Plain-text passwords are never stored.

• Password Policies: Enforces strong password creation policies to enhance account security.

D. Role Management:

• Manages user roles, which are included in JWT claims. This allows other services, particularly the API Gateway, to implement fine-grained access control based on the user's role.

III. Technology Stack and Implementation Details

The auth-service leverages a modern Python-based technology stack:

• Python Version: 3.10+

• Web Framework: FastAPI for building high-performance, asynchronous APIs with automatic data validation and API documentation.

• Data Validation & Serialization: Pydantic for defining data models (schemas) and ensuring data integrity for API requests and responses.

• Database ORM: SQLAlchemy for interacting with the PostgreSQL database, providing an object-relational mapping layer.

• Database Migrations: Alembic for managing database schema changes and versioning.

• Password Hashing: passlib library.

• JWT Handling: python-jose library.

• Configuration: Relies on environment variables for crucial settings, managed via a .env file during development. Key variables include:

  • DATABASE_URL: Connection string for the PostgreSQL database (e.g., postgresql+psycopg2://user:password@localhost:5432/dante_auth).

  • SECRET_KEY (or JWT_SECRET): A long, random, and secure key used for signing JWTs and other cryptographic operations.

  • ALGORITHM: Specifies the JWT signing algorithm.

  • ACCESS_TOKEN_EXPIRE_MINUTES: Configures the validity duration for access tokens.

• Asynchronous Capabilities: FastAPI's async/await syntax is used for non-blocking I/O operations, improving service responsiveness.

IV. API Endpoints

The auth-service exposes its functionality through RESTful API endpoints, which are accessed via the API Gateway. The primary authentication-related endpoints as defined in the platform's API documentation are:

• POST /api/v1/auth/register:

  • Description: Registers a new user on the platform.

  • Request Body: User registration details (e.g., email, password).

  • Response: Success or error message.

• POST /api/v1/auth/login:

  • Description: Authenticates an existing user.

  • Request Body: User credentials (e.g., email, password).

  • Response: On success, returns JWTs (e.g., access_token, potentially refresh_token).

• POST /api/v1/auth/refresh:

  • Description: Refreshes an access token using a valid refresh token.

  • Request Body: Refresh token.

  • Response: On success, returns a new access_token.

V. Interactions with Other Platform Components

• API Gateway:

  • The API Gateway routes all authentication-related requests (e.g., /api/v1/auth/*) to the auth-service.

  • It relies on JWTs issued by the auth-service to authenticate and authorize subsequent requests made by users to other platform services.

• PostgreSQL Database:

  • Serves as the persistent datastore for all user accounts, securely hashed credentials, roles, and any other related authentication data.

• Clients (Users/Applications):

  • Clients interact with the auth-service indirectly through the API Gateway.

VI. Setup, Running, and Development

A. Environment Setup:

1. Virtual Environment: Create and activate a Python virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Linux/macOS
   # .\venv\Scripts\activate   # On Windows

2. Install Dependencies: Install required Python packages:

   pip install -r requirements.txt

3. Configuration: Create a .env file in the auth-service root directory or set environment variables directly. Refer to app/core/config.py (if such a file exists as per typical FastAPI structures) or the service-specific README for all required variables. Example .env content:

   DATABASE_URL=postgresql+psycopg2://dante:dante123@localhost:5432/dante
   SECRET_KEY=your_very_secure_and_random_jwt_secret_key
   ALGORITHM=HS256
   ACCESS_TOKEN_EXPIRE_MINUTES=30

   (Note: The DATABASE_URL in the example uses dante as the database name, consistent with the main README, while the service-specific snippet mentioned dante_auth. The main README's DATABASE_URL likely refers to a unified database for multiple services, or a default that services adapt.)

B. Database Setup:

1. Ensure a PostgreSQL server is running and accessible.

2. Create the database specified in the DATABASE_URL if it doesn't exist.

3. Apply database migrations:

   cd auth-service  # Navigate to the auth-service directory
   alembic upgrade head

C. Running the Service:

• Start the FastAPI development server using Uvicorn:

  uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

  The --reload flag enables auto-reloading during development. The service will typically be accessible on port 8000 as per the main platform README's service startup order.

D. API Documentation:

• Once the service is running, interactive API documentation (Swagger UI) is available at http://<host>:8000/docs.

• Alternative ReDoc documentation is available at http://<host>:8000/redoc.

E. Testing:

• Run tests for the auth-service (typically located within its directory):

  cd auth-service
  python -m pytest

VII. Security Considerations

• Strong SECRET_KEY / JWT_SECRET: This key is critical for the security of JWTs and must be kept confidential and sufficiently complex in production environments.

• Regular Dependency Updates: Keep Python packages, especially those related to security (FastAPI, Passlib, python-jose, SQLAlchemy), updated to patch vulnerabilities.

• HTTPS Enforcement: While SSL/TLS termination might be handled at the API Gateway or load balancer level, ensure internal communications are also secured where necessary.

• Input Validation: FastAPI and Pydantic provide robust input validation, which is crucial for preventing injection attacks and other exploits.

• Secure Database Access: Use strong, unique credentials for database access, and limit the privileges of the database user for the auth-service.

The auth-service is a vital component, ensuring that the Dante GPU Rental Platform operates securely by managing user identities and access control with robust, modern authentication practices. Its production-ready status indicates a mature and reliable implementation.