Skip to content

Admin roles and privileged access (Authifi service)

Authifi's admin privilege model has three sources:

  • Super Administrators (platform-wide)
  • Tenant Administrators (tenant-wide)
  • Delegated Admins (users granted elevated admin::* permissions)

See Super Admin Access for the operation inventory and Privileged Access Summary for the privileged-access reference.

Terminology Note

In user-facing documentation, the platform-wide admin role is called "Super Administrator" to distinguish it from infrastructure system administrators who manage servers and operating systems.

Table of contents

Super Administrators

Super Administrators have platform-wide privileged access across all tenants.

Authifi determines Super Administrator status from membership in the designated Super Administrator group, configured through auth.defaults.systemAdminGroup. When a user authenticates, Authifi checks group membership and sets an internal authorization flag.

Super Administrators can perform platform-wide privileged operations. Some operations still block them, including protections for config-defined Super Administrators. See Super Admin Access for the full list of SA-only and SA-or-scope operations.

Tenant Administrators

Tenant Administrators have full administrative access within a tenant for most tenant-scoped APIs.

Authifi determines Tenant Administrator status from membership in the tenant's admin group, configured through auth.defaults.adminGroup.

Within a tenant, Tenant Administrators can perform tenant admin actions unless an operation is restricted to Super Administrators or an elevated admin scope. Tenant Administrator status also supports cross-tenant authorization through "trusted tenants" delegation (see below).

Delegated Admins (admin scopes)

Delegated Admins are users who are not Super Administrators but have elevated permissions through admin::* scopes.

Authifi reads these scopes from the user's permissions and roles at request time. RBAC configuration assigns the scopes.

Naming Convention: By convention, delegated admin permissions use the admin:: prefix (e.g., admin::mfa:reset). However, this naming convention alone does not make an entity privileged; the isPrivileged flag must be set on the permission, role, or group. See Privileged Access Summary for details.

These scopes commonly grant access to operations that would otherwise be Super-Administrator-only or to edits on privileged entities. Examples include:

  • admin::admin-permissions:edit (privileged RBAC entities: admin groups, roles, and permissions)
  • admin::system-templates:edit (system templates)
  • admin::trusted-provider:edit (trusted or verified IdP restrictions and some IdP type restrictions)
  • admin::provider-scripts:edit (IdP claims mapping scripts)
  • admin::access-scripts:edit and admin::clients:edit (client scripts and updates)
  • admin::view:idp-secrets (unmask IdP secrets in responses)
  • admin::user-ssh-secret:edit (SSH key operations)

For the exact places these are enforced, see the relevant sections in Super Admin Access.

How these roles are enforced

1) API-level authorization checks

  • Many API endpoints explicitly check Super Administrator status, Tenant Administrator status, and/or specific admin::* permissions.
  • Example patterns:
    • SA-only: Request is rejected unless the user is a Super Administrator
    • SA-or-scope: Super Administrator is allowed, otherwise requires an admin::* scope
    • SA-or-tenant-admin: Super Administrator is allowed, otherwise allows Tenant Administrators

2) Admin override for scope failures

  • A large portion of /auth/admin/tenants/{tenantId}/... endpoints are primarily protected by OAuth scopes.
  • When authentication fails due to Insufficient scope, the authorization system can allow certain admin users to proceed:
    • Tenant Administrator of the target tenant ({tenantId}), or
    • Tenant Administrator of the original token tenant and the target tenant is a trusted tenant.
  • This bypass is not applied to Client Credentials tokens.

This is why many "admin" APIs don't contain an explicit "Tenant Administrator required" check: Tenant Administrators may still be able to use them even when scopes are missing.

3) Trusted tenants delegation

  • The service supports delegating admin access across tenants using "trusted tenants" relationships.
  • See Trusted Tenant Implementation for details.

Common patterns and examples

  • Tenant Administrators can do "anything in the tenant", except what is SA-only or scope-gated

    • Practically, Tenant Administrators can perform most tenant administration, but some operations remain reserved for:
      • Super Administrators (SA-only), or
      • Delegated Admins (SA-or-scope), especially around privileged RBAC entities and sensitive scripting/secrets.

  • Privileged RBAC entities (admin groups/roles/permissions)

    • Commonly enforced as SA-or-scope (admin::admin-permissions:edit).

  • Trusted identity provider controls

    • Commonly enforced as SA-or-scope (admin::trusted-provider:edit), with additional Tenant-Administrator-specific logic for some IdP fields.

  • Monitoring / reporting APIs

    • Often scope-gated (e.g. audit/log scopes, protected health scope), with Tenant Administrator access potentially enabled via the admin override mechanism.

Securing admin accounts (best practices)

  • Prefer "trusted" identity providers for admin identities

    • Restrict admin sign-in to identity providers that are verified/trusted and centrally managed.
    • Avoid granting admin access to accounts authenticated via ad-hoc or weakly verified providers.

  • Enforce MFA for all admin-capable accounts

    • Require phishing-resistant MFA where possible (e.g. WebAuthn/FIDO2), at minimum TOTP.
    • Ensure "break-glass" admin accounts are also MFA-protected (with tightly controlled recovery).

  • Apply least privilege and minimize standing access

    • Keep the number of Super Administrators small.
    • Prefer delegated admin access (admin::*) over Super Administrator where possible.
    • Remove unused admin scopes; time-bound or approval-gated elevation where feasible.

  • Separate admin and day-to-day user accounts

    • Use dedicated admin accounts for privileged actions.
    • Do not browse email/drive/chat from privileged accounts; reduce exposure to phishing and token theft.

  • Review admin access regularly

    • Periodically review:
      • Super Administrator assignments,
      • Tenant Administrator group membership,
      • users holding admin::* privileges,
      • "trusted tenant" delegations.
    • Treat emergency additions as temporary and require follow-up removal/review.

  • Monitor and audit admin activity

    • Audit logs should be routinely reviewed for privileged actions (RBAC changes, secrets access, IdP changes, template/script changes, tenant exports).
    • Alert on anomalous admin behavior (new admin grants, repeated denied attempts, unusual login patterns, cross-tenant access via delegation).

  • Harden sessions and tokens

    • Shorter session lifetimes for admin contexts; revoke sessions promptly on role removal.
    • Rotate credentials/secrets used by admin automation; avoid long-lived tokens.

  • Have an incident-ready process

    • Document how to revoke admin access quickly (including removing scopes, disabling accounts, revoking sessions).
    • Validate restore/recovery paths for audit logs and configuration (and restrict restore operations appropriately).