Auth Service Documentation

This document details the Authorization Service, a microservice in the space trader elite-style backend. Its purpose is to handle user authentication, including registration, login, and the management of JWT and refresh tokens.

1. Data Models

The Auth Service relies on two primary data models to manage user data and sessions.

1.1. User Model

Represents a user account in the system.

User.cs
namespace AuthService.Models
{
    public class User
    {
        public int Id { get; set; }
        public string Username { get; set; } = default!;
        public string PasswordHash { get; set; } = default!;
        public string Role { get; set; } = "User";
        public ICollection RefreshTokens { get; set; } = new List();
    }
}

Fields:

Id: A unique identifier for the user.
Username: The user's unique username.
PasswordHash: The securely hashed password using BCrypt.
Role: The user's role, with a default value of "User".
RefreshTokens: A collection of associated refresh tokens.

1.2. RefreshToken Model

Used to generate new JWTs without requiring the user to re-enter their credentials.

RefreshToken.cs
namespace AuthService.Models
{
    public class RefreshToken
    {
        public int Id { get; set; }
        public string Token { get; set; } = default!;
        public DateTime ExpiresAt { get; set; }
        public int UserId { get; set; }
        public User User { get; set; } = default!;
    }
}

Fields:

Id: Unique identifier for the refresh token.
Token: The unique refresh token string.
ExpiresAt: The expiration date and time of the token.
UserId: The foreign key to the associated user.
User: The navigation property to the user object.

2. API Endpoints

All endpoints are defined within the AuthController and are prefixed with /api/Auth.

2.1. Register User

POST /api/Auth/register

Registers a new user with a username, password, and role.

Request Body (JSON)

{
  "username": "newuser",
  "password": "securepassword123",
  "role": "User"
}

Responses

200 OK: { "Message": "User registered successfully" }
400 Bad Request: { "Message": "Username already taken" } if the username is not unique.

2.2. Login User

POST /api/Auth/login

Authenticates a user and issues a new JWT and a refresh token.

Request Body (JSON)

{
  "username": "existinguser",
  "password": "securepassword123"
}

Responses

200 OK: A JSON object containing the JWT and refresh token.
401 Unauthorized: { "Message": "Invalid credentials" } if the username or password is incorrect.

2.3. Delete User

POST /api/Auth/delete

Deletes a user account and all associated refresh tokens.

Request Body (JSON)

{
  "username": "userToDelete"
}

Responses

200 OK: { "Message": "User deleted successfully" }.

2.4. Refresh Token

POST /api/Auth/refresh

Exchanges an old, unexpired refresh token for a new JWT and a new refresh token.

Request Body (JSON)

{
  "refreshToken": "old_refresh_token_string"
}

Responses

200 OK: A JSON object containing the new JWT and new refresh token.
401 Unauthorized: { "Message": "Invalid or expired refresh token" }.

3. Business Logic

The core logic of the service is managed by the AuthServiceLogic class.

Password Hashing: Passwords are hashed using the BCrypt.Net-Next library before being stored.
JWT Generation: A new JWT is created upon successful login, containing claims for the user's ID, username, and role. The token is signed with a symmetric key from the configuration file and has a 15-minute expiration time.
Refresh Token Management: A new refresh token is generated for each login and refresh request. These tokens are stored in the database and are valid for 7 days. When a refresh request is made, the old token is deleted and a new one is created.

4. Configuration and Dependencies

4.1. Configuration

The appsettings.json file contains all the necessary configuration settings.

appsettings.json
{
    "Jwt": {
        "Key": "super-secure-secret-key-change-me-super-secure-secret-key-change-me",
        "Issuer": "AuthService",
        "Audience": "ClientApp",
        "ExpiresInMinutes": 15,
        "RefreshTokenExpiresInDays": 7
    },
    "ConnectionStrings": {
        "DatabaseConnection": "Server=auth_db_server;Username=auth_db_user;Password=auth_db_password;Database=auth_db"
    }
}

The database connection string and JWT parameters are defined here. The ApiGateway and AuthService share the same JWT configuration (Key, Issuer, Audience) to ensure that tokens issued by the auth service can be validated by the gateway.

4.2. Dependencies

Key dependencies are managed in the AuthService.csproj file.

BCrypt.Net-Next: For secure password hashing.
Microsoft.AspNetCore.Authentication.JwtBearer: For handling JWT authentication.
Npgsql.EntityFrameworkCore.PostgreSQL: To interact with a PostgreSQL database.
Microsoft.EntityFrameworkCore.Design: For managing database migrations.

5. Docker and Deployment

The service is containerized using a multi-stage Dockerfile. The final image is based on a lightweight ASP.NET runtime image, which is optimized for deployment.