Identity API Project - README

Overview

The Identity API is a gRPC-based authentication and authorization service built using .NET 9 and C# 13.0. It provides functionalities for user registration, login, token generation (JWT and refresh tokens), and role-based authorization. This API serves as a centralized identity management system that can be integrated into larger applications requiring authentication and authorization services.

---

Table of Contents

• Overview
• Features
• Technologies Used
• Architecture
• Setup and Installation
• Usage
  • Running the API
  • Using Postman
• Authentication and Authorization
  • Roles and Permissions
  • Policies
  • Token Management
• API Endpoints
• Notes and Best Practices
• Troubleshooting

---

Features

• User Registration: Allows new users to create accounts with validation checks.
• User Login: Authenticates users and issues JWT and refresh tokens.
• Token Refresh: Provides new JWT tokens using valid refresh tokens.
• Role-Based Authorization: Implements access control based on user roles and permissions.
• Policy Enforcement: Defines and enforces authorization policies using claims.
• gRPC Services: Utilizes gRPC for high-performance communication.
• JSON Transcoding: Supports RESTful JSON APIs via gRPC services.
• Fluent Validation: Ensures robust input validation for requests.

---

Technologies Used

• .NET 9
• C# 13.0
• ASP.NET Core
• Entity Framework Core
• Microsoft Identity
• gRPC with JSON Transcoding
• JWT (JSON Web Tokens)
• Mapster: For object mapping.
• FluentValidation: For input validation.
• MediatR: Implements the mediator pattern.
• SQL Server: As the database.

---

Architecture

The project follows a clean architecture approach, promoting separation of concerns:

• Domain Layer: Contains core entities and logic.
• Application Layer: Implements business logic and use cases.
• Infrastructure Layer: Includes data access, repositories, and external services.
• Presentation Layer: Exposes gRPC services and handles client interactions.
• Shared Layer: Contains shared resources like authentication helpers and constants.

---

Setup and Installation

Prerequisites

• .NET 9 SDK installed on the machine.
• SQL Server instance (can be local or remote).
• Postman (optional, for API testing).

Steps

1. Clone the Repository

2. Configure the Database Connection

   Update the Default connection string in appsettings.json with your SQL Server details:

3. Apply Migrations and Seed Data

   Open a terminal in the project directory and run:

   This command applies migrations and creates the database.

4. Run the Application

   Start the API by running:

   The API will be accessible at https://localhost:5001.

---

Usage

Running the API

Ensure that the API is running locally before attempting to interact with it.

Using Postman

Refer to the Using Identity API with Postman section for detailed instructions on how to interact with the API endpoints.

---

Authentication and Authorization

Roles and Permissions

The API uses role-based authorization with predefined roles:

• Admin
• Manager
• User

Permissions are assigned using claims defined in the Permission class:

• CanCreate
• CanRead
• CanUpdate
• CanDelete

Policies

Authorization policies are defined in PolicyServiceExtensions and are enforced throughout the application:

• AdminPolicy: For administrators with full permissions.
• ManagerPolicy: For managers with limited permissions.
• UserPolicy: For regular users with minimal permissions.
• AdminManagerPolicy: Shared policies for admins and managers.
• AdminUserPolicy: Shared policies for admins and users.

Token Management

• JWT Tokens: Issued upon successful authentication and used for subsequent requests.
• Refresh Tokens: Used to obtain new JWT tokens without re-authenticating.

Tokens are managed using services:

• IJwtToken: Generates JWT tokens based on user claims.
• IRefreshToken: Generates and validates refresh tokens.

---

API Endpoints

gRPC Services Endpoints

The API exposes gRPC services with the following endpoints:

• Create Account

  • Service: CreateAccountServiceProto

  • Method: CreateAccountProto

  • Description: Registers a new user account.

  • Endpoint:

    https://localhost:5001/v1/CreateAccountServiceProto/CreateAccountProto

• Login Account

  • Service: LoginAccountServiceProto

  • Method: LoginAccountProto

  • Description: Authenticates a user and returns tokens.

  • Endpoint:

    https://localhost:5001/v1/LoginAccountServiceProto/LoginAccountProto

• Get New Token

  • Service: GetNewTokenServiceProto

  • Method: GetNewTokenProto

  • Description: Provides a new JWT token using a valid refresh token.

  • Endpoint:

    https://localhost:5001/v1/GetNewTokenServiceProto/GetNewTokenProto

---

Notes and Best Practices

• Password Requirements: Passwords must be at least 8 characters long and include uppercase letters, lowercase letters, and numbers.
• Token Security: Store JWT and refresh tokens securely in your client applications.
• SSL Configuration: For development environments, you might need to disable SSL certificate verification in Postman or trust the development certificate.
• Error Handling: The API returns meaningful error messages via gRPC exceptions. Always check responses for status codes and error details.

---

Troubleshooting

• Database Connection Errors: Ensure the connection string is correct and that the SQL Server instance is accessible.
• Migration Issues: If migrations fail, delete the existing database and try applying migrations again.
• Port Conflicts: If the default ports are occupied, modify the application URLs in launchSettings.json.

---

Using Identity API with Postman

This guide provides step-by-step instructions on how to interact with the Identity API using Postman.

Prerequisites

• Identity API is running locally on https://localhost:5001.
• Postman installed on your machine.

Register a New Account

1. Open Postman and create a new POST request.

2. Set the request URL to:

3. Set the request headers:

   • Content-Type: application/json

4. In the body, select raw and paste the following JSON:

5. Send the request.

6. Verify the response:

   A successful response should be:

Login to Get JWT and Refresh Token

1. Create a new POST request in Postman.

2. Set the request URL to:

3. Set the request headers:

   • Content-Type: application/json

4. In the body, select raw and paste the following JSON:

5. Send the request.

6. Verify the response:

   A successful response will include jwtToken and refreshToken:

7. Save the tokens for future requests.

Refresh JWT Token

1. Create a new POST request in Postman.

2. Set the request URL to:

3. Set the request headers:

   • Content-Type: application/json

4. In the body, select raw and paste the following JSON:

   Replace the refreshToken value with the token received from the login response.

5. Send the request.

6. Verify the response:

   A successful response will include a new jwtToken:

Access Protected Endpoints

To access endpoints that require authentication:

1. Create a new request in Postman.

2. Set the request method and URL according to the endpoint you want to access.

3. Set the request headers:

   • Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR...

     Replace the token with your jwtToken.

4. Send the request.

5. Verify the response.

---

Short Summary

This README provides an in-depth overview of the Identity API project, including its features, setup instructions, usage guidelines, authentication mechanisms, and how to interact with it using Postman. The Identity API is a robust and scalable solution for managing user authentication and authorization in applications built with .NET 9 and C# 13.0.

---

Note: Since the project targets .NET 9 and uses C# 13.0, ensure that the development environment supports these versions.