MechanaXAccessAPI 1.2.2

MechanaX Access API

A comprehensive JWT-based authentication and authorization API library for .NET 10 applications, providing robust security services with minimal configuration.

Features

• JWT Bearer Authentication - Industry-standard token-based authentication
• User Management - Complete user authentication and authorization workflow
• Password Hashing - Secure password storage with PBKDF2
• SQL Server Integration - Efficient data access with Dapper ORM
• Swagger Documentation - Interactive API documentation out of the box
• Minimal API Design - Modern ASP.NET Core minimal API pattern
• Role-Based Authorization - Fine-grained access control

Requirements

• .NET 10 SDK or Runtime (10.0.x or higher)
• SQL Server 2012 or later
• NuGet Package Manager

Installation

Install via NuGet Package Manager:

dotnet add package MechanaXAccessAPI --version 1.2.0

Or via Package Manager Console:

Install-Package MechanaXAccessAPI -Version 1.2.0

Quick Start

1. Configure Services

In your Program.cs:

using MechanaX.Access.Data.API;

var builder = WebApplication.CreateBuilder(args);

// Add MechanaX Access services
builder.AddMechanaXAccessServices();
builder.AddMechanaXAccessCustomServices();

var app = builder.Build();

// Configure MechanaX Access routes
app.ConfigureMechanaXAccessRoutes();
app.ConfigureMechanaXAccessCustomRoutes();

app.Run();

2. Configure Connection Strings

Update your appsettings.json:

{
  "ConnectionStrings": {
    "Default": "Server=localhost;Database=YourDb;User Id=youruser;Password=yourpassword;TrustServerCertificate=True;"
  },
  "Jwt": {
    "Key": "your-secret-key-min-32-characters-long",
    "Issuer": "https://your-api.example.com/",
    "Audience": "https://your-api.example.com/",
    "ExpiryMinutes": 60,
    "PersistentExpiryDays": 3650
  },
  "ApiUser": {
    "Username": "apiuser",
    "Firstname": "User",
    "Surname": "Api",
    "Email": "apiuser@example.com",
    "TypeName": "Administrator"
  }
}

?? Important: For .NET 10 with Microsoft.Data.SqlClient 6.x, you must include either:

• TrustServerCertificate=True (for development/testing)
• Encrypt=True with proper SSL certificates (for production)

3. Run Your Application

dotnet run

Navigate to https://localhost:5000/swagger to view the interactive API documentation.

API Endpoints

Authentication Endpoints

Example: Get Authentication Token

curl -X GET "https://localhost:5000/ApiAuth"

Response:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ...

Example: Login with Credentials

curl -X POST "https://localhost:5000/ApiAuth" \
  -H "Content-Type: application/json" \
  -d '{
    "Username": "testuser",
    "Password": "testpassword"
  }'

Example: Using the Token

curl -X GET "https://localhost:5000/your-protected-endpoint" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Configuration Options

JWT Configuration

Database Configuration

The library uses stored procedures for data access. Ensure your SQL Server database has the required schema and stored procedures configured.

Connection string parameters:

• Server - SQL Server instance
• Database - Database name
• User Id / Integrated Security - Authentication method
• TrustServerCertificate=True - Required for .NET 10 (development)
• Encrypt=True - Use with valid SSL certificates (production)

Advanced Usage

Custom Authorization

// In your endpoint
app.MapGet("/secure-endpoint", [Authorize(Roles = "Administrator")] () => 
{
    return Results.Ok("Authorized!");
});

Injecting User Data Service

app.MapGet("/users", async (IUserData userData) => 
{
    var users = await userData.GetAllUsers();
    return Results.Ok(users);
});

Migration from .NET 8

If you're upgrading from version 1.1.x (targeting .NET 8):

1. Update your project to target .NET 10:

   <TargetFramework>net10.0</TargetFramework>
   

2. Update the package:

   dotnet add package MechanaXAccessAPI --version 1.2.0
   

3. Update connection strings - Add TrustServerCertificate=True:

   {
     "ConnectionStrings": {
       "Default": "Server=localhost;Database=MyDb;...;TrustServerCertificate=True;"
     }
   }
   

See CHANGELOG.md for detailed breaking changes and migration guide.

Security Best Practices

Production Deployment

1. Use Environment Variables for sensitive data:

   export Jwt__Key="your-production-key"
   export ConnectionStrings__Default="Server=prod;..."
   

2. Configure SQL Server SSL:

   • Install valid SSL certificate on SQL Server
   • Use Encrypt=True in connection string
   • Remove or set TrustServerCertificate=False

3. Secure JWT Keys:

   • Use strong, random keys (minimum 32 characters)
   • Rotate keys periodically
   • Store in Azure Key Vault or similar secret management service

4. Enable HTTPS:

   • Always use HTTPS in production
   • Configure proper SSL certificates
   • Enable HSTS headers

Troubleshooting

SQL Connection Issues

Error: "A connection was successfully established with the server, but then an error occurred during the login process"

Solution: Add TrustServerCertificate=True to your connection string (or configure proper SSL certificates).

JWT Token Validation Fails

Error: "IDX10503: Signature validation failed"

Solution: Ensure Jwt:Key in configuration matches between token generation and validation.

Swagger UI Not Loading

Error: API works but Swagger UI shows errors

Solution: Verify AccessAPI.xml documentation file is generated and deployed alongside your application.

Project Structure

MechanaXAccessAPI/
??? AccessAPI/
?   ??? API/                    # API endpoint definitions
?   ?   ??? ApiAuth.cs         # Authentication endpoints
?   ?   ??? ...
?   ??? DataAccess/            # Data access layer
?   ?   ??? Data/              # Data access implementations
?   ?   ??? DbAccess/          # Database access (Dapper)
?   ?   ??? Models/            # Data models
?   ??? Domain/                # Domain logic
?   ??? Models/                # API models
?   ??? Program.cs             # Application entry point
??? README.md

Dependencies

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Changelog

See CHANGELOG.md for version history and release notes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues, questions, or contributions:

• GitHub Issues: Report a bug
• Repository: MechanaXAccessAPI

Authors

• Alan Benington - Initial work - alanxxbooom

Acknowledgments

• Built with ASP.NET Core 10
• Uses industry-standard JWT authentication
• Leverages Dapper for efficient data access
• Swagger/OpenAPI for comprehensive documentation

Version: 1.2.0
Last Updated: January 2025
Status: ? Production Ready