Installation

This guide covers everything you need to install, configure, and verify AuthService is running correctly.

System Requirements

Before installing AuthService, ensure your system meets these requirements:

Required

.NET 8 SDK

Version 8.0 or higher required for running the serviceDownload .NET 8 SDK →

Git

For cloning the repository and version controlDownload Git →

Optional

IDE

Visual Studio 2022, VS Code, or Rider recommended

API Client

Postman, Insomnia, or curl for testing endpoints

Verify Prerequisites

Check that you have the correct versions installed:

Verify .NET SDK

dotnet --version

Expected output:

8.0.x

If you see a version lower than 8.0, download and install the latest .NET 8 SDK from the official website.

Verify Git

git --version

Expected output:

git version 2.x.x

Installation Steps

Clone the Repository

Clone the AuthService repository to your local machine:

git clone https://github.com/David-Andino/auth-service-dotnet.git
cd auth-service-dotnet/AuthService

Want to use SSH? Use git clone [email protected]:David-Andino/auth-service-dotnet.git instead.

Restore Dependencies

The project uses NuGet packages that need to be restored:

dotnet restore

This will download:

Microsoft.AspNetCore.Authentication.JwtBearer (8.0.0) - JWT authentication
Microsoft.EntityFrameworkCore.Sqlite (8.0.0) - Database provider
Microsoft.EntityFrameworkCore.Design (8.0.0) - EF Core tooling
Swashbuckle.AspNetCore (6.5.0) - API documentation

Expected output:

Restore succeeded.

Review Configuration (Optional)

The service comes with sensible defaults in appsettings.json. You can review or modify:

appsettings.json

{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=authservice.db"
  },
  "Jwt": {
    "SecretKey": "CAMBIA-ESTO-EN-PRODUCCION-usa-un-valor-largo-y-aleatorio-min32chars",
    "Issuer": "AuthService",
    "Audience": "AuthService.Clients",
    "AccessTokenExpiryMinutes": "15",
    "RefreshTokenExpiryDays": "7"
  }
}

For development only! The default JWT SecretKey is fine for local testing, but you MUST change it before deploying to production. See Production Configuration for details.

The SQLite database file authservice.db will be created automatically in the project root when you first run the service.

Build the Project

Compile the application to verify everything is configured correctly:

dotnet build

Expected output:

Build succeeded.
    0 Warning(s)
    0 Error(s)

If you encounter build errors, make sure you’re in the correct directory (auth-service-dotnet/AuthService) and have .NET 8 SDK installed.

Run the Service

Start the AuthService API:

dotnet run

You should see output similar to:

info: Microsoft.EntityFrameworkCore.Database.Command[20101]
      Executed DbCommand (0ms) [Parameters=[], CommandType='Text']
      CREATE TABLE IF NOT EXISTS "__EFMigrationsHistory" ...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

On first run, you’ll see Entity Framework Core create the database schema automatically. This is expected behavior in development mode.

Verify Installation

Confirm that AuthService is running correctly:

Access Swagger UI

Open your web browser and navigate to:

http://localhost:5000

You should see the Swagger UI interface with the following endpoints:

POST /api/auth/register - Register a new user
POST /api/auth/login - Login with credentials
POST /api/auth/refresh - Refresh access token
POST /api/auth/revoke - Revoke refresh token (logout)
GET /api/auth/me - Get current user info

Swagger UI provides interactive documentation where you can test endpoints directly in your browser!

Test the Health of the API

Make a test request to register a user:

curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "test_user",
    "email": "[email protected]",
    "password": "TestPass123!"
  }'

Expected Response (201 Created):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "8f3ZHk9mN2pQr5tVwXyZ1aB4cD6eF8gH...",
  "accessTokenExpiry": "2026-03-10T05:15:00Z",
  "user": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "username": "test_user",
    "email": "[email protected]",
    "createdAt": "2026-03-10T05:00:00Z"
  }
}

If you receive this response, your installation is successful!

Verify Database Creation

Check that the SQLite database was created:

ls -la authservice.db

You should see the database file:

-rw-r--r--  1 user  group  20480 Mar 10 05:00 authservice.db

The database file is created in the same directory where you run dotnet run. For production, you’ll want to use a more robust database like PostgreSQL or SQL Server.

Project Structure

Understand how the AuthService project is organized:

AuthService/
├── Controllers/
│   └── AuthController.cs          # API endpoints (register, login, refresh, etc.)
├── Services/
│   ├── AuthService.cs             # Core authentication logic
│   ├── TokenService.cs            # JWT and refresh token generation
│   └── PasswordService.cs         # PBKDF2 password hashing
├── Entities/
│   ├── User.cs                    # User entity model
│   └── RefreshToken.cs            # Refresh token entity with revocation tracking
├── DTOs/
│   └── AuthDTOs.cs                # Request/Response data transfer objects
├── Data/
│   └── AppDbContext.cs            # Entity Framework Core database context
├── Middleware/
│   └── ExceptionHandlingMiddleware.cs  # Global error handling
├── Program.cs                     # Application entry point and configuration
├── appsettings.json               # Configuration settings
├── appsettings.Development.json   # Development-specific settings
└── AuthService.csproj             # Project file with dependencies

