Authentication Flows

This section documents the various authentication flows in GrydAuth. Each flow includes detailed sequence diagrams showing the interaction between components.

Overview

GrydAuth supports multiple authentication scenarios to handle different user states and requirements:

🔐

Standard Login

Basic authentication flow with default tenant. The most common login scenario.

Default Tenant

🔑

First Login

Login flow when password change is required (first login or forced reset).

Password Change

🏢

Switch Tenant

Login flow when user has no default tenant and must select one.

Multi-Tenant

🔄

Refresh Token

Renew expired access tokens without re-entering credentials.

Token Management

🚪

Logout

Invalidate tokens and terminate sessions securely.

Session End

🛡️

MFA Challenge

Second-factor step-up (TOTP / recovery code) when a tenant's MFA policy requires it.

Step-Up

Flow Decision Tree

The following diagram shows how GrydAuth determines which flow to execute:

100% 💡 Use Ctrl + Scroll para zoom | Arraste para navegar

Quick Reference

Flow	Trigger	Token Type	Expiration
Standard Login	Tenant resolved (single/preferred/default)	Tenant (access) token	JwtSettings:ExpirationMinutes — default 10, range 1–15
First Login	IsFirstLogin or MustChangePassword	Global Token	2 minutes (hardcoded, single-use)
Switch Tenant	Multiple tenants, no default/preferred match	Global Token	2 minutes (hardcoded, single-use)
MFA Challenge	Tenant MFA policy requires it	MFA-pending token	Short-lived, no refresh token
Refresh Token	Access token expired	New Tenant token	Resets expiration; refresh token rotates (7-day default)
Logout	User action	N/A	Immediate, global (all sessions)

Common Components

All flows share these core components:

Security Service

Handles:

• Password verification (Argon2id)
• Password strength validation
• Failed attempt tracking
• Account lockout

JWT Service

Generates and validates:

• Access tokens (short-lived)
• Refresh tokens (long-lived)
• Global tokens (tenant selection / first login)

Token Claims

Every token carries exactly one token_type claim (access / refresh / global / mfa_pending) — see canonical token type. Access tokens additionally carry:

{
  "sub": "user-id-guid",
  "token_type": "access",
  "tenant_id": "tenant-id-guid",
  "tenant_name": "Acme Corp",
  "role": ["Admin", "User"],
  "permission": ["users:read", "users:write"],
  "token_version": 1,
  "group_id": "parent-group-tenant-id",
  "group_name": "Holding Sul",
  "iat": 1751462400,
  "exp": 1751463000
}

role / permission, not roles / permissions

The underlying JWT claim types are singular (role, permission), repeated once per value. group_id/group_name only appear for child tenants in a hierarchical/group tenant.

Additional Flows

Already implemented, documented separately:

• Multi-Factor Authentication - TOTP + recovery codes, per-tenant step-up policy
• Reset Password - Self-service password recovery (request-password-reset / reset-password)
• Social Login - OAuth via POST /api/v1/auth/social-login

Not yet implemented:

• WebAuthn / Passkeys (FIDO2) - reserved MFA factor type, planned for a future release
• API Key Authentication - Service-to-service auth