Key Concepts

This page defines the core concepts in Auris. Each term is explained in the context of how Auris uses it — not as a general industry definition. If you are new to identity and access management, reading this page before the guides will make the rest of the documentation easier to follow.

Tenant

An isolated environment in Auris. Every configuration, user, application, role, and policy belongs to a tenant. Tenants cannot share data — a user account in tenant A cannot authenticate against an application registered in tenant B.

Under the hood, each tenant maps to a Keycloak realm. Keycloak enforces realm isolation at the identity store level.

In API requests, the active tenant is identified by the x-tenant header. SDKs set this automatically based on the domain you configure at initialization.

Single-tenant deployments use a single tenant (usually named 'default'). Multi-tenant SaaS products create one tenant per customer organization — this is different from Auris’s own Organization concept, which is a B2B grouping within a single Auris tenant.

Application

A client registered with Auris. Every piece of software that uses Auris authentication must be registered as an application. An application has:

• A unique Client ID (public identifier, safe to embed in browser code)
• An optional Client Secret (private, only for server-side M2M clients)
• A list of allowed Redirect URIs (enforced exactly — no wildcards)
• An Application Type that determines which OAuth 2.0 flows are available

Application types:

Applications can have Custom JWT Claims configured — extra data embedded in access tokens issued to that application without requiring an additional API call.

User

An identity managed by Auris within a tenant. Users have:

• A unique ID (sub claim in JWTs)
• An email address (primary identifier)
• An optional username, first name, last name, and phone number
• One or more roles (via role assignments)
• Optional permission overrides (ALLOW or DENY on specific permissions, independent of roles)
• One or more authentication methods (password, social accounts, passkeys, etc.)
• Optional 2FA configurations (TOTP, SMS, WebAuthn)

Users are stored in Keycloak (for authentication) and mirrored in the Auris Prisma database (for RBAC metadata, preferences, and extended profile data).

Role

A named collection of permissions. Users are assigned roles; roles define what those users are allowed to do. Roles are scoped to a tenant.

A user can have multiple roles. When checking a permission, all roles are evaluated — if any role grants ALLOW and none grant DENY, the permission is granted.

Roles can be hierarchical (via INHERIT permission values). A base user role might grant read access to most resources, while an admin role adds write access on top.

Roles can also be application-scoped — the same user can have different roles (and therefore different permissions) in different applications registered with Auris. This is useful when your platform hosts multiple products with different access models.

Permission

A capability represented as an action:resource string. Examples:

• manage:users — full CRUD access to users
• view:invoices — read access to invoices
• approve:expenses — ability to approve expense reports
• create:tickets — ability to create support tickets
• export:payments — ability to export payment data

Permissions have tri-state values:

DENY always wins over ALLOW. If a user has role A granting ALLOW on a permission and role B granting DENY on the same permission, access is denied.

User permission overrides can set an individual user’s permission to ALLOW or DENY regardless of their roles. This is used for exceptional cases (e.g., a temporary permission grant during an audit period).

Access Token

A short-lived JWT (JSON Web Token) that proves the user’s identity and carries their permissions. Access tokens are:

• Signed with RS256 (RSA + SHA-256) using Auris’s private key
• Verified by any service with access to Auris’s public JWKS endpoint
• Sent in the Authorization: Bearer <token> HTTP header to protected APIs
• Short-lived (default: 15 minutes — configurable per tenant)

The access token payload includes:

{
  "sub": "user-uuid",
  "email": "[email protected]",
  "roles": ["admin", "billing_manager"],
  "aud": "your-client-id",
  "iss": "https://auth.yourdomain.com",
  "exp": 1700000000,
  "iat": 1699999100
}

Custom claims configured for an application are also included in the payload.

Refresh Token

A long-lived opaque token used to obtain new access tokens after the current one expires. Refresh tokens are:

• Opaque — they are random strings, not JWTs. They carry no information themselves.
• Long-lived (default: 7 days — configurable per tenant)
• Single-use — each time a refresh token is used to obtain a new access token, Auris invalidates the old refresh token and issues a new one (refresh token rotation). This limits the window of exposure if a refresh token is stolen.
• Stored securely — SDKs store refresh tokens in httpOnly cookies (server-side) or encrypted storage (client-side). Never store them in localStorage.