Configuration Options

The service can be configured through appsettings.json:

Database Connection

"ConnectionStrings": {
  "DefaultConnection": "Data Source=authservice.db"
}

Development: Uses SQLite (file-based, no setup required)
Production: Change to PostgreSQL, SQL Server, or MySQL connection string

JWT Configuration

"Jwt": {
  "SecretKey": "your-secret-key-here",
  "Issuer": "AuthService",
  "Audience": "AuthService.Clients",
  "AccessTokenExpiryMinutes": "15",
  "RefreshTokenExpiryDays": "7"
}

Setting	Default	Description
`SecretKey`	Sample key	MUST change in production! Minimum 32 characters
`Issuer`	AuthService	JWT issuer claim
`Audience`	AuthService.Clients	JWT audience claim
`AccessTokenExpiryMinutes`	15	Short-lived access token lifetime
`RefreshTokenExpiryDays`	7	Long-lived refresh token lifetime

Security Critical: The SecretKey is used to sign JWT tokens. If compromised, attackers can forge valid tokens. Always use a cryptographically random key in production and store it securely (Azure Key Vault, AWS Secrets Manager, etc.).

Development Tools

Using Postman

A Postman collection is included in the repository:

Import the collection:

File → Import → AuthService.postman_collection.json

Set the base URL variable:
- baseUrl: http://localhost:5000
Run requests: The collection automatically saves tokens after login/register

Using the .NET CLI

Useful commands for development:

# Auto-restart on file changes
dotnet watch run

Running on a Different Port

To run the service on a different port, use the --urls argument:

dotnet run --urls "http://localhost:8080"

Or configure it in appsettings.Development.json:

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:8080"
      }
    }
  }
}

Troubleshooting

Port 5000 already in use

Error: Failed to bind to address http://127.0.0.1:5000Solution:

Kill the process using port 5000: lsof -ti:5000 | xargs kill -9 (macOS/Linux)
Or run on a different port: dotnet run --urls "http://localhost:5001"

Database locked error

Error: SQLite Error 5: 'database is locked'Solution:

Stop all running instances of the service
Delete authservice.db and restart
For production, use a proper database server

JWT SecretKey error

Error: InvalidOperationException: JWT SecretKey not configuredSolution:

Ensure appsettings.json has a valid Jwt:SecretKey value
The key must be at least 32 characters for security

401 Unauthorized on protected endpoints

Error: Protected endpoints return 401 even with a tokenSolution:

Verify the token format: Authorization: Bearer {token}
Check token hasn’t expired (15-minute lifetime)
Ensure there’s a space between “Bearer” and the token

Environment Variables

Override configuration using environment variables:

export Jwt__SecretKey="your-production-secret-key-here"
export ConnectionStrings__DefaultConnection="Server=..."
dotnet run

Use double underscores (__) to represent nested configuration keys in environment variables.

Next Steps

Now that AuthService is installed and running:

Quickstart Guide

Follow our step-by-step guide to make your first authenticated request

API Reference

Explore all available endpoints and their parameters

Authentication Flow

Understand how JWT and refresh tokens work together

Production Checklist

Prepare your service for production deployment

Development vs Production

Key differences between development and production modes:

Feature	Development	Production
Database	SQLite (auto-created)	PostgreSQL/SQL Server
Swagger UI	Enabled at root (`/`)	Disabled
HTTPS	Optional	Required
Secret Key	Default sample key	Secure vault (Key Vault, Secrets Manager)
Logging	Verbose	Warnings/Errors only
CORS	Permissive	Restricted to specific origins

Never deploy to production with the default configuration. See the Production Checklist for a complete guide.

Get Started

Core Concepts

Guides

System Requirements

Required

.NET 8 SDK

Git

Optional

IDE

API Client

Verify Prerequisites

Installation Steps

Verify Installation

Project Structure

Configuration Options

Database Connection

JWT Configuration

Development Tools

Using Postman

Using the .NET CLI

Running on a Different Port

Troubleshooting

Port 5000 already in use

Database locked error

JWT SecretKey error

401 Unauthorized on protected endpoints

Environment Variables

Next Steps

Quickstart Guide

API Reference

Authentication Flow

Production Checklist

Development vs Production

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​System Requirements

​Required

.NET 8 SDK

Git

​Optional

IDE

API Client

​Verify Prerequisites

​Installation Steps

​Verify Installation

​Project Structure

​Configuration Options

​Database Connection

​JWT Configuration

​Development Tools

​Using Postman

​Using the .NET CLI

​Running on a Different Port

​Troubleshooting

Port 5000 already in use

Database locked error

JWT SecretKey error

401 Unauthorized on protected endpoints

​Environment Variables

​Next Steps

Quickstart Guide

API Reference

Authentication Flow

Production Checklist

​Development vs Production

Build docs developers (and LLMs) love

System Requirements

Required

Optional

Verify Prerequisites

Installation Steps

Verify Installation

Project Structure

Configuration Options

Database Connection

JWT Configuration

Development Tools

Using Postman

Using the .NET CLI

Running on a Different Port

Troubleshooting

Environment Variables

Next Steps

Development vs Production