Skip to content
Dashboard
Theme
Theme

Role rules

Assign an optional application role from bounded group, domain and connection rules.

View Markdown

Role rules are managed through /v1/role_rules with policies:read or policies:write. Business supports up to 100 rules; Enterprise supports up to 1,000 and bounded expression conditions. The selected role is application data, not an OhAuthCat account or staff permission.

Matching classes are evaluated in this order:

  1. Group rules.
  2. Exact organization-verified primary-email domain rules.
  3. Connection-default rules.

Within a class, ascending priority and then stable rule ID select the role. Conditions that evaluate false do not match. A matched explicit deny refuses sign-in; a role assignment cannot override an admission refusal. Values are bounded to 128 bytes.

The optional result travels in the profile through code exchange and access-profile reads. No match means no role, and a newer unmatched sign-in clears the previously stored role rather than keeping an old permission indefinitely. Existing rules remain enforced after downgrade; above-plan edits are refused and deletion remains available.

A rule can carry an optional condition: an allow or deny action over a bounded expression. Expressions combine leaf, all and any nodes over email, email.domain and groups.idp, using equals, in, contains and contains_any. They are the same declarative expressions as sign-in policies, not code or regular expressions. A rule matches only when its match key matches and its condition holds.

POST /v1/role_rules/preview (scope policies:read) shows the role a sign-in would get, without signing anyone in. Send an organization, a connection and sample evidence: email and email_verified, idp_groups and idp_groups_verified, and scim_groups. Add an unsaved draft rule to see its effect before you save it.

The preview uses the same compiler, ordering and condition evaluator as sign-in. The verified domain comes from the organization’s verified domains, as it does at sign-in. The response gives role (null when no rule assigns one) and denied, which is true when a deny rule matched and the sign-in would be refused. Nothing is stored or audited, and the plan limits for saving rules do not apply to a draft.

Directory projection uses current SCIM memberships, exact organization-owned primary-email domains and a connection default only when exactly one connection is bound to the directory. No binding or several bindings skip the connection-default class.

Shared eligible evidence must produce the same role as sign-in. This does not imply universal parity: authenticated IdP group claims and OIDC email_verified are sign-in-only evidence and are unavailable to directory events. Ambiguous, unavailable or overflowing SCIM evidence also cannot establish a shared identity match.

Direct user changes recompute the role before their normal user event. Rule, membership, binding or domain changes trigger bounded worker reprojection, so cached directory roles can update eventually. A role-only change uses the normal user-updated event rather than a separate permission event.

Your application must decide which identity source controls its own permissions and revoke access when eligibility changes. See directory role mapping, sign-in policies and profiles.