Updated README.md. Added Prerequisites section. Implemented OIDC IdP …

…Integration Guides. Added Keycloak OIDC implementation guide. Added Authentik OIDC implementation guide. Updated .dockerignore

.dockerignore

@@ -16,6 +16,7 @@ public/dist/
 .options.json
 
 # Project files
+.docs
 .github
 .editorconfig
 .gitignore

.docs/oidc/authentik/README.md

@@ -0,0 +1,81 @@
+# Authentik OIDC
+
+## 1. Authentik Application Configuration
+
+### Step 1: Log in to the Authentik Admin Interface
+
+1. Access the Authentik admin interface (e.g., `https://auth.example.com/if/admin`).
+2. Log in with your admin credentials.
+
+### Step 2: Create a Provider
+
+1. Go to **Providers** in the left-hand menu.
+2. Click **Create Provider**.
+3. Choose **OAuth2/OpenID Connect Provider** as the provider type.
+4. Set the following fields:
+    - **Name**: `unifi-voucher-provider`.
+    - **Authentication flow**: `default-authentication-flow`.
+    - **Authorization flow**: `default-provider-authorization-implicit-consent`.
+    - **Client Type**: Select either `public` or `confidential` based on your needs:
+        - **Public**: No client secret is required.
+        - **Confidential**: A client secret will be generated.
+5. Set the **Redirect URI** to match your UniFi Voucher Site’s callback URL (e.g., `https://<unifi-voucher-url>/callback`).
+6. Click **Submit**.
+
+![Create Provider 1](images/create_provider_1.png)
+![Create Provider 2](images/create_provider_2.png)
+![Create Provider 3](images/create_provider_3.png)
+![Create Provider 4](images/create_provider_4.png)
+
+#### For Public Client Method:
+
+- After saving, note down the **Client ID** generated for this provider. You’ll need it when configuring your UniFi Voucher Site.
+
+#### For Confidential Client Method:
+
+- After saving, note down the **Client ID** and **Client Secret** generated for this provider. You’ll need it when configuring your UniFi Voucher Site.
+
+### Step 3: Create a New Application
+
+1. Go to **Applications** in the left-hand menu.
+2. Click **Create Application**.
+3. Fill in the following fields:
+    - **Name**: `UniFi Voucher` (You can choose any relevant name).
+    - **Slug**: This is a URL-friendly identifier (e.g., `unifi-voucher`).
+    - **Provider**: Select the provider you created in step 2 (e.g., `unifi-voucher-provider`).
+4. Click **Submit** to save.
+
+![Create Application](images/create_application.png)
+
+---
+
+## 2. UniFi Voucher Site Configuration
+
+Now, configure your UniFi Voucher Site to use the Authentik client.
+
+### For Public Client Configuration
+
+1. In your UniFi Voucher Site configuration, set `AUTH_OIDC_CLIENT_TYPE` as `public`.
+2. Set the `AUTH_OIDC_CLIENT_ID` as configured in Authentik (found in the Authentik provider configuration).
+3. Provide the `AUTH_OIDC_ISSUER_BASE_URL` from your Authentik provider.
+    - You can find this under **Providers > unifi-voucher-provider > OpenID Configuration URL** in Authentik.
+
+### For Confidential Client Configuration
+
+1. In your UniFi Voucher Site configuration, set `AUTH_OIDC_CLIENT_TYPE` as `confidential`.
+2. Set the `AUTH_OIDC_CLIENT_ID` as configured in Authentik (found in the Authentik provider configuration).
+3. Provide the `AUTH_OIDC_CLIENT_SECRET` (found in the Authentik provider configuration).
+4. Provide the `AUTH_OIDC_ISSUER_BASE_URL` from your Authentik provider.
+    - You can find this under **Providers > unifi-voucher-provider > OpenID Configuration URL** in Authentik.
+
+---
+
+## 3. Testing and Troubleshooting
+
+1. Test the login flow from your UniFi Voucher Site. Ensure it redirects to Authentik for authentication.
+2. After logging in, the user should be redirected back to the voucher site with the appropriate tokens.
+
+### Common Issues
+
+- **Invalid Redirect URI**: Ensure the callback URI matches what is configured in Authentik.
+- **Client Secret Errors** (for confidential clients): Double-check the client secret in both Authentik and your UniFi configuration.

.docs/oidc/keycloak/README.md

