From 765e1db8ee24899d338d963d2d33611c40a19554 Mon Sep 17 00:00:00 2001 From: Dewi Roberts Date: Thu, 15 May 2025 15:29:33 +0100 Subject: [PATCH 1/3] Adds omada controller doc and updated integration sidebar --- .../services/omada-controller/index.mdx | 93 +++++++++++++++++++ website/sidebars/integrations.mjs | 1 + 2 files changed, 94 insertions(+) create mode 100644 website/integrations/services/omada-controller/index.mdx diff --git a/website/integrations/services/omada-controller/index.mdx b/website/integrations/services/omada-controller/index.mdx new file mode 100644 index 000000000000..70e4db105df5 --- /dev/null +++ b/website/integrations/services/omada-controller/index.mdx @@ -0,0 +1,93 @@ +--- +title: Integrate with Omada Controller +sidebar_label: Omada Controller +support_level: community +--- + +## What is Omada Controller + +> The Omada Controller is a software platform used to centrally manage and monitor Omada networking devices like access points, switches, and routers. It provides a single interface for configuring, managing, and monitoring these devices, offering centralized control over your entire Omada network. +> +> -- https://www.omadanetworks.com/ + +:::note +Omada Controller is available as [3 options](https://www.tp-link.com/uk/support/faq/3737/): + +1. Cloud Controller +2. Software Controller +3. Hardware Controller + +This guide specifies the required changes for all 3 controller options. +::: + +## Preparation + +The following placeholders are used in this guide: + +- `authentik.company` is the FQDN of the authentik installation. + +:::note +This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application. +::: + +## authentik configuration + +To support the integration of Omada Controller with authentik, you need to create an application/provider pair in authentik. + +### Create an application and provider in authentik + +1. Log in to authentik as an admin, and open the authentik Admin interface. +2. Navigate to **Applications** > **Applications** and click **Create with Provider** to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.) + + - **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. + - Note the application slug, it will be required when filling out the **Identity provider SSO URL** later on. TEMP + - **Choose a Provider type**: select **SAML Provider** as the provider type. + - **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations. + - For Cloud Controller, set the **ACS URL** to `https://aps1-omada-account.tplinkcloud.com/sso/saml/login/`. For Software and Hardware Controllers, set the **ACS URL** as the IP Address and port of your controller followed by `/sso/saml/login` (e.g `https://192.168.10.11:8043/sso/saml/login`). + - For Cloud Controller, temporarily set the **Audience** to `https://omada.tplinkcloud.com/`. For Software and Hardware Controllers, set the **Audience** as the IP Address and port of your Controller (e.g `https://192.168.10.11:8043`). + - Set the **Service Provider Binding** to `Post`. TEMP needs testing + - Under **Advanced protocol settings**, set an available signing certificate. + - **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page. + +3. Click **Submit** to save the new application and provider. + +### App role TEMP + +### Download the metadata file + +1. Log into authentik as an admin, and open the authentik Admin interface. +2. Navigate to **Applications** > **Providers** and click on the name of the newly created Omada Controller provider. +3. Under **Metadata** click the **Download** button. This metadata file will be required in the next section. + +## Omada Controller configuration + +1. Log in to the Omada Controller. +2. Navigate to **Global View** > **Settings** > **SAML SSO**, then click **Add New SAML Connection**. +3. Set **Identity Provider Name** to `authentik`. +4. For **Configuration Method** select `Metadata File`, and upload the metadata file you downloaded from authentik. +5. Click **Send**. +6. In the **Actions** column, click on the **Details** button. +7. Take note of the **Entity ID**, **Omada ID**, **Resource ID**, and click **OK**. These values will be required in the next section. +8. At the top right of the page, click **Go To SAML Role**, followed by **Add New SAML Role**. +9. Set the desired **SAML Role Name**, **Role**, and **Privileges** for the new SAML role. Click TEMP + +## Decoding default relay state + +The default relay state is derived by decoding a combination of the **Resource ID** and **Omada ID** with a Base64 encryption tool. This section provides an example of how to do this. + +1. Go to https://www.base64decode.org/ +2. In the **Decode from Base64 format** section, enter: `_`. +3. Click **Decode**. +4. Click the **Copy to clipboard**. This is the **Default relay state** value that will be required in the next section + +## Reconfigure authentik provider + +1. Log in to authentik as an admin, and open the authentik Admin interface. +2. Navigate to **Applications** > **Providers** and click the **Edit** icon of the newly created Omada Controller provider. +3. Under **Protocol settings**, set **Audience** to the copied **Entity ID** (e.g. `https://aps1-omada-cloud.tplinkcloud.com/`). +4. Under **Advanced protocol settings**, set **Default relay state** to the decoded value from the previous section. TEMP +5. Click **Update** + +## Configuration verification + +To verify that authentik is correctly integrated with Atlassian Cloud, first log out of your account. Then, log back in using your credentials for an internal user. You should be redirected to your authentik instance and after successfully logging in, you should be redirected to the selected Atlassian Cloud app. diff --git a/website/sidebars/integrations.mjs b/website/sidebars/integrations.mjs index 39a16afe12fa..0b2845409795 100644 --- a/website/sidebars/integrations.mjs +++ b/website/sidebars/integrations.mjs @@ -120,6 +120,7 @@ const items = [ "services/fortimanager/index", "services/gravity/index", "services/netbird/index", + "services/omada-controller/index", "services/opnsense/index", "services/pfsense/index", ], From 5c2619768fbf53e61d75daef7f4555741e4bf509 Mon Sep 17 00:00:00 2001 From: Dewi Roberts Date: Thu, 15 May 2025 15:33:45 +0100 Subject: [PATCH 2/3] Update verification section --- website/integrations/services/omada-controller/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/integrations/services/omada-controller/index.mdx b/website/integrations/services/omada-controller/index.mdx index 70e4db105df5..896efbe62dc0 100644 --- a/website/integrations/services/omada-controller/index.mdx +++ b/website/integrations/services/omada-controller/index.mdx @@ -90,4 +90,4 @@ The default relay state is derived by decoding a combination of the **Resource I ## Configuration verification -To verify that authentik is correctly integrated with Atlassian Cloud, first log out of your account. Then, log back in using your credentials for an internal user. You should be redirected to your authentik instance and after successfully logging in, you should be redirected to the selected Atlassian Cloud app. +To verify that authentik is correctly integrated with Omada Controller, first log out of your account. From 46a18741ce2fe6f112fae00438a2ec65e13a7bdd Mon Sep 17 00:00:00 2001 From: Dewi Roberts Date: Fri, 16 May 2025 12:17:06 +0100 Subject: [PATCH 3/3] WIP --- .../services/omada-controller/index.mdx | 27 ++++++++++++++----- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/website/integrations/services/omada-controller/index.mdx b/website/integrations/services/omada-controller/index.mdx index 896efbe62dc0..e2f42287d795 100644 --- a/website/integrations/services/omada-controller/index.mdx +++ b/website/integrations/services/omada-controller/index.mdx @@ -32,7 +32,7 @@ This documentation lists only the settings that you need to change from their de ## authentik configuration -To support the integration of Omada Controller with authentik, you need to create an application/provider pair in authentik. +To support the integration of Omada Controller with authentik, you need to create an application/provider pair, and an application entitlement in authentik. ### Create an application and provider in authentik @@ -45,13 +45,21 @@ To support the integration of Omada Controller with authentik, you need to creat - **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations. - For Cloud Controller, set the **ACS URL** to `https://aps1-omada-account.tplinkcloud.com/sso/saml/login/`. For Software and Hardware Controllers, set the **ACS URL** as the IP Address and port of your controller followed by `/sso/saml/login` (e.g `https://192.168.10.11:8043/sso/saml/login`). - For Cloud Controller, temporarily set the **Audience** to `https://omada.tplinkcloud.com/`. For Software and Hardware Controllers, set the **Audience** as the IP Address and port of your Controller (e.g `https://192.168.10.11:8043`). - - Set the **Service Provider Binding** to `Post`. TEMP needs testing + - Set the **Service Provider Binding** to `Post`. TEMP-needs testing - Under **Advanced protocol settings**, set an available signing certificate. - **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page. 3. Click **Submit** to save the new application and provider. -### App role TEMP +### Create an application entitlement + +An application entitlement is used to control privileged access to the Omada Controller. + +1. Log in to authentik as an admin, and open the authentik Admin interface. +2. Navigate to **Applications** > **Applications**, and click on the **Application entitlements** tab. +3. Click **Create entitlement**, and provide the following required configurations: + - **Name**: provide a suitable name for the application entitlement. + - **Attributes**: TEMP ### Download the metadata file @@ -69,14 +77,15 @@ To support the integration of Omada Controller with authentik, you need to creat 6. In the **Actions** column, click on the **Details** button. 7. Take note of the **Entity ID**, **Omada ID**, **Resource ID**, and click **OK**. These values will be required in the next section. 8. At the top right of the page, click **Go To SAML Role**, followed by **Add New SAML Role**. -9. Set the desired **SAML Role Name**, **Role**, and **Privileges** for the new SAML role. Click TEMP +9. Set the desired **SAML Role Name**, **Role**, and **Privileges** for the new SAML role. The **SAML Role Name** must match the name of the previously created authentik application entitlement. +10. Click TEMP ## Decoding default relay state The default relay state is derived by decoding a combination of the **Resource ID** and **Omada ID** with a Base64 encryption tool. This section provides an example of how to do this. -1. Go to https://www.base64decode.org/ -2. In the **Decode from Base64 format** section, enter: `_`. +1. Go to https://www.base64decode.org/ or another Base64 decoding service/application. +2. In the **Decode from Base64 format** section, enter: `_`. 3. Click **Decode**. 4. Click the **Copy to clipboard**. This is the **Default relay state** value that will be required in the next section @@ -85,9 +94,13 @@ The default relay state is derived by decoding a combination of the **Resource I 1. Log in to authentik as an admin, and open the authentik Admin interface. 2. Navigate to **Applications** > **Providers** and click the **Edit** icon of the newly created Omada Controller provider. 3. Under **Protocol settings**, set **Audience** to the copied **Entity ID** (e.g. `https://aps1-omada-cloud.tplinkcloud.com/`). -4. Under **Advanced protocol settings**, set **Default relay state** to the decoded value from the previous section. TEMP +4. Under **Advanced protocol settings**, set **Default relay state** to the decoded value from the previous section. 5. Click **Update** +## Resources + +- [Omada Networks Azure SSO Documentation](https://www.omadanetworks.com/de/support/faq/4406/#_Toc193896083) + ## Configuration verification To verify that authentik is correctly integrated with Omada Controller, first log out of your account.