Skip to main content
When SAML authentication is enabled, Omni can automatically assign roles to new users based on their SAML attributes. To configure this, use SAMLLabelRule resources to map SAML attribute labels to Omni roles. If no rules are configured, roles must be assigned manually by an administrator.

​
Prerequisites

  • SAML authentication must be configured on your Omni instance. See Authentication and Authorization for setup instructions.
  • omnictl must be installed and configured with Admin access to your Omni instance.

​
How SAML label rules work

When a SAML user logs in to Omni, their SAML attributes are read and mapped to labels on the user resource. Omni recognises the following SAML attribute names by default and maps them to the role label key: For example, a user with the SAML attribute Role: engineers will be labeled saml.omni.sidero.dev/role/engineers in Omni automatically when using Google or a compatible provider. If your SAML identity provider uses a different attribute name, you must configure Omni to map it to the role key. This can be done via the CLI flag when starting the Omni server:
Or via the Omni configuration file:
For the full list of configuration options, see the Omni Configuration reference. Once the correct labels are appearing on your users, a SAMLLabelRule resource can automatically assign an Omni role when a matching label is found. If multiple rules match the same user, the role with the highest access level is assigned.

​
Create and verify a SAML label rule

The following example creates a rule that assigns the Operator role to any new SAML user whose SAML attributes include Role: engineers.

​
Step 1: Create the rule

Create and apply the SAMLLabelRule resource:
The fields in the spec are:

​
Step 2: Verify the rule was applied

Log in to Omni as a SAML user with the matching attribute, then confirm the role was assigned by running the following command, replacing <user-email> with the user’s email address:
The output should show the assigned role under the user’s spec.

​
Limitations

The following limitations apply when automatically assigning roles to SAML users:
  • SAML label rules only apply to users logging in for the first time. If a user has already logged in to Omni at least once, their role will not be updated by a SAMLLabelRule and must be updated manually by an administrator.
  • If the SAML user is the first user to log in to an Omni instance, the SAMLLabelRule will not apply. The first user is always assigned the Admin role, regardless of any label rules.