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

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	Default tenant exists	Full JWT	Configurable (default: 1h)
First Login	MustChangePassword = true	Temporary	10 minutes
Switch Tenant	No default tenant	Pre-Auth	5 minutes
Refresh Token	Access token expired	New JWT	Resets expiration
Logout	User/admin action	N/A	Immediate invalidation

Common Components

All flows share these core components:

Security Service

Handles:

• Password verification (BCrypt/Argon2)
• Password strength validation
• Failed attempt tracking
• Account lockout

JWT Service

Generates and validates:

• Access tokens (short-lived)
• Refresh tokens (long-lived)
• Temporary tokens (purpose-specific)
• Pre-auth tokens (tenant selection)

Token Claims

Standard JWT claims included in access tokens:

{
  "sub": "user-id-guid",
  "email": "user@example.com",
  "tenant_id": "tenant-id-guid",
  "tenant_name": "Acme Corp",
  "roles": ["Admin", "User"],
  "permissions": ["users:read", "users:write"],
  "token_version": 1,
  "iat": 1706882400,
  "exp": 1706886000
}

Additional Flows

More authentication flows coming soon:

• Reset Password - Self-service password recovery
• Social Login - OAuth/OIDC with Auth0
• API Key Authentication - Service-to-service auth
• Two-Factor Authentication - TOTP/SMS verification