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:
SAML attributeProvider
http://schemas.microsoft.com/ws/2008/06/identity/claims/roleMicrosoft
RoleGoogle
roleSamltest
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: 
--auth-saml-label-rules='{"your-custom-attribute": "role"}'
Or via the Omni configuration file: 
auth:
  saml:
    attributeRules:
      your-custom-attribute: role
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: 
cat <<EOF | omnictl apply -f -
metadata:
  namespace: default
  type: SAMLLabelRules.omni.sidero.dev
  id: assign-operator-to-engineers-label
spec:
  assignrole: Operator
  updateoneachlogin: true
  matchlabels:
    - saml.omni.sidero.dev/role/engineers
EOF
The fields in the spec are:
FieldDescription
assignroleThe Omni role to assign to matching users. Valid values are Reader, Operator, and Admin.
updateoneachloginIf true, the role is re-evaluated and updated on every login, not just the first. If false, the role is only assigned on the user’s first login.
matchlabelsA list of SAML-derived labels to match against. Labels follow the format saml.omni.sidero.dev/<attribute-name>/<attribute-value>.

​
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: 
omnictl get user <user-email> -o yaml
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.