@@ -0,0 +1,91 @@
+# Keycloak OIDC
+
+## 1. Keycloak Client Configuration
+
+### Step 1: Log in to the Keycloak Admin Console
+
+1. Go to your Keycloak admin console (e.g., `https://auth.example.com/`).
+2. Log in with your admin credentials.
+
+### Step 2: Create a New Realm (Optional)
+
+If you don't already have a realm:
+
+1. Click **Add Realm** in the left-hand menu.
+2. Name your realm (e.g., `unifi-voucher`).
+3. Save the realm.
+
+![Create Realm](images/create_realm.png)
+
+### Step 3: Create a Client
+
+1. Inside your realm, go to **Clients** in the left-hand menu.
+2. Click **Create**.
+3. Fill in the following fields:
+    - **Client ID**: `unifi-voucher-site` (You can choose any name relevant to your UniFi Voucher Site).
+    - **Client Protocol**: `openid-connect`.
+    - Click **Save**.
+
+![Create Client](images/create_client.png)
+
+### Step 4: Configure the Client
+
+You’ll see various tabs for configuring the client. Set the following fields based on the type of method you want:
+
+#### A. **Public Client Method**
+
+1. Go to the **Settings** tab.
+2. Set **Access Type** to `public`.
+3. Ensure **Implicit Flow Enabled** is set to `ON`. (This enables the Implicit flow for public clients).
+4. Set **Valid Redirect URIs** to your UniFi voucher callback URL (e.g., `https://voucher.example.com/callback`).
+5. Click **Save**.
+
+In this mode, no client secret is required. The public client relies on the Implicit flow without needing to authenticate itself.
+
+![Client Settings 1](images/client_settings_1.png)
+![Client Settings 2](images/client_settings_2.png)
+
+#### B. **Confidential Client Method**
+
+1. Go to the **Settings** tab.
+2. Set **Access Type** to `confidential`.
+3. Ensure **Standard Flow Enabled** is set to `ON`.
+4. Set **Valid Redirect URIs** to your UniFi voucher callback URL (e.g., `https://voucher.example.com/callback`).
+5. Click **Save**.
+
+6. After saving, go to the **Credentials** tab to get the **Client Secret**. This secret will be used by your UniFi Voucher Site when authenticating as a confidential client.
+
+![Client Settings 3](images/client_settings_3.png)
+![Client Settings 2](images/client_settings_2.png)
+![Client Secret](images/client_secret.png)
+
+---
+
+## 2. UniFi Voucher Site Configuration
+
+Now, configure your UniFi Voucher Site to use the Keycloak client.
+
+### For Public Client Configuration
+
+1. In your UniFi Voucher Site configuration, set `AUTH_OIDC_CLIENT_TYPE` as `public`.
+2. Set the `AUTH_OIDC_CLIENT_ID` as configured in Keycloak (e.g., `unifi-voucher-site`).
+3. Provide the `AUTH_OIDC_ISSUER_BASE_URL` from your Keycloak server (e.g., `https://auth.example.com/realms/{realm}/.well-known/openid-configuration`).
+
+### For Confidential Client Configuration
+
+1. In your UniFi Voucher Site configuration, set `AUTH_OIDC_CLIENT_TYPE` as `confidential`.
+2. Set the `AUTH_OIDC_CLIENT_ID` as configured in Keycloak (e.g., `unifi-voucher-site`).
+3. Provide the `AUTH_OIDC_CLIENT_SECRET` (found in the Credentials tab in Keycloak).
+4. Provide the `AUTH_OIDC_ISSUER_BASE_URL` from your Keycloak server (e.g., `https://auth.example.com/realms/{realm}/.well-known/openid-configuration`).
+
+---
+
+## 3. Testing and Troubleshooting
+
+1. Test the login flow from your UniFi Voucher Site. Ensure it redirects to Keycloak for authentication.
+2. After logging in, the user should be redirected back to the voucher site with the appropriate tokens.
+
+### Common Issues
+
+- **Invalid Redirect URI**: Ensure the callback URI matches what is configured in Keycloak.
+- **Client Secret Errors** (for confidential clients): Double-check the client secret in both Keycloak and your UniFi configuration.

README.md

@@ -28,11 +28,25 @@ UniFi Voucher Site is a web-based platform for generating and managing UniFi net
 - NodeMailer
 - PDFKit
 
+## Prerequisites
+
+- UniFi Network Controller (Cloud Key, Dream Machine, or Controller software)
+- UniFi Access Point (AP)
+- UniFi Local Account with 'Full Management' access
+
+[Follow this guide to set up the Hotspot Portal](https://help.ui.com/hc/en-us/articles/115000166827-UniFi-Hotspot-Portal-and-Guest-WiFi), then continue with the installation below
+
+> Ensure voucher authentication is enabled within the Hotspot Portal
+
+> Attention!: We recommend only using Local UniFi accounts due to short token lengths provided by UniFi Cloud Accounts. Also, UniFi Cloud Accounts using 2FA are not supported!
+
+> Note: When creating a Local UniFi account ensure you give 'Full Management' access rights to the Network controller. The 'Hotspot Role' won't give access to the API and therefore the application will throw errors.
+
 ## Installation
 
 ### Docker
 
-- Code from master is build by Docker Hub
+- Code from master is build by GitHub actions
 - Builds can be pulled by using this command: `docker pull glenndehaan/unifi-voucher-site`
 - An example docker compose file can be found below:
 
@@ -98,10 +112,6 @@ services:
       LOG_LEVEL: 'info'
 ```
 
-> Attention!: We recommend only using Local UniFi accounts due to short token lengths provided by UniFi Cloud Accounts. Also, UniFi Cloud Accounts using 2FA won't work!
-
-> Note: When creating a Local UniFi account ensure you give 'Full Management' access rights to the Network controller. The 'Hotspot Role' won't give access to the API and therefore the application will throw errors.
-
 ### Home Assistant Add-on
 
 For users of Home Assistant, we provide a dedicated add-on to seamlessly integrate the UniFi Voucher Site with your Home Assistant instance. This add-on simplifies the setup process and allows you to manage UniFi vouchers directly from your Home Assistant dashboard.
@@ -390,6 +400,19 @@ To identify which client types your OpenID Connect (OIDC) provider supports (Pub
 
    For confidential clients, confirm that the `token_endpoint_auth_methods_supported` field lists options like `client_secret_post` or `client_secret_basic`, which indicate that the provider supports client secret authentication.
 
+### OIDC IdP Integration Guides
+
+This section provides integration guides for configuring the UniFi Voucher Site with various OIDC (OpenID Connect) Identity Providers (IdPs). These guides cover the necessary steps for setting up the IdP, configuring client credentials, and integrating the IdP with the UniFi Voucher Site.
+
+#### Available Guides
+
+Below is a list of tested Identity Providers (IdPs) with detailed integration instructions:
+
+- [Keycloak Integration](.docs/oidc/keycloak/README.md)
+- [Authentik Integration](.docs/oidc/authentik/README.md)
+
+> Integrated with an IdP that is not on the list? Feel free to create a guide for others and contribute it to the project
+
 ## Screenshots
 
 ### Login (Desktop)