The access token refresh flow is handled automatically by all Auris SDKs. You do not need to implement it manually.

ID Token

An OpenID Connect (OIDC) token containing the authenticated user’s profile information. ID tokens are:

• JWTs, signed with RS256 like access tokens
• Issued alongside the access token during the authorization code exchange
• Intended for the client application to display user information (name, email, avatar)
• Not sent to APIs — APIs should use the access token, not the ID token

The ID token payload follows OIDC standard claims:

{
  "sub": "user-uuid",
  "email": "[email protected]",
  "name": "Alice Smith",
  "given_name": "Alice",
  "family_name": "Smith",
  "picture": "https://...",
  "phone_number": "+39 123 456 7890",
  "locale": "en",
  "iss": "https://auth.yourdomain.com",
  "aud": "your-client-id",
  "exp": 1700000000
}

PKCE

Proof Key for Code Exchange (RFC 7636). A security extension to the OAuth 2.0 Authorization Code flow that prevents authorization code interception attacks.

Without PKCE, if an attacker intercepts the authorization code (e.g., via a malicious redirect), they could exchange it for tokens. PKCE prevents this by requiring the client to prove it initiated the flow.

How it works:

1. Before redirecting to login, the client generates a random code_verifier and computes code_challenge = base64url(SHA256(code_verifier)).
2. The code_challenge is sent with the authorization request.
3. After authentication, Auris redirects back with the authorization code.
4. When exchanging the code for tokens, the client sends the original code_verifier.
5. Auris recomputes the challenge and verifies it matches — proving the code was obtained by the same client that initiated the flow.

Auris enforces S256 (SHA-256 hashing) — plain PKCE is not accepted. All Auris SDKs handle PKCE generation and verification automatically. You never need to implement this yourself.

RBAC

Role-Based Access Control. The permission model where:

• Users are assigned roles
• Roles have permissions
• Permissions gate access to actions and resources

RBAC answers the question: “What can this user’s role do?” It is appropriate for most access control scenarios — protecting API routes, showing/hiding UI elements, and gating business operations.

In Auris, RBAC is implemented as Layer 2 of the three-layer authorization model. The requirePermission(req, 'action:resource') function on API routes and the useRequirePermission('action:resource') hook in UI components are the primary enforcement points.

FGA

Fine-Grained Authorization. A Zanzibar-style relationship-based access control system for object-level permissions. FGA answers the question: “Can this specific user access this specific object?”

Where RBAC says “users with the editor role can edit documents,” FGA says “user Alice can edit document 42, user Bob can view document 42, and user Charlie has no access to document 42.”

FGA uses three core concepts:

• Authorization Model — a schema defining object types and relations (e.g., document has relations owner, editor, viewer)
• Relationship Tuples — facts stored in the database (e.g., document:42#editor@user:alice)
• Check — a recursive query that determines whether a subject has a relation to an object by following the model’s rewrite rules

FGA is implemented as Layer 3 of the authorization model and replaces the Ory Keto integration when enabled (FGA_ENGINE_ENABLED=true).

SSO

Single Sign-On. A mechanism that lets users authenticate once with an identity provider (IdP) and automatically gain access to multiple applications without re-entering credentials.

Auris supports two SSO protocols:

• SAML 2.0 — XML-based protocol widely used by enterprise IdPs (Okta, Azure AD, ADFS, PingIdentity). Auris acts as the Service Provider (SP); the customer’s IdP is the identity source.
• OIDC (OpenID Connect) — Modern JSON-based protocol. Used by Google Workspace, Microsoft Entra ID, and others.

SSO connections are configured per Organization in Auris. When a user’s email domain matches a configured SSO connection, Auris automatically redirects them to their organization’s IdP for authentication (domain-based SSO detection).

SCIM

System for Cross-domain Identity Management (RFC 7643/7644). A standard protocol for automated user provisioning and deprovisioning from an identity provider into downstream applications.

With SCIM enabled:

• When HR creates a new employee in Okta or Azure AD, that user is automatically provisioned in Auris.
• When an employee is terminated, their Auris account is automatically deprovisioned.
• Group memberships can be synced to Auris roles.

Auris exposes a SCIM 2.0 API endpoint (/api/scim/v2/) that is compatible with major identity providers. SCIM connections are configured per tenant in the Auris Console under Settings > Provisioning.

M2M

Machine-to-Machine. Server-to-server authentication where no human user is involved. Examples include background jobs, cron scripts, microservices calling each other, and CLI tools.

M2M authentication uses the OAuth 2.0 Client Credentials grant:

1. The server sends its client_id and client_secret to POST /api/auth/token.
2. Auris validates the credentials and issues an access token with a type: 'm2m' claim.
3. The server uses this token to call protected APIs.

M2M tokens are scoped — you define which permissions (scopes) the M2M client is allowed to request. This limits the blast radius if a client secret is compromised.

MFA

Multi-Factor Authentication. Requiring users to prove their identity with more than one factor. Auris supports three MFA methods:

MFA can be enforced globally (all users), per-role, or adaptively based on risk scoring. Adaptive MFA automatically escalates to additional factors when risk signals are detected (new device, new country, impossible travel, VPN usage) — without requiring all users to use MFA on every login.

Actions

Custom JavaScript functions that run during authentication flows in a sandboxed environment. Actions let you extend Auris’s behavior without forking the platform.

Use cases:

• Deny login to users who have not accepted the latest terms of service
• Add a custom claim to the access token based on a database lookup
• Send a Slack notification when a specific user logs in
• Enforce login-time checks (account standing, subscription status, device compliance)

Actions execute synchronously in the auth flow. If an action throws an error or explicitly denies the request, the authentication is blocked. Actions have a configurable timeout (default: 5 seconds).

For visual editing of complex action logic, the Blueprint Editor provides a drag-and-drop node-based interface (similar to Unreal Engine Blueprints) that generates the underlying action code.

Organization

A B2B entity within a tenant. Organizations are used when you build a product that you sell to other businesses — each of your customers is modeled as an Organization.

Each organization has:

• A roster of members with roles (OWNER, ADMIN, MEMBER, VIEWER)
• An optional Enterprise SSO connection (SAML or OIDC) scoped to that organization
• Invitation workflows — send email invitations to new members (token-based, 7-day expiry)
• Domain-based SSO detection — when a user’s email domain matches the organization’s SSO connection, Auris automatically redirects them to their IdP

Organizations are different from tenants. A tenant is the top-level isolation boundary; an organization is a grouping of users within a single tenant.

Custom Domain

A feature that lets you serve the Auris-hosted login pages from your own domain (e.g., auth.yourcompany.com) instead of the default Auris URL. This provides a white-label authentication experience.

Custom domains require DNS verification (CNAME or TXT record). Auris handles SSL certificate provisioning automatically once the DNS record is verified.

Webhook

An HTTP callback that Auris sends to your server when specific events occur. Webhooks are signed with HMAC-SHA256 using a whsec_-prefixed secret, allowing you to verify that the request originated from Auris.

Over 180 event types are supported, grouped into 18 categories (authentication, users, organizations, invoices, tickets, chat, CRM, and more). Delivery failures are retried with exponential backoff.

Blueprint

A visual node editor for building Actions logic without writing JavaScript directly. The Blueprint Editor uses a Zanzibar-inspired drag-and-drop interface with typed nodes:

• Trigger Node — the auth event that initiates the flow
• Condition Nodes — if/then logic (field comparisons, operators)
• Logic Gate Nodes — AND/OR combinators
• Action Nodes — operations to perform (deny, set claims, set metadata, log)

The Blueprint serializes to a JSON rule structure that the Actions engine evaluates at runtime. You can switch between Blueprint view and raw code view on the same action.

OIDC Discovery

The standard mechanism for OIDC clients to discover an identity provider’s configuration. Auris publishes its OIDC Discovery document at:

GET /.well-known/openid-configuration

This document lists the authorization endpoint, token endpoint, JWKS URI, supported response types, scopes, and signing algorithms. Standard OAuth 2.0 and OIDC libraries can auto-configure from this URL — you only need to provide the Auris domain.