Omni can integrate with your enterprise SAML provider for authentication and identity management. See also information about how SAML impacts Omni authentication. Please contact support@siderolabs.com or your account manager to enable SAML on the SaaS version of Omni.

This guide shows you how to create a user in an Omni instance with SAML authentication enabled.

Grant the new user access to Omni in your SAML identity provider. The new user should login to the new user account, in order for Omni to have the account synchronized with the SAML provider.

Log into Omni using another account with Admin permissions, navigate to Settings, then find the newly added user in the list of users. Now, select “Edit User” from the menu under the ellipsis:

Change the role to Reader, Operator or Admin as appropriate:

And click “Update User”. The user will now have the appropriate role within Omni, and be associated with the SAML user.

This guide shows you how to configure your Omni instance so that new users logging in with SAML authentication are automatically assigned to a role based on their SAML role attributes.

Create the file assign-operator-to-engineers-label.yaml for the SAMLLabelRule resource, with the following content:

Copy

metadata:
  namespace: default
  type: SAMLLabelRules.omni.sidero.dev
  id: assign-operator-to-engineers-label
spec:
  assignroleonregistration: Operator
  matchlabels:
    - saml.omni.sidero.dev/role/engineers

As an admin, create it on your Omni instance using omnictl:

Copy

omnictl apply -f assign-operator-to-engineers-label.yaml

This will create a resource that assigns the Operator role to any user that logs in with SAML and has the SAML attribute Role with the value engineers.

Log in to Omni as a new SAML user with the SAML attribute with name Role and value engineers.

This will cause the user created on the Omni side to be labeled as saml.omni.sidero.dev/role/engineers.

This label will match the SAMLLabelRule resource we created above, and the user will automatically be assigned the Operator role.

Note

When there are multiple matches from different SAMLLabelRule resources, the matched role with the highest access level will be assigned to the user.

Warning

This role assignment will only work for the new users logging in with SAML.

The SAML users who have already logged in to Omni at least once will not be matched by the SAMLLabelRule resource and their roles will not be updated.

Warning

If the logged in SAML user is the very first user logging in to an Omni instance, it will not be matched by the SAMLLabelRule resource and always be assigned the Admin role.

Workspace ONE Access

This section describes how to create a Web App inside Workspace ONE Acces (WSOA).

First, login to the WSOA user interface and browse to Resources -> Web Apps -> New

Next, enter values for the following options before clicking on Next.

On the Single Sign-On page, enter the following values:

Still on the Single Sign-On page, in the Advanced Properties section, set the following toggle buttons;

At the bottom of the Single Sign-On page, in the Custom Attribute Mapping section, add the following attributes:

Click Next to continue and select the access policy as required by your organization.

Now it’s time to click the Save & Assign button and permit the Users and Groups allowed to login to Omni.

On the Assign screen, enter the following:

• Select the permitted group from your backing Active Directory or LDAP server.

• Set the Deployment Type to Automatic.

Finally, obtain the IdP Metadata URL by clicking on Settings and then the Copy URL link.

Omni

Provide the following flags to the Omni container on launch.

For example;

Copy

--auth-saml-enabled=true
--auth-saml-url=https://{workspace-one-host}/SAAS/API/1.0/GET/metadata/idp.xml
--auth-saml-label-rules='{"groups": "groups"}'

Now that you have started Omni with the correct flags, refer to the Auto-assign roles to SAML users guide for information on how to automatically assign roles to users based on their SAML attributes.

Note that when using groups, the group name is prefixed with saml.omni.sidero.dev/groups/ instead of role. For example;

Copy

metadata:
  namespace: default
  type: SAMLLabelRules.omni.sidero.dev
  id: assign-admin-to-platform-admins-label
spec:
  assignroleonregistration: Operator
  matchlabels:
    - saml.omni.sidero.dev/groups/omni-platform-administrators

1. Log in to Otka

2. Create a new App Integration

3. Select “SAML 2.0”

4. Give the Application a recognizable name (we suggest simply “Omni”)

5. Set the SAML Settings and Attribute Statements as shown below:

1. Click “Next” and optionally fill out the Feedback, then click “Finish”

Once that is complete, you should now be able to open the “Assignments” tab for the application you just created and manage your users and access as usual.

In the Azure portal, click "Enterprise Applications".

Click "New Application" and search for "Entra SAML Toolkit".

Name this application something more meaningful if desired and click "Create".

Under the "Manage" section of the application, select "Single sign-on", then "SAML" as the single sign-on method.

In section 1 of this form, enter identifier, reply, and sign on URLs that match the following and save:

• Identifier (Entity ID): https://<domain name for omni>/saml/metadata

• Reply URL (Assertion Consumer Service URL): https://<domain name for omni>/saml/acs

• Sign on URL: https://<domain name for omni>/login

From section 3, copy the "App Federation Metadata Url" for later use.

Again, under the "Manage" section of the application, select "Users and groups".

Add any users or groups you wish to give access to your Omni environment here.

Unifi Identity Enterprise

This section describes how to use Unifi Identity Enterprise (here forward UIIE) SSO with Omni via SAML

First, login to the UIIE Manager portal and navigate to the SSO Apps section in the left menu.

Next, Add a new app. Choose “Add Custom App”

Next, click Add on the “SAML 2.0” option for Sign-on Method

You’ll now be in the Add SAML 2.0 App screen where we’ll define the app.

After entering the above values and clicking the “Add” button, you’ll be taken to another screen with some details. We don’t need anything from here, we’ll get info we need later after further configuration, so just click “Done” to proceed.

You’ll now be on the screen to manage the app, here you’ll want to assign users/groups according to who you would like to have the ability to login to Omni. To start with, you probably only want to assign the person who will be the primary admin, as the first user to login will be granted that role in Omni. Therefore, best practice would be to assign your primary admin, have them login to Omni, then come back into the app here and assign any other users who should have access.

Once you’ve assigned the user(s) accordingly, click the “Settings” bubble at the top of the screen as some final configuration is needed here.

Expand the “Sign On” section at the bottom of the settings page via the “Show More” down arrow.

At the bottom of this section, you’ll see an “Attibute Statements” block, here the mappings from UIIE to Omni fields needs to be entered as below. Use the “Add Another” button to create new ones.

Lastly, you’ll need the IDP Metadata file which can be obtained via the View Setup Instructions link or downloaded as an xml file via the Identity Provider metadata link; both of which are slightly further up the page.

A copy of this file needs to be on the host which will run the Omni container as we’ll feed it in to the container at runtime. You can copy paste contents or download/upload the file whichever is easiest. For the remainder of this guide, we’ll assume this file ends up at the following location on your container host: ~/uiieIDPmetadata.xml

This completes the configurations required in UIIE

Omni

To get Omni to use UIIE as a SAML provider, the following flags should be passed to Docker & the Omni container on launch.

For example;

Copy

docker run \
...
-v $PWD/uiieIDPmetadata.xml:/uiieIDPmetadata.xml
...
ghcr.io/siderolabs/omni:latest \
  --auth-saml-enabled=true
  --auth-saml-metadata-/uiieIDPmetadata.xml

Unfortunately UIIE does not expose group attributes, so you will have to manually assign Omni groups/roles to the users as they are created on first login.