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

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: [e-mail]
        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: [e-mail]
        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: [e-mail]
        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: [e-mail]
        labels:
          saml.omni.sidero.dev/role/omni-cluster-admin: ""
      cluster:
        name: prod-1
      expected:
        role: Operator

Apply the policy as the Omni admin user:

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, [e-mail], and download omnictl and omniconfig from the Omni UI.

Try to list all clusters:

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:

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:

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:

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.