diff --git a/.docs/oidc/authentik/README.md b/.docs/oidc/authentik/README.md index 4aec832..f0645b2 100644 --- a/.docs/oidc/authentik/README.md +++ b/.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 --- diff --git a/.docs/oidc/keycloak/README.md b/.docs/oidc/keycloak/README.md index af4a2f6..b57510d 100644 --- a/.docs/oidc/keycloak/README.md +++ b/.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 --- diff --git a/.docs/oidc/uid/README.md b/.docs/oidc/uid/README.md index 531c382..febac4c 100644 --- a/.docs/oidc/uid/README.md +++ b/.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! diff --git a/.docs/oidc/zitadel/README.md b/.docs/oidc/zitadel/README.md new file mode 100644 index 0000000..06061dc --- /dev/null +++ b/.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. diff --git a/.docs/oidc/zitadel/images/project_create_overview.png b/.docs/oidc/zitadel/images/project_create_overview.png new file mode 100644 index 0000000..f26c242 Binary files /dev/null and b/.docs/oidc/zitadel/images/project_create_overview.png differ diff --git a/.docs/oidc/zitadel/images/project_method.png b/.docs/oidc/zitadel/images/project_method.png new file mode 100644 index 0000000..44c2bc8 Binary files /dev/null and b/.docs/oidc/zitadel/images/project_method.png differ diff --git a/.docs/oidc/zitadel/images/project_name_type.png b/.docs/oidc/zitadel/images/project_name_type.png new file mode 100644 index 0000000..4f0ea78 Binary files /dev/null and b/.docs/oidc/zitadel/images/project_name_type.png differ diff --git a/.docs/oidc/zitadel/images/project_overview.png b/.docs/oidc/zitadel/images/project_overview.png new file mode 100644 index 0000000..e35c053 Binary files /dev/null and b/.docs/oidc/zitadel/images/project_overview.png differ diff --git a/.docs/oidc/zitadel/images/project_secrets.png b/.docs/oidc/zitadel/images/project_secrets.png new file mode 100644 index 0000000..b8865da Binary files /dev/null and b/.docs/oidc/zitadel/images/project_secrets.png differ diff --git a/.docs/oidc/zitadel/images/project_uris.png b/.docs/oidc/zitadel/images/project_uris.png new file mode 100644 index 0000000..ceace50 Binary files /dev/null and b/.docs/oidc/zitadel/images/project_uris.png differ diff --git a/.docs/oidc/zitadel/images/projects_create.png b/.docs/oidc/zitadel/images/projects_create.png new file mode 100644 index 0000000..8855403 Binary files /dev/null and b/.docs/oidc/zitadel/images/projects_create.png differ diff --git a/.docs/oidc/zitadel/images/projects_overview.png b/.docs/oidc/zitadel/images/projects_overview.png new file mode 100644 index 0000000..00bdae8 Binary files /dev/null and b/.docs/oidc/zitadel/images/projects_overview.png differ diff --git a/README.md b/README.md index 898be32..e6e2f87 100644 --- a/README.md +++ b/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