Updated OIDC documentation. Added Zitadel OIDC integration documentation

.docs/oidc/authentik/README.md

@@ -59,6 +59,8 @@ Now, configure your UniFi Voucher Site to use the Authentik client.
 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.
+4. Provide the `AUTH_OIDC_APP_BASE_URL` from your UniFi Voucher Site instance (e.g., `https://voucher.example.com`).
+5. Restart the container after these changes
 
 ### For Confidential Client Configuration
 
@@ -67,6 +69,8 @@ Now, configure your UniFi Voucher Site to use the Authentik client.
 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.
+5. Provide the `AUTH_OIDC_APP_BASE_URL` from your UniFi Voucher Site instance (e.g., `https://voucher.example.com`).
+6. Restart the container after these changes
 
 ---
 

.docs/oidc/keycloak/README.md

@@ -70,6 +70,8 @@ Now, configure your UniFi Voucher Site to use the Keycloak client.
 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`).
+4. Provide the `AUTH_OIDC_APP_BASE_URL` from your UniFi Voucher Site instance (e.g., `https://voucher.example.com`).
+5. Restart the container after these changes
 
 ### For Confidential Client Configuration
 
@@ -77,6 +79,8 @@ Now, configure your UniFi Voucher Site to use the Keycloak client.
 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`).
+5. Provide the `AUTH_OIDC_APP_BASE_URL` from your UniFi Voucher Site instance (e.g., `https://voucher.example.com`).
+6. Restart the container after these changes
 
 ---
 

.docs/oidc/uid/README.md

@@ -2,22 +2,22 @@
 
 ## 1. UID Application Configuration
 
-### Step 1: Log in to your Identity Enterprise Workspace
+### Step 1: Log in to the Identity Enterprise Workspace
 
 1. Access the UID workspace (e.g., `https://your-site.ui.com`).
 2. Log in with your credentials.
 
 ![UID Workspace](images/uid_workspace.png)
 
-### Step 2: Navigate to the Manager portal and create a new application
+### Step 2: Create a new application
 
 1. Select the `Manager Portal`. You will be prompted to verify with MFA.
-2. Once signed in select `SSO Apps` in the left-hand menu.
-3. Press the Plus button in the top right-hand corner.
+2. Select `SSO Apps` in the left-hand menu.
+3. Press the **Plus** button in the top right-hand corner.
 4. Select `Add Custom App`
 5. Select `OIDC` from the menu
 6. Fill in the details for your application.
-   The crucial fields needed are `Initiate Sign-In URI` and `Sign-In Redirect URI`.
+   The required fields needed are `Initiate Sign-In URI` and `Sign-In Redirect URI`.
 
    Initiate Sign-In URI - (e.g., `https://voucher.example.com`)
    Sign-In Redirect URI - (e.g., `https://voucher.example.com/callback`)
@@ -32,32 +32,22 @@
 ![UID Add OIDC App](images/uid_add_oidc_app.png)
 ![UID Tool Collection App](images/uid_tool_collection_app.png)
 
-### Step 3: Create or update your application configuration
+---
 
-> Attention!: UID currently only supports the `confidential` Client Type.
+## 2. UniFi Voucher Site Configuration
 
-1. Copy the values from your `Well Known Config Endpoint`, `Client ID` and `Client Secret` into your application configuration. Then set the `AUTH_OIDC_CLIENT_TYPE` to `confidential`.
+Now, configure your UniFi Voucher Site to use the UID client.
 
-`docker-compose.yml`
-```yaml
-      AUTH_OIDC_ISSUER_BASE_URL: 'https://your-site.ui.com/gw/idp/api/v1/public/oauth/your-secret-token/.well-known/openid-configuration'
-      AUTH_OIDC_APP_BASE_URL: 'voucher.example.com'
-      AUTH_OIDC_CLIENT_ID: 'atlafa3i2j5ebhna5ds3hsxpx'
-      AUTH_OIDC_CLIENT_TYPE: 'confidential'
-      AUTH_OIDC_CLIENT_SECRET: 'vcusek6ixxjgxvvo57dqohxcjtjlqfutldvtbgycmpqltzt7zo'
-```
+1. In your UniFi Voucher Site configuration, set `AUTH_OIDC_CLIENT_TYPE` as `confidential`.
+2. Set the `AUTH_OIDC_CLIENT_ID` as found within the UID Application.
+3. Provide the `AUTH_OIDC_CLIENT_SECRET` as found within the UID Application.
+4. Provide the `AUTH_OIDC_ISSUER_BASE_URL` from your UID domain (e.g., `https://your-site.ui.com/gw/idp/api/v1/public/oauth/your-secret-token/.well-known/openid-configuration`).
+5. Provide the `AUTH_OIDC_APP_BASE_URL` from your UniFi Voucher Site instance (e.g., `https://voucher.example.com`).
+6. Restart the container after these changes
 
