# asad-maiga/aspnetcore-authentication-from-scratch architecture

> Architecture diagram of the GitHub repository asad-maiga/aspnetcore-authentication-from-scratch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asad-maiga/aspnetcore-authentication-from-scratch
- Repository: https://github.com/asad-maiga/aspnetcore-authentication-from-scratch

## Overview

This is a teaching Web API that demonstrates how requests become authenticated identities and how those identities are authorized. The main workflow is request authentication, claims/principal creation, policy or resource checks, and a controller response. Cookie and JWT endpoints add login/session or token/refresh flows; API-key authentication is the default scheme. The README documents further authorization examples and capabilities. Wiring below is based on sampled source and README claims; unsampled implementations are represented only where the tree supports their paths.

Main entry points: [`AuthFromScratch/AuthFromScratch.Api/Program.cs`](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Program.cs) (App pipeline), [`AuthFromScratch/AuthFromScratch.Api/Controllers/JwtAuthController.cs`](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Controllers/JwtAuthController.cs) (JWT endpoints), [`AuthFromScratch/AuthFromScratch.Api/Authentication/ApiKey/ApiKeyAuthenticationHandler.cs`](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authentication/ApiKey/ApiKeyAuthenticationHandler.cs) (Claims principal), [`AuthFromScratch/AuthFromScratch.Api/Controllers/IdentityController.cs`](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Controllers/IdentityController.cs) (Identity endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Request runtime"]
  node_program["App pipeline<br/>[Program.cs]"]
end

subgraph group_auth["Authentication"]
  node_api_key["API key handler"]
  node_cookie_auth["Cookie authentication<br/>[Cookie]"]
  node_jwt_validation["JWT validation<br/>[Program.cs]"]
  node_principal["Claims principal"]
  node_jwt_service["Access token service<br/>[JwtTokenService.cs]"]
  node_refresh_service["Refresh token service"]
  node_refresh_store[("Refresh token store")]
end

subgraph group_authz["Authorization"]
  node_policies["Authorization policies<br/>[Program.cs]"]
  node_access_handler["Access-level handler"]
  node_resource_handler["Resource-owner handler"]
end

subgraph group_features["API features"]
  node_identity_controller["Identity endpoints"]
  node_cookie_controller["Cookie endpoints"]
  node_jwt_controller["JWT endpoints"]
  node_resources["Identity resources"]
  node_demo_user["Demo user settings<br/>[DemoUserOptions.cs]"]
end

node_client(("HTTP client"))

node_client -->|"sends request"| node_program
node_program -->|"dispatches default"| node_api_key
node_program -->|"configures scheme"| node_cookie_auth
node_program -->|"configures scheme"| node_jwt_validation
node_api_key -->|"creates principal"| node_principal
node_cookie_auth -->|"restores principal"| node_principal
node_jwt_validation -->|"validates token"| node_principal
node_program -->|"maps controllers"| node_identity_controller
node_program -->|"maps controllers"| node_cookie_controller
node_program -->|"maps controllers"| node_jwt_controller
node_identity_controller -->|"reads resource"| node_resources
node_identity_controller -->|"authorizes resource"| node_resource_handler
node_resource_handler -->|"reads claims"| node_principal
node_identity_controller -->|"requires policy"| node_policies
node_cookie_controller -->|"reads credentials"| node_demo_user
node_jwt_controller -->|"reads credentials"| node_demo_user
node_cookie_controller -->|"signs in or out"| node_cookie_auth
node_jwt_controller -->|"creates access token"| node_jwt_service
node_jwt_controller -->|"issues or rotates"| node_refresh_service
node_refresh_service -->|"reads and writes"| node_refresh_store
node_jwt_controller -->|"reads request identity"| node_principal
node_policies -->|"uses requirement"| node_access_handler

click node_program "https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Program.cs"
click node_api_key "https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authentication/ApiKey/ApiKeyAuthenticationHandler.cs"
click node_cookie_auth "https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/tree/main/AuthFromScratch/AuthFromScratch.Api/Authentication/Cookie"
click node_jwt_validation "https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Program.cs"
click node_principal "https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authentication/ApiKey/ApiKeyAuthenticationHandler.cs"
click node_identity_controller "https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Controllers/IdentityController.cs"
click node_cookie_controller "https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Controllers/CookieAuthController.cs"
click node_jwt_controller "https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Controllers/JwtAuthController.cs"
click node_jwt_service "https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authentication/Jwt/JwtTokenService.cs"
click node_refresh_service "https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authentication/Jwt/RefreshTokenService.cs"
click node_refresh_store "https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authentication/Jwt/InMemoryRefreshTokenStore.cs"
click node_policies "https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Program.cs"
click node_access_handler "https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authorization/MinimumAccessLevelHandler.cs"
click node_resource_handler "https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authorization/ResourceOwnerHandler.cs"
click node_resources "https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authorization/Resources/IdentityResource.cs"
click node_demo_user "https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authentication/Cookie/DemoUserOptions.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_program,node_client toneBlue
class node_api_key,node_cookie_auth,node_jwt_validation,node_principal,node_jwt_service,node_refresh_service,node_refresh_store toneAmber
class node_policies,node_access_handler,node_resource_handler toneMint
class node_identity_controller,node_cookie_controller,node_jwt_controller,node_resources,node_demo_user toneRose
```

## Components

### Request runtime

- [App pipeline](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Program.cs): `AuthFromScratch/AuthFromScratch.Api/Program.cs`

### Authentication

- [API key handler](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authentication/ApiKey/ApiKeyAuthenticationHandler.cs): `AuthFromScratch/AuthFromScratch.Api/Authentication/ApiKey/ApiKeyAuthenticationHandler.cs`
- [Cookie authentication](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/tree/main/AuthFromScratch/AuthFromScratch.Api/Authentication/Cookie): `AuthFromScratch/AuthFromScratch.Api/Authentication/Cookie`
- [JWT validation](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Program.cs): `AuthFromScratch/AuthFromScratch.Api/Program.cs`
- [Claims principal](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authentication/ApiKey/ApiKeyAuthenticationHandler.cs): `AuthFromScratch/AuthFromScratch.Api/Authentication/ApiKey/ApiKeyAuthenticationHandler.cs`
- [Access token service](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authentication/Jwt/JwtTokenService.cs): `AuthFromScratch/AuthFromScratch.Api/Authentication/Jwt/JwtTokenService.cs`
- [Refresh token service](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authentication/Jwt/RefreshTokenService.cs): `AuthFromScratch/AuthFromScratch.Api/Authentication/Jwt/RefreshTokenService.cs`
- [Refresh token store](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authentication/Jwt/InMemoryRefreshTokenStore.cs): `AuthFromScratch/AuthFromScratch.Api/Authentication/Jwt/InMemoryRefreshTokenStore.cs`

### Authorization

- [Authorization policies](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Program.cs): `AuthFromScratch/AuthFromScratch.Api/Program.cs`
- [Access-level handler](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authorization/MinimumAccessLevelHandler.cs): `AuthFromScratch/AuthFromScratch.Api/Authorization/MinimumAccessLevelHandler.cs`
- [Resource-owner handler](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authorization/ResourceOwnerHandler.cs): `AuthFromScratch/AuthFromScratch.Api/Authorization/ResourceOwnerHandler.cs`

### API features

- [Identity endpoints](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Controllers/IdentityController.cs): `AuthFromScratch/AuthFromScratch.Api/Controllers/IdentityController.cs`
- [Cookie endpoints](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Controllers/CookieAuthController.cs): `AuthFromScratch/AuthFromScratch.Api/Controllers/CookieAuthController.cs`
- [JWT endpoints](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Controllers/JwtAuthController.cs): `AuthFromScratch/AuthFromScratch.Api/Controllers/JwtAuthController.cs`
- [Identity resources](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authorization/Resources/IdentityResource.cs): `AuthFromScratch/AuthFromScratch.Api/Authorization/Resources/IdentityResource.cs`
- [Demo user settings](https://github.com/asad-maiga/aspnetcore-authentication-from-scratch/blob/main/AuthFromScratch/AuthFromScratch.Api/Authentication/Cookie/DemoUserOptions.cs): `AuthFromScratch/AuthFromScratch.Api/Authentication/Cookie/DemoUserOptions.cs`

### Other components

- **HTTP client**

## Connections

- HTTP client → App pipeline: sends request
- App pipeline → API key handler: dispatches default
- App pipeline → Cookie authentication: configures scheme
- App pipeline → JWT validation: configures scheme
- API key handler → Claims principal: creates principal
- Cookie authentication → Claims principal: restores principal
- JWT validation → Claims principal: validates token
- App pipeline → Identity endpoints: maps controllers
- App pipeline → Cookie endpoints: maps controllers
- App pipeline → JWT endpoints: maps controllers
- Identity endpoints → Identity resources: reads resource
- Identity endpoints → Resource-owner handler: authorizes resource
- Resource-owner handler → Claims principal: reads claims
- Identity endpoints → Authorization policies: requires policy
- Cookie endpoints → Demo user settings: reads credentials
- JWT endpoints → Demo user settings: reads credentials
- Cookie endpoints → Cookie authentication: signs in or out
- JWT endpoints → Access token service: creates access token
- JWT endpoints → Refresh token service: issues or rotates
- Refresh token service → Refresh token store: reads and writes
- JWT endpoints → Claims principal: reads request identity
- Authorization policies → Access-level handler: uses requirement