From ffae1be340b8d4fd6eb1bf0ab707d859ed2f7c21 Mon Sep 17 00:00:00 2001 From: Leon Hoppe Date: Sun, 22 Dec 2024 15:13:55 +0100 Subject: [PATCH] added proper documentation for openid integration --- README.md | 2 + docs/authentication.md | 4 +- docs/openid.md | 120 +++++++++++++++++++++++++++++++++++++++++ docs/readme.md | 1 + 4 files changed, 126 insertions(+), 1 deletion(-) create mode 100644 docs/openid.md diff --git a/README.md b/README.md index 4d53003..b41c964 100644 --- a/README.md +++ b/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. diff --git a/docs/authentication.md b/docs/authentication.md index c3489d0..a8e29a1 100644 --- a/docs/authentication.md +++ b/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 diff --git a/docs/openid.md b/docs/openid.md new file mode 100644 index 0000000..00a15f4 --- /dev/null +++ b/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 LoadConfiguration(); + + Task RequestToken(string code, string defaultCallback); + + Task ConstructAuthUri(string defaultCallback, string state = null); + + Task InspectToken(string token); + + Task RefreshAccessToken(string refreshToken); + +} +``` diff --git a/docs/readme.md b/docs/readme.md index df7f363..99198a9 100644 --- a/docs/readme.md +++ b/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