added proper documentation for openid integration

README.md

@@ -6,6 +6,8 @@ A simple backend management api for ASP.NET Core Web APIs
 - [x] User authentication
 - [x] Permission management
 - [x] Generated frontend administration boards
+- [x] API token support
+- [x] OpenID authentication integration
 
 # Usage
 There are two different versions of HopFrame, either the Web API version or the full Blazor web version.

docs/authentication.md

@@ -24,7 +24,9 @@ by configuring your configuration to load these.
 > custom configurations / HopFrame services.
 
 You can specify `Seconds`, `Minutes`, `Hours` and `Days` for either of the two token types.
-These get combined to a single time span.
+These get combined to a single time span. You can also completely disable the default authentication
+by setting the `DefaultAuthentication` to `false`. Note that you will no longer be able to login in any
+way unless you enabled the [OpenID](./openid.md) authentication.
 
 #### Configuration example
 ```json

docs/openid.md

@@ -0,0 +1,120 @@
+# OpenID Authentication
+The HopFrame allows you to use an OpenID provider as your authentication provider for single sign on or better security
+etc. To use it, you just simply need to configure it through the `appsettings.json` or environment variables.
+
+>**Note**: The Blazor module has not yet implemented endpoints for the login process, but the middleware is correctly
+> configured and the `IOpenIdAccessor` service is also provided for you to easily implement the endpoints yourself.
+
+When you have enabled the integration, new endpoints will also be provided to perform the authentication.
+simply use the swagger explorer to look up how the endpoints function. They're all under the subroute
+`/api/v1/openid/`.
+
+## Configure the HopFrame to use OpenID authentication
+
+1. Create / Configure your OpenID provider:
+    
+    - Save the ClientID and Client Secret from the provider, because you need it later.
+    - The default redirect uri looks something like this: `https://example.com/api/v1/openid/callback`.
+      - **Replace** the origin with the FQDN of your service.
+    - In order for the HopFrame to automatically renew expired access tokens you need to enable the `offline_access` scope.
+      - The integration also works without doing that, but then you need to reauthenticate every time your access token expires.
+
+2. Configure the HopFrame integration:
+
+   >**Hint**: All of these configuration options can also be defined as environment variables. Use '__'
+   > to separate the namespaces like so: `HOPFRAME__AUTHENTICATION__OPENID__ENABLED=true`
+
+   - Add the following lines to your `appsettings.json`:
+   ```json
+      "HopFrame": {
+          "Authentication": {
+            "OpenID": {
+              "Enabled": true,
+              "Issuer": "your-issuer",
+              "ClientId": "your-client-id",
+              "ClientSecret": "your-client-secret"
+            }
+          }
+      }
+   ```
+   
+   >**Hint**: If you are using Authentik, the issuer url looks something like this: `https://auth.example.com/application/o/application-name/`.
+   > Just replace the FQDN and application-name with your configured application.
+
+   - **Optional**: You can also disable the default authentication via the config:
+
+   ```json
+      "HopFrame": {
+          "Authentication": {
+            "DefaultAuthentication": false
+          }
+      }
+   ```
+   
+   - **Optional**: By default, the HopFrame will cache the api responses to reduce api latency. This can also be configured in the config (the cache can also be completely disabled here):
+
+   ```json
+      "HopFrame": {
+         "Authentication": {
+            "OpenID": {
+               "Cache": {
+                  "Enabled": true,
+                  "Configuration": {
+                     "Hours": 5
+                  },
+                  "Auth": {
+                     "Seconds": 90
+                  },
+                  "Inspection": {
+                     "Minutes": 5
+                  }
+               }
+            }
+         }
+      }
+   ```
+
+   - **Optional**: You can also define your own callback endpoint like so (you also need to add / replace the endpoint in the provider settings):
+
+   ```json
+      "HopFrame": {
+          "Authentication": {
+            "OpenID": {
+              "Callback": "https://example.com/auth/callback"
+            }
+          }
+      }
+   ```
+   
+   - **Optional**: You can also prevent new users from being created by disabling it in the config:
+
+   ```json
+      "HopFrame": {
+          "Authentication": {
+            "OpenID": {
+              "GenerateUsers": false
+            }
+          }
+      }
+   ```
+
+## Use the abstraction to integrate OpenID yourself
+
+The HopFrame has a service, that simplifies the communication with the OpenID provider called `IOpenIdAccessor`.
+You can inject it like every other service in your application.
+
+```csharp
+public interface IOpenIdAccessor {
+    
+    Task<OpenIdConfiguration> LoadConfiguration();
+    
+    Task<OpenIdToken> RequestToken(string code, string defaultCallback);
+    
+    Task<string> ConstructAuthUri(string defaultCallback, string state = null);
+    
+    Task<OpenIdIntrospection> InspectToken(string token);
+    
+    Task<OpenIdToken> RefreshAccessToken(string refreshToken);
+    
+}
+```

docs/readme.md

@@ -9,6 +9,7 @@ The HopFrame comes in two variations, you can eiter only use the backend with so
 - [Base Models](./models.md)
 - [Authentication](./authentication.md)
 - [Permissions](./permissions.md)
+- [OpenID Integration](./openid.md)
 
 ## HopFrame Web API