This Todo REST API allows users to manage their to-do list. It's built with C#, .NET 8, and integrated with Azure AD for secure user authentication via OAuth 2.0 (Authorization Code Flow with PKCE).
- π§± Clean Architecture
 - π Azure AD Authentication + PKCE
 - π OpenAPI (Swagger) docs with XML comments
 - π Paginated API responses
 - 𧬠Entity Framework (Code-First approach)
 - π§ββοΈ Role-Based Access Control (User / Admin)
 - π§ͺ Unit Testing with xUnit & Moq
 - π‘ API Rate Limiting using built-in ASP.NET 8 middleware
 
This project was developed to gain hands-on experience in .NET 8 REST API.
The aim was to go beyond basic CRUD implementation and target real-world, enterprise-grade solutions with a focus on:
1οΈβ£ Azure AD Authentication (OAuth 2.0 Authorization Code Flow)
2οΈβ£ OpenAPI for defining API contracts and Swagger UI for rendering interactive documentation
π‘ Inspiration: This project is based on roadmap.sh, which provides role-based roadmaps, learning resources, and real-world projects to help developers upskill.
This idea has been further extended by simulating how an enterprise-grade API might be designed, secured, and documented.
The project uses Clean Architecture to ensure:
- Clear separation of concerns
 - Maintainability and testability
 - Scalability for future enhancements
 
This API uses OAuth 2.0 Authorization Code Flow with PKCE, designed for secure frontend (SPA) consumption.
- This API simulates being called from a Single Page Application (SPA) or Postman, both of which cannot securely store secrets.
 - PKCE enhances security for public clients.
 - Confidential clients (like server-side apps) can use the flow without PKCE.
 
- Go to Microsoft Entra ID β App Registrations
 - Create an app: 
todo-api-backend - Under Expose an API:
- Click Add Scope
 - Create a scope like 
access-as-app-user - Format: 
api://{Application ID}/access-as-app-user 
 - Under App Roles:
- Create roles: 
admin,user - Enable them
 
 - Create roles: 
 
- Go to App Registrations
 - Create app: 
postman-as-frontend - Under API Permissions:
- Click Add a permission
 - Add delegated access to 
todo-api-backendusing its Application(client) ID 
 - Under Authentication:
- Click Add a platform
 - Select SPA (This is needed to work with Swagger)
 - Add Swagger redirect url 'https://localhost:7280/todoApi/docs/oauth2-redirect.html'
 - Select Mobile and desktop applications (This is needed to work with Postman)
 - Add Postman redirect url 'https://oauth.pstmn.io/v1/callback'
 
 
- In Enterprise Applications > 
todo-api-backend - Assign app roles (
admin,user,guest) to users 
dotnet restoredotnet builddotnet ef database updateOnce the project is configured, there are 2 ways to interact with API :
β Configuration
- Edit appsettings.json Replace placeholder values in the "AzureAd" section:
 
"AzureAd": {
  "TenantId": "{your-tenant-id}",
  "ClientId": "{your-frontend-app-id}",
  "Audience": "{your-backend-app-id}",
  "Domain": "{your-azure-domain}"- Edit SwaggerServiceExtensions.cs Replace hardcoded values used for OAuth2 flow in Swagger UI setup:
 
AuthorizationUrl = new Uri("https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/authorize"),
TokenUrl = new Uri("https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token"),
Scopes = new Dictionary<string, string>
{
    { "api://{your-backend-app-id}/access-as-user", "Access Todo API" }
}
action.OAuthClientId("<your-frontend-app-id>");β This enables the Authorize button in Swagger UI for OAuth2.
Important
Updating above files with your Azure values is required to run the project with Swagger
- Run the API: 
dotnet run - Open https://localhost:7280/todoApi/docs/index.html
 - Click Authorize, login via Azure AD
 
Use Try it out to call endpoints.
- Update 
appsetting.json(similar to above Swagger option) - No need to modify 
SwaggerServiceExtensions.cs - Import the Postman collection from 
/postman/TodoApi.postman_collection.json 
Postman is used here to simulate a public client using the API with OAuth2 + PKCE.
Once the import is successful, use the Postman's Authorization tab to update below placeholders with actual values.
-> {your-tenantId} : Your Azure AD(Entra ID) Tenant ID
-> {your-frontend-app-id} : Application(client) ID of your Front-end app or Postman App on Azure.
-> {your-backend-app-id} :  Application(client) ID of your Backend Todo API on Azure.
Below is how your Postman's Authorization tab(π©green-highlighted) will look like, once all the values are filled in as per above instructions.
- Click "Get New Access Token"
 
This will open a browser window for Azure AD login and fetch an access token.
- After successful login, click "Use Token"
 
The token will be injected into Postman's current Token field (π΅ blue-highlighted in above image).
Ensure the Header Prefix is set to Bearer
β Now, you are all set to make API calls.
The project uses Swashbuckle to auto-generate Swagger UI from OpenAPI specs and XML comments.
- β Custom OpenAPI metadata (title, version, contact info)
 - β XML comments from controllers
 - β Security Definition (OAuth2 + PKCE)
 - β Schema customization using SchemaFilter
 
πSwagger UI Url : https://localhost:7280/todoApi/docs/index.html
Important
The port (7280) may vary depending on your local setup. Update the API & Swagger URL if your project runs on a different port.
This is a personal project but any suggestions or recommendations are welcome.
This project is licensed under the MIT License.

