🔐 How to Authenticate

💻 Client Authentication

Single-Factor Authentication

An access token can be obtained using basic authentication with:
POST /api/v1/token

Important

External clients are required to activate a subscription via:
POST /api/v1/clients/{key}/subscriptions

Note

The access token can be validated via:
POST /api/v1/token/status.

---

📱 User Authentication

Single-Factor Authentication

Access and refresh tokens can be obtained using:
POST /api/v2/token

Multi-Factor Authentication

1. An OTP can be requested via:
   POST /api/v1/otp

2. The OTP can be exchanged for access and refresh tokens via:
   POST /api/v3/token

Important

To authenticate with OTP, users are required to verify their email via:
POST /api/v1/email/verification/{token}

Note

The access token can be validated via:
POST /api/v1/token/status.

Tip

The access token can be refreshed via:
PUT /api/v2/token

---

⚙️ Complete API Documentation

• Postman collection
• Swagger

---

📐 Architecture & Design

SDK: .NET Core 10
Databases: SQL Server 2022
ORM: Entity Framework Core
Caching: Redis
Message Brokers: RabbitMQ
Additional Libraries: Serilog, Polly, AutoMapper, GoogleAuthenticator
Tests: xUnit, FluentAssertions, Bogus, Respawn

Important

The appsettings.json is validated during API startup.

Important

Database creation and schema management are handled through Entity Framework Core migrations at runtime.

Important

Initialization scripts are automatically executed using DbUp at runtime.

Tip

The application supports updating appsettings.json at runtime without requiring a restart.

---

Architecture

Note

The application follows Clean Architecture.

API

Functionality	Description	Reference
Documentation	Implemented using Swagger.	SwaggerExtensions.cs
Supported Headers	X-Request-ID X-Correlation-ID	HttpHeaderHandlingMiddleware.cs
Logger	Global exception logging is handled from ExceptionHandlingMiddleware. Global HTTP request and response logging is handled from HttpMessageLoggingMiddleware. Logged data can be controlled with SkipLogAttribute and SensitiveDataAttribute.	LoggerSetup.cs
Data Mapping	Used AutoMapper for request/response mappings. Used manual mapping for entity mappings.	Request/Response Mappings Entity Mappings
Paginated Report	For retrieval of both customers and users.	PaginatedReportService.cs
RabbitMQ	Used for asynchronous communication with Notify API for sending notifications to users. Added resilience using Polly.	RabbitMqSetup.cs RabbitMqService.cs RabbitMqExtensions RabbitMqEventAttribute.cs

Security

Functionality	Description	Reference
Tokens	Implemented using the Strategy Pattern.	SecurityTokenHandler.cs
Custom Authorization	Set by AuthorizeUserAttribute.	UserAuthorizationHandler.cs
Rate Limiter	Used with fixed window counter, configurable by appsettings::Security::RateLimiter.	AddRateLimiter()
User Password	Hashed with Pbkdf2.	Pbkdf2Key.cs
Client Contracts	Encrypted using AES when saved and decrypted upon download. A checksum is calculated for each file using MD5.	CreateAndAesEncryptAsync() ReadAndAesDecryptAllBytesAsync() ComputeMd5Checksum()

Caching

Functionality	Description	Reference
Redis	Distributed caching.	RedisService.cs RedisKeyBuilder.cs

Database

Functionality	Description	Reference
Unit Of Work Pattern	Manages all access to the database.	UnitOfWork.cs
Repository Pattern	The full list of repositories can be viewed here.	Repository.cs
Migrations	Automatically executes pending migrations at startup. This functionality is configurable by appsettings::Database::IsDbMigrationAllowed.	ApplyDbPendingMigrationsAsync()
DbUp	Automatically executes pending scripts at startup. This functionality is configurable by appsettings::Database::IsDbUpAllowed.	ApplyDbPendingMigrationsAsync()

---

Client Single-Factor Authentication Steps

1. Client credentials are received in the Authorization header using the format:
   Basic <base64_encoded_key>:<base64_encoded_secret>
2. The credentials from the header are decoded.
3. A database query is executed to fetch client data using the provided key.
4. If the key exists, the client status is validated.
5. If the client status is acceptable, the system checks for an active subscription.
6. If there is an active subscription, the stored secret is compared with the provided secret.
7. If the secret is valid, the failed login attempt counter is reset.
8. An access token (JWT) is generated, scoped to the client ID and the applications the client is allowed to access.

Warning

Invalid key or secret results in HTTP status code 401 Unauthorized.

Warning

Invalid client status or missing active subscription results in HTTP status code 403 Forbidden.

Caution

If the failed login attempt counter exceeds the allowed limit, the client status is updated to BLOCKED.

---

User Single-Factor Authentication Steps

1. User username and password are received in the request body.
2. A database query is executed to fetch user data using the provided username.
3. If the username exists, the user status is validated.
4. If the user status is acceptable, the provided password is hashed using the same method as the stored one.
5. The hashed password is compared with the stored password.
6. If the passwords match, the failed login attempt counter is reset.
7. An access token (JWT) is generated, scoped to the user ID, username, user role and user status.
8. A refresh token (JWT) is generated, scoped to the user ID.

Note

An event is sent when a login attempt is made through a new IP address.

Warning

Invalid username or password results in HTTP status code 401 Unauthorized.

Warning

Invalid user status results in HTTP status code 403 Forbidden.

Caution

If the failed login attempt counter exceeds the allowed limit, the user status is updated to BLOCKED and an alert for login attempt is registered.

---

User Multi-Factor Authentication Steps

1. User username and password are received in the request body.
2. A database query is executed to fetch user data using the provided username.
3. If the username exists, the user status is validated.
4. If the user status is acceptable, the provided password is hashed using the same method as the stored one.
5. The hashed password is compared with the stored password.
6. If the passwords match, the failed login attempt counter is reset.
7. A one-time password is generated and saved to Redis.
8. A message is registered to send the one-time password to the user via the preferred notification provider.
9. The user receives the one-time password and enters it.
10. An attempt is made to fetch the one-time password from Redis.
11. If the one-time password is valid and not expired, it is deleted from Redis.
12. An access token (JWT) is generated, scoped to the user ID, username, user role and user status.
13. A refresh token (JWT) is generated, scoped to the user ID.

Note

Each one-time password is stored in Redis with an absolute expiration.

Warning

Invalid username or password or one-time password results in HTTP status code 401 Unauthorized.

Warning

Invalid user status results in HTTP status code 403 Forbidden.

Caution

A failed login attempt counter is maintained in Redis per one-time password. If the counter exceeds the allowed limit, the one-time password is deleted.

---

Testing

• Unit Tests
• Integration Tests