-2. Build your application or update it.
+---
 
-```bash
-sudo docker-compose up -d
-```
-
-```bash
-sudo docker-compose up -d --force-recreate
-```
-
-### Testing OIDC Sign-In
+## 3. Testing and Troubleshooting
 
 **From `UID Workspace`**
 
@@ -67,14 +57,14 @@ Navigate to the Applications section and select your application. This will laun
 ![UID Demo Sign-In](images/uid_demo_sign_in.png)
 ![UID OIDC Sign-In Success](images/uid_oidc_sign_in_success.png)
 
-**External Sign In form outside of UID**
+**External Sign In from outside of UID**
 
 > Notice: You will only be prompted for UID sign-in if you have not signed in within your predefined sign in policy in UID.
 
 Access your application via the `Initiate Sign-In URI` this will prompt a new window to sign in to UID. Once you sign in you will be redirected back to your application.
 
-![uid-signin}](images/uid_sign_in.png)
-![demo-signin](images/uid_demo_sign_in.png)
+![UID Sign-In](images/uid_sign_in.png)
+![UID Demo Sign-In](images/uid_demo_sign_in.png)
 ![UID OIDC Sign-In Success](images/uid_oidc_sign_in_success.png)
 
 That's it you now have OIDC setup and can sign in to your application!

.docs/oidc/zitadel/README.md

@@ -0,0 +1,66 @@
+# ZITADEL
+
+## 1. ZITADEL Project and Application Configuration
+
+### Step 1: Log in to the ZITADEL Console
+
+1. Go to your ZITADEL admin console (e.g., `https://auth.example.com`).
+2. Log in with your admin credentials.
+
+### Step 2: Create a Project
+
+1. In the ZITADEL console, go to **Projects**.
+2. Click **Create New Project**.
+3. Name your project (e.g., `UniFi Voucher Site`).
+4. Click **Create**.
+
+![Projects Overview](images/projects_overview.png)
+![Projects Create](images/projects_create.png)
+
+### Step 3: Create an Application (OAuth2 Client)
+
+Now, create an application under the project you just created.
+
+1. Select your project (e.g., `UniFi Voucher Site`).
+2. Under Applications click **Add**.
+3. Fill in the following fields and click **Continue**:
+    - **Name**: `Production`.
+    - **Type**: `Web`.
+4. Select **Code** and click **Continue**.
+5. Fill in the following fields and click **Continue**:
+    - **Login Redirect URIs**: Enter the URL of your UniFi Voucher callback (e.g., `https://voucher.example.com/callback`).
+    - **Logout Redirect URIs**: Enter the root URL of your UniFi Voucher instance (e.g., `https://voucher.example.com`).
+6. Click **Create** to save the application.
+7. Save the Client ID and Client Secret shown within the popup and click **Close**
+
+![Project Overview](images/project_overview.png)
+![Project Name & Type](images/project_name_type.png)
+![Project Method](images/project_method.png)
+![Project Uris](images/project_uris.png)
+![Project Create Overview](images/project_create_overview.png)
+![Project Secrets](images/project_secrets.png)
+
+---
+
+## 2. UniFi Voucher Site Configuration
+
+Now, configure your UniFi Voucher Site to use the ZITADEL client.
+
+1. In your UniFi Voucher Site configuration, set `AUTH_OIDC_CLIENT_TYPE` as `confidential`.
+2. Set the `AUTH_OIDC_CLIENT_ID` as the ClientId found within the ZITADEL Popup.
+3. Provide the `AUTH_OIDC_CLIENT_SECRET` as the ClientSecret found within the ZITADEL Popup.
+4. Provide the `AUTH_OIDC_ISSUER_BASE_URL` from your Keycloak server (e.g., `https://auth.example.com/.well-known/openid-configuration`).
+5. Provide the `AUTH_OIDC_APP_BASE_URL` from your UniFi Voucher Site instance (e.g., `https://voucher.example.com`).
+6. Restart the container after these changes
+
+---
+
+## 3. Testing and Troubleshooting
+
+1. Test the login flow from your UniFi Voucher Site. It should redirect users to ZITADEL for authentication.
+2. After logging in, users should be redirected back to the voucher site with tokens from ZITADEL.
+
+### Common Issues
+
+- **Invalid Redirect URI**: Ensure the callback URI matches what is configured in ZITADEL.
+- **Client Secret Errors** (for confidential clients): Ensure that the client secret in both ZITADEL and your UniFi configuration match.

README.md

@@ -367,6 +367,7 @@ Below is a list of tested Identity Providers (IdPs) with detailed integration in
 - [Keycloak Integration](.docs/oidc/keycloak/README.md)
 - [Authentik Integration](.docs/oidc/authentik/README.md)
 - [UniFi Identity Enterprise (UID)](.docs/oidc/uid/README.md)
+- [ZITADEL Integration](.docs/oidc/zitadel/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