> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siderolabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-assign roles to SAML users

> Automatically assign Omni roles to new SAML users based on their SAML attribute labels.

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](../manage-user-in-omni) by an administrator.

## Prerequisites

* SAML authentication must be configured on your Omni instance. See [Authentication and Authorization](../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 attribute                                                 | Provider  |
| -------------------------------------------------------------- | --------- |
| `http://schemas.microsoft.com/ws/2008/06/identity/claims/role` | Microsoft |
| `Role`                                                         | Google    |
| `role`                                                         | Samltest  |

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:

```bash theme={null}
--auth-saml-label-rules='{"your-custom-attribute": "role"}'
```

**Or** via the Omni configuration file:

```yaml theme={null}
auth:
  saml:
    attributeRules:
      your-custom-attribute: role
```

For the full list of configuration options, see the [Omni Configuration reference](../../reference/omni-configuration#auth-saml).

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:

```bash theme={null}
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:

| Field               | Description                                                                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `assignrole`        | The Omni role to assign to matching users. Valid values are `Reader`, `Operator`, and `Admin`.                                                       |
| `updateoneachlogin` | If `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. |
| `matchlabels`       | A 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:

```bash theme={null}
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.