Skip to main content

Integrate with Omada Controller

Support level: Community

What is Omada Controller?​

Omada Controller is a software platform used to centrally manage and monitor Omada networking devices such as access points, switches, and routers.

-- https://www.omadanetworks.com/

Preparation​

The following placeholders are used in this guide:

  • authentik.company is the FQDN of the authentik installation.

This guide applies to Omada Standard Cloud-Based Controller, Omada Software Controller, and OC300/OC400 hardware controllers. OC200 hardware controllers do not support SAML SSO.

info

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 SAML property mappings, an application/provider pair, and application entitlements to map users to Omada groups.

Create property mappings in authentik​

Omada expects SAML assertions to include user profile attributes, a username attribute, and a usergroup_name attribute. Create custom SAML property mappings so authentik sends the attribute names Omada expects.

  1. Log in to authentik as an administrator and open the authentik Admin interface.
  2. Navigate to Customization > Property Mappings and click Create. Create the following SAML Provider Property Mappings entries:

    • Omada given name mapping:

      • Name: Omada given name
      • SAML Attribute Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
      • Expression:
      return request.user.name.split(" ", 1)[0] if request.user.name else request.user.username

    • Omada surname mapping:

      • Name: Omada surname
      • SAML Attribute Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
      • Expression:
      return request.user.name.rsplit(" ", 1)[-1] if " " in request.user.name else ""

    • Omada username mapping:

      • Name: Omada username
      • SAML Attribute Name: username
      • Expression:
      return request.user.username

    • Omada SAML user group mapping:

      • Name: Omada user group
      • SAML Attribute Name: usergroup_name
      • Expression:
      omada_entitlements = [
          entitlement.name
          for entitlement in request.user.app_entitlements(provider.application)
          if entitlement.name.startswith("Omada-")
      ]

      return omada_entitlements[0] if omada_entitlements else None

Create an application and provider in authentik​

SAML provider changes in authentik 2026.5

authentik 2026.5 introduces changes to how the SAML provider behaves. Specifically, the provider now automatically sets the Issuer value to: https://authentik.company/application/saml/<application_slug>/metadata/

Older versions of authentik set this value to authentik by default. If you're running an older version, please set Issuer to https://authentik.company/application/saml/<application_slug>/metadata/, where <application_slug> is the slug that you selected for the application.

  1. Log in to authentik as an administrator and open the authentik Admin interface.

  2. Navigate to Applications > Applications and click New Application to create an application and provider pair.

    • Application: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings.
    • 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.
      • Temporarily set ACS URL to https://temp.temp.
      • Temporarily set Audience to https://temp.temp.
      • Under Advanced protocol settings:
        • Set an available Signing certificate.
        • Set NameID Property Mapping to authentik default SAML Mapping: UPN.
        • Add the property mappings that you created earlier.
        • Remove authentik default SAML Mapping: Groups, because Omada receives role assignment from the usergroup_name attribute instead of authentik groups.
    • Configure Bindings (optional): you can create a binding (policy, group, or user) to manage the listing and access to applications on a user's Application Dashboard page.

  3. Click Submit to save the new application and provider.

Create application entitlements in authentik​

Use application entitlements to represent the Omada SAML user groups that this application should assign.

  1. Open the Omada Controller application that you just created in the authentik Admin interface.
  2. Click the Application entitlements tab.
  3. Create one entitlement for each Omada SAML user group that users should be able to receive, such as Omada-admins.
  4. Open each entitlement and bind the users or groups that should receive it.
Single Omada user group per user

Omada supports one SAML user group value per user. Ensure that each user receives only one Omada- entitlement for this application.

The entitlement name must exactly match the SAML User Group Name value in Omada. The Omada- prefix keeps Omada-specific authorization scoped to this application and lets the usergroup_name property mapping ignore unrelated entitlements.

Copy the provider metadata URL​

  1. Navigate to Applications > Providers and open the SAML provider that you created in the previous section.
  2. Click the Metadata tab.
  3. Under SAML Metadata, click Copy download URL. This metadata URL is required in the next section.

Omada Controller configuration​

Create a SAML connection​

  1. Log in to the Omada Controller.
  2. Navigate to Global View > Settings > SAML SSO and click Add New SAML Connection.
  3. Configure the following settings:
    • Identity Provider Name: authentik
    • Configuration Method: select Metadata URL.
    • Paste the metadata URL that you copied from authentik.
  4. Click Load Info, and then click Send.
  5. In the Actions column, click Details for the authentik SAML connection.
  6. Copy the Entity ID, Sign-On URL, Omada ID, and Resource ID values. These values are required in later sections.
  7. Click OK.

Create a SAML user group​

  1. At the top-right corner of the SAML SSO page, click Go to SAML User Group.
  2. Click Add New SAML User Group.
  3. Configure the SAML User Group Name, Role, User Type, and Privileges for the new SAML user group.
  4. Click Create.

The SAML User Group Name must exactly match the authentik application entitlement name that users receive. The value is case sensitive.

Reconfigure the authentik provider​

Encode the default relay state​

The default relay state is the Base64-encoded value of the Resource ID and Omada ID, separated by an underscore (_).

echo -n '<Resource_ID>_<Omada_ID>' | base64 --wrap=0

Update the SAML provider​

  1. Log in to authentik as an administrator and open the authentik Admin interface.
  2. Navigate to Applications > Providers and edit the Omada Controller provider.
  3. Configure the following settings:
    • ACS URL: enter the Sign-On URL value from Omada.
    • Audience: enter the Entity ID value from Omada.
    • Under Advanced protocol settings, set Default relay state to the encoded relay state value from the previous section.
  4. Click Update to save your changes.

Configuration verification​

To verify that authentik is correctly integrated with Omada Controller, log out of Omada Controller. Open the Omada Controller application from the authentik User interface. You should be redirected to the Omada Controller dashboard.

Resources​