Expand Simple Auth in docs

Author: mythz

MyApp/_pages/releases/v8_05.md

@@ -492,10 +492,14 @@ We're excited to migrate our templates to Kamal for deployments as it has distil
 
 ## Simple API Keys Credentials Auth Provider
 
-We've improved the usability of [Simple Auth with API Keys](/auth/admin-apikeys) story with the new
-`ApiKeyCredentialsProvider` which enables .NET Microservices provide user session like behavior using
-simple API Keys which you'd configure together with the `AuthSecretAuthProvider` and `ApiKeysFeature` to enable
-a Credentials Auth implementation which users can use with their API Keys or Admin AuthSecret.
+The usability of the [Simple Auth with API Keys](/auth/admin-apikeys) story has
+been significantly improved with the new `ApiKeyCredentialsProvider` which enables .NET Microservices to provide
+persistent UserSession-like behavior using simple API Keys which can be configured together with the
+`AuthSecretAuthProvider` and `ApiKeysFeature` to enable a Credentials Auth implementation which users can
+use with their API Keys or Admin AuthSecret.
+
+A typical configuration for .NET Microservices looking to enable Simple Auth access whose APIs are protected
+by API Keys and their Admin functionality protected by an Admin Auth Secret can be configured with:
 
 ```csharp
 public class ConfigureAuth : IHostingStartup
@@ -505,7 +509,7 @@ public class ConfigureAuth : IHostingStartup
         {
             services.AddPlugin(new AuthFeature([
                 new ApiKeyCredentialsProvider(),
-                new AuthSecretAuthProvider(AppConfig.Instance.AuthSecret),
+                new AuthSecretAuthProvider("MyAuthSecret"),
             ]));
             services.AddPlugin(new SessionFeature());
             services.AddPlugin(new ApiKeysFeature());
@@ -518,12 +522,105 @@ public class ConfigureAuth : IHostingStartup
 }
 ```
 
-When registered a Credentials Auth dialog will appear for [ServiceStack Built-in UIs](https://servicestack.net/auto-ui) allowing users to Sign In with their API Keys or Admin Auth Secret. 
+When registered a Credentials Auth dialog will appear for [ServiceStack Built-in UIs](https://servicestack.net/auto-ui)
+allowing users to Sign In with their **API Keys** or Admin **Auth Secret**.
+
+![](/img/pages/auth/simple/ai-server-auth-apiexplorer.png)
+
+### Session Auth with API Keys
+
+Behind the scenes this creates a Server [Auth Session](/auth/sessions)
+but instead of maintaining an Authenticated User Session it saves the API Key in the session then attaches the API Key to each request. This makes it possible to make API Key validated requests with just a session cookie instead of requiring resubmission of API Keys for each request.
+
+### Secure .NET Microservices and Docker Appliances
+
+This is an ideal Auth Configuration for .NET Docker Appliances and Microservices like [AI Server](/posts/ai-server) that don't need the complexity of ASP .NET Core's Identity Auth machinery and just want to restrict access to their APIs with API Keys and restrict Admin functionality to Administrator's with an Auth Secret.
+
+The benefit of `ApiKeyCredentialsProvider` is that it maintains a persistent Session so that end users
+only need to enter their API Key a single time and they'll be able to navigate to all of AI Server's protected pages using their API Key maintained in their Server User Session without needing to re-enter it for each UI and every request.
+
+### User Access with API Keys
+
+AI Server uses **API Keys** to restrict Access to their AI Features to **authorized Users** with Valid API Keys who
+are able to use its Built-in UIs for its AI Features with the Users preferred Name and issued API Key:
+
+![](/img/pages/auth/simple/ai-server-auth-user.png)
+
+After signing in a single time they'll be able to navigate to any protected page and start using AI Server's AI features:
+
+![](/img/pages/auth/simple/ai-server-auth-user-chat.png)
+
+### User Access to API Explorer
+
+This also lets users use their existing Auth Session across completely different UIs
+like [API Explorer](/api-explorer)
+where they'll have the same access to APIs as they would when calling APIs programatically with their API Keys, e.g:
+
+![](/img/pages/auth/simple/ai-server-auth-apiexplorer-api.png)
+
+### Coarse or fine-grained API Key access
+
+By default **any** Valid API Key can access restricted services by `[ValidateApiKey]`
+
+```csharp
+[ValidateApiKey]
+public class Hello : IGet, IReturn<HelloResponse>
+{
+    public required string Name { get; set; }
+}
+```
+
+### API Key Scopes
+
+API Keys can be given elevated privileges where only Keys with user defined scopes:
+
+![](/img/pages/auth/simple/admin-ui-apikeys-edit.png)
+
+Are allowed to access APIs restricted with that scope:
+
+```csharp
+[ValidateApiKey("todo:read")]
+public class QueryTodos : QueryDb<Todo>
+{
+    public long? Id { get; set; }
+    public List<long>? Ids { get; set; }
+    public string? TextContains { get; set; }
+}
+```
+
+### Restricted API Keys to specific APIs 
+
+API Keys can also be locked down to only be allowed to call specific APIs:
+
+![](/img/pages/auth/simple/admin-ui-apikeys-restrict-to.png)
+
+## Admin Access
+
+AI Server also maintains an Admin UI and Admin APIs that are only accessible to **Admin** users who 
+Authenticate with the App's configured Admin Auth Secret who are able to access AI Server's Admin
+UIs to monitor Live AI Requests, create new User API Keys, Manage registered AI Providers, etc. 
+
+![](/img/pages/auth/simple/ai-server-auth-admin-jobs.png)
+
+### Admin Restricted APIs
+
+You can restrict APIs to Admin Users by using `[ValidateAuthSecret]`: 
+
+```csharp
+[Tag(Tags.Admin)]
+[ValidateAuthSecret]
+[Api("Add an AI Provider to process AI Requests")]
+public class CreateAiProvider : ICreateDb<AiProvider>, IReturn<IdResponse>
+{
+    //...
+}
+```
+
+Which are identified in API Explorer with a **padlock** icon whilst APIs restricted by API Key are 
+identified with a **key** icon:
 
-![](/img/pages/auth/simple/apiexplorer-apikey-credentials.png)
+![](/img/pages/auth/simple/ai-server-auth-apiexplorer-admin.png)
 
-Behind the scenes this creates a server session like normal [Session Auth](/auth/sessions) but instead of maintaining an Authenticated User Session it saves the API Key in the session then attaches the API Key to each request which is how it's able to make API Key validated requests with just a session cookie instead of resubmitting their API Key
-for each request.
 
 ## ServiceStack.Swift rewritten for Swift 6