> ## 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.

# Using SAML and ACLs for fine-grained access control

> Apply fine-grained cluster access control using SAML roles and Omni Access Policies.

If your Omni instance uses a SAML identity provider, you can drive cluster access control directly from the roles defined in your identity provider, without managing individual user permissions in Omni.

This page shows how to use SAML roles as the basis for Access Policy rules. For a general introduction to Access Policies and how they work, see [Manage Access Policies (ACLs)](../how-to-manage-acls).

## How SAML roles map to Omni labels

When a user signs in via SAML, Omni reads their role attributes from the SAML assertion and attaches them as labels in the format:

```
saml.omni.sidero.dev/role/<role-name>=
```

For example, a user with the SAML role `cluster-support` will have the label:

```
saml.omni.sidero.dev/role/cluster-support=
```

You can use these labels in the `usergroups` section of an Access Policy to match users by their SAML role, without listing individual users by email.

## Configure SAML-based access control

Follow these steps to set up role-based cluster access using your SAML identity provider.

### Step 1: Sign in as the initial SAML user

The first user to sign in via SAML is automatically assigned the Omni `Admin` role. Sign in before configuring any access policies so you have an admin account to apply them with.

### Step 2: Create an access policy

The example below gives users with the SAML role `omni-cluster-support` full access to staging clusters and read-only access to production clusters. Users with the SAML role `omni-cluster-admin` get full access to all clusters.

Adjust the SAML role names, cluster name patterns, and Omni roles to match your setup. For all available roles and the full `AccessPolicy` schema, see the [Access Policies reference](../../reference/acls).

```yaml theme={null}
metadata:
  namespace: default
  type: AccessPolicies.omni.sidero.dev
  id: access-policy
spec:
  usergroups:
    support:
      users:
        - labelselectors:
            - saml.omni.sidero.dev/role/omni-cluster-support=
    admin:
      users:
        - labelselectors:
            - saml.omni.sidero.dev/role/omni-cluster-admin=
  clustergroups:
    staging:
      clusters:
        - match: staging-*
    production:
      clusters:
        - match: prod-*
    all:
      clusters:
        - match: "*"
  rules:
    - users:
        - group/support
      clusters:
        - group/staging
      role: Operator
    - users:
        - group/support
      clusters:
        - group/production
      role: Reader
      kubernetes:
        impersonate:
          groups:
            - read-only
    - users:
        - group/admin
      clusters:
        - group/all
      role: Operator
  tests:
    - name: support engineer has Operator access to staging cluster
      user:
        name: support-eng@example.org
        labels:
          saml.omni.sidero.dev/role/omni-cluster-support: ""
      cluster:
        name: staging-1
      expected:
        role: Operator
    - name: support engineer has Reader access to prod cluster and impersonates read-only group
      user:
        name: support-eng@example.org
        labels:
          saml.omni.sidero.dev/role/omni-cluster-support: ""
      cluster:
        name: prod-1
      expected:
        role: Reader
        kubernetes:
          impersonate:
            groups:
              - read-only
    - name: admin has Operator access to staging cluster
      user:
        name: admin-1@example.org
        labels:
          saml.omni.sidero.dev/role/omni-cluster-admin: ""
      cluster:
        name: staging-1
      expected:
        role: Operator
    - name: admin has Operator access to prod cluster
      user:
        name: admin-1@example.org
        labels:
          saml.omni.sidero.dev/role/omni-cluster-admin: ""
      cluster:
        name: prod-1
      expected:
        role: Operator
```

Apply the policy as the Omni admin user:

```bash theme={null}
omnictl apply -f acl.yaml
```

### Step 3: Verify cluster access

SAML users start with no Omni account-level role, which means they cannot use Omni Web or list all clusters, but they can still access specific clusters through an ACL. This step shows what that looks like in practice.

Sign in as a support engineer, `cluster-support-1@example.org`, and download `omnictl` and `omniconfig` from the Omni UI.

Try to list all clusters:

```bash theme={null}
omnictl --omniconfig ./support-omniconfig.yaml get cluster
```

This will fail because the user has no Omni account-level role:

```
Error: rpc error: code = PermissionDenied desc = failed to validate: 1 error occurred:
	* rpc error: code = PermissionDenied desc = unauthorized: access denied: insufficient role: "None"
```

Now try to get a specific staging cluster:

```bash theme={null}
omnictl --omniconfig ./support-omniconfig.yaml get cluster staging-1
```

This succeeds because the ACL grants the user access to `staging-1` directly:

```
NAMESPACE   TYPE      ID          VERSION
default     Cluster   staging-1   5
```

Try to delete the same cluster:

```bash theme={null}
omnictl --omniconfig ./support-omniconfig.yaml delete cluster staging-1
```

This also succeeds because the ACL grants `Operator`-level access to staging clusters:

```
torn down Clusters.omni.sidero.dev staging-1
destroyed Clusters.omni.sidero.dev staging-1
```

Now try the same operations against a production cluster:

```bash theme={null}
omnictl --omniconfig ./support-omniconfig.yaml get cluster prod-1
omnictl --omniconfig ./support-omniconfig.yaml delete cluster prod-1
```

This fails because the ACL grants only `Reader`-level access to production clusters:

```
Error: rpc error: code = PermissionDenied desc = failed to validate: 1 error occurred:
	* rpc error: code = PermissionDenied desc = unauthorized: access denied: insufficient role: "Reader"
```

As the admin user, both get and delete operations succeed across staging and production clusters.

### Step 4: Allow SAML users to access the Omni web UI

SAML users without an Omni account-level role cannot use the Omni web UI. Access Policies grant cluster-level access but do not assign an account-level role.

To allow a user to use the web UI, assign them at least the `Reader` role from the Users section of the Omni dashboard.