Added more comments and better description in READMEs

OpenIdDict.Server/Authorisation/OpenIdDictTokenResolving.cs

@@ -9,6 +9,19 @@
 
 namespace AK.OAuthSamples.OpenIdDict.Server.Authorisation;
 
+//
+// The default implementation uses encrypted JWTs as Auth Codes with all the identity information. It (especially the JWT signature)
+// blows out the size of the generated code string (may exceed 2,048 symbols) that gets returned in the Query String.
+// Kestrel / Firewalls / browsers may prohibit requests with such long query strings.
+// As a workaround, the code below replaces the 'auth code' with a 'reference token' (a GUID in this case) and stores the pair in memory cache.
+// This approach is not a part of the OAuth2 spec (as it doesn't specify what the 'auth code' must look like) but a widely accepted practice.
+// Here are some links: 
+//		- Auth0 calls them “opaque” token: https://auth0.com/docs/secure/tokens/access-tokens#opaque-access-tokens
+//		- IdentityServer4 is using ref tokens: https://identityserver4.readthedocs.io/en/latest/topics/reference_tokens.html
+//		- LeastPrivilege: https://leastprivilege.com/2015/11/25/reference-tokens-and-introspection/
+//
+
+
 /// <summary>
 ///		Caches the <i>Authorization Code</i> in memory cache and replaces it with a reference that can be resolved later
 /// </summary>

OpenIdDict.Server/README.md

@@ -31,5 +31,5 @@ The authentication client is implemented by [NSwag](https://github.com/RicoSuter
 2. If a relevant user identity cookie not found,
    1. the user gets redirected further to the login page of the linked _Identity Provider_ (for Azure AD it's `https://login.microsoftonline.com/{TENANT}/oauth2/v2.0/authorize`).
    2. on successful authentication withing the tenant, the user gets redirected back to the Auth Gateway to continue the authentication/authorisation process.
-3. On successful authentication/authorisation, the user gets redirected back to Swagger<br> `/swagger/oauth2-redirect.html?code={RECEIVED_CODE}&session_state={RANDOM_STATE}`
+3. On successful authentication/authorisation, the user gets redirected back to Swagger<br> `/swagger/oauth2-redirect.html?code={CODE}&session_state={RANDOM_STATE}`,<br>where `CODE` is a reference token to the auth code stored in memory cache on the server.
 4. Then _NSwag_'s JavaScript exchanges the received _code_ to an _access token_ by running a `POST` request to `/token`.

README.md

@@ -14,7 +14,7 @@ A trusted authority for our enterprise application(s) that
 - issues an _access token_ with app-specific attributes (user’s roles/groups/etc.);
 - is self-hosted without reliance on third-party services.
 
-The code uses _Azure AD_ as the linked _Identity Provider_ (for the identity checks) and an own bespoke authorisation server. 
+The code uses _Azure AD_ as the linked _Identity Provider_ (for the identity checks) and its own bespoke authorisation server. 
 
 ![Transparent Auth Gateway](./auth-gateway-enterprise-apps.png)
 
@@ -26,6 +26,15 @@ The implemented protocols:
 There are 3 projects:
 
 - [AzureADAuthClient](./AzureADAuthClient) – a quick way to ensure that _Azure AD_ authentication is configured. Uses Swagger UI to acquire a token and the standard `Microsoft.Identity` way to validate the token on WebAPI.
-- [OpenIdDict.Server](./OpenIdDict.Server) – a bespoke _Transparent Auth Gateway_ that that implements OAuth 2 [Authorization Code Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) with [PKCE](https://oauth.net/2/pkce/) to serve other client apps as a trusted authority and perform authentication from a linked _Identity Provider_ (a specified tenant of Azure AD).
-- [OpenIdDict.Client.Api](./OpenIdDict.Client.Api) – A Web API app that validates the _access token_ issued by a custom Auth Gateway along with a Swagger front-end to request the token and run HTTP requests against test end-points.
-
+- [OpenIdDict.Server](./OpenIdDict.Server) – a bespoke _Transparent Auth Gateway_ to confirm the user's identity from the linked provider and authorise the user (issue own _access token_) according to the bespoke rules:
+  - implements OAuth 2 [Authorization Code Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) with [PKCE](https://oauth.net/2/pkce/) to serve other client apps as the trusted authority; 
+  - perform authentication from the linked _Identity Provider_ (a specified tenant of Azure AD).
+- [OpenIdDict.Client.Api](./OpenIdDict.Client.Api) – A Web API app that validates the _access token_ issued by the Auth Gateway (`OpenIdDict.Server`). Contains:
+  - Swagger front-end to request the token and run HTTP requests;
+  - test API end-points.
+
+# How's it different?
+The key differences:
+- Issues its own _access token_ based on internal rules and confirmed user's identity from an Azure AD tenant.
+- Requires no database.
+- Has minimum code and "magical" behaviour from the packages.