Core Concepts

Tenants

A tenant is an isolated authentication environment. Each tenant has its own:

Users, roles, permissions, groups
RSA keypair for JWT signing
Branding and login page configuration
SSO connections (SAML, OIDC, LDAP)
Billing plan and usage limits

Your SaaS customers each get their own tenant. Data never leaks between tenants.

Your SaaS → Tenant "acme" → Users, roles, SSO for Acme Corp
          → Tenant "globex" → Users, roles, SSO for Globex Inc

Applications

An application is an OAuth 2.0 client registered in a tenant. Types:

Type	Auth Method	Use Case
Web	client_secret (confidential)	Server-rendered apps
SPA	PKCE (public)	React, Vue, Svelte apps
Native	PKCE (public)	Mobile, desktop apps
M2M	client_credentials	Service-to-service

Each application gets a client_id and (for confidential apps) a client_secret.

Users

End users within a tenant. A user has:

Email (unique per tenant), password hash
Profile: name, picture, metadata (JSON)
Roles and permissions (direct or via groups)
MFA factors (TOTP)
Organization memberships
Login history, session tracking

Roles & Permissions

Permissions are fine-grained actions: read:users, write:orders, admin:billing.

Roles are collections of permissions: “admin” has read:users + write:users + admin:billing.

Roles can be assigned to users directly or via groups.

User → Role "editor" → Permissions: read:articles, write:articles
User → Group "engineering" → Role "developer" → Permissions: read:code, deploy:staging

Groups

Azure AD-like security groups. Users belong to groups, groups have roles. Effective permissions = user’s direct roles + all group roles merged.

Groups appear in the JWT groups claim and can be used in eBPF access policies.

Organizations

Multi-tenant within a tenant. For B2B SaaS where your customers have sub-organizations:

Tenant "acme" → Org "engineering" → Members with org-specific roles
              → Org "sales" → Different members, different branding

Each org can override: branding, auth settings (password rules, MFA policy, session TTL), default SSO connection.

Connections

Authentication methods configured per tenant:

Strategy	Protocol	Example
`email`	Password	Built-in email/password
`google`	OAuth 2.0	Google social login
`github`	OAuth 2.0	GitHub social login
`saml`	SAML 2.0	Okta, OneLogin, Azure AD
`oidc`	OpenID Connect	Any OIDC provider
`ldap`	LDAP/AD	On-prem Active Directory

Domain routing: *@acme.com → Okta SAML, *@partner.io → Azure AD OIDC.

JWT Claims

Every access token contains:

{
  "sub": "user-id",
  "iss": "https://tenant.authfi.app",
  "aud": "your-client-id",
  "azp": "your-client-id",
  "email": "user@example.com",
  "email_verified": true,
  "tenant_id": "tenant-uuid",
  "org_id": "org-uuid",
  "roles": ["admin", "editor"],
  "permissions": ["read:users", "write:articles"],
  "groups": ["engineering", "devops"],
  "mfa_verified": true,
  "exp": 1711234567,
  "iat": 1711230967
}

SDKs verify this token on every request using cached JWKS public keys.