Authentication Methods and Flows

Relevant source files

• api/commands/account.py
• api/controllers/console/apikey.py
• api/controllers/console/auth/data_source_bearer_auth.py
• api/controllers/console/auth/email_register.py
• api/controllers/console/auth/forgot_password.py
• api/controllers/console/auth/login.py
• api/controllers/console/auth/oauth.py
• api/controllers/console/auth/oauth_server.py
• api/controllers/console/extension.py
• api/controllers/console/workspace/__init__.py
• api/controllers/web/forgot_password.py
• api/controllers/web/login.py
• api/controllers/web/passport.py
• api/dify_app.py
• api/libs/login.py
• api/services/account_service.py
• api/services/advanced_prompt_template_service.py
• api/services/agent_service.py
• api/services/api_based_extension_service.py
• api/services/app_model_config_service.py
• api/services/auth/api_key_auth_service.py
• api/services/enterprise/account_deletion_sync.py
• api/services/saved_message_service.py
• api/services/webapp_auth_service.py
• api/services/workflow/workflow_converter.py
• api/tests/test_containers_integration_tests/controllers/console/app/test_message.py
• api/tests/test_containers_integration_tests/controllers/console/app/test_statistic.py
• api/tests/test_containers_integration_tests/controllers/console/auth/test_data_source_bearer_auth.py
• api/tests/test_containers_integration_tests/controllers/console/auth/test_oauth_server.py
• api/tests/test_containers_integration_tests/controllers/console/test_api_based_extension.py
• api/tests/test_containers_integration_tests/controllers/console/test_apikey.py
• api/tests/test_containers_integration_tests/services/auth/__init__.py
• api/tests/test_containers_integration_tests/services/auth/test_auth_integration.py
• api/tests/test_containers_integration_tests/services/enterprise/__init__.py
• api/tests/test_containers_integration_tests/services/enterprise/test_account_deletion_sync.py
• api/tests/test_containers_integration_tests/services/test_account_service.py
• api/tests/test_containers_integration_tests/services/test_api_based_extension_service.py
• api/tests/test_containers_integration_tests/services/test_model_load_balancing_service.py
• api/tests/unit_tests/controllers/console/auth/test_data_source_bearer_auth.py
• api/tests/unit_tests/controllers/console/auth/test_oauth_server.py
• api/tests/unit_tests/controllers/console/test_apikey.py
• api/tests/unit_tests/controllers/console/test_extension.py
• api/tests/unit_tests/controllers/console/test_workspace_account.py
• api/tests/unit_tests/libs/test_login.py
• api/tests/unit_tests/services/enterprise/test_account_deletion_sync.py
• api/tests/unit_tests/services/test_account_service.py
• packages/contracts/generated/api/console/oauth/types.gen.ts
• packages/contracts/generated/api/console/oauth/zod.gen.ts
• web/app/components/rag-pipeline/hooks/use-nodes-sync-draft.ts
• web/service/fetch.ts
• web/service/share.ts

Purpose and Scope

This page documents the authentication approaches employed in Dify, including email/password login, OAuth with GitHub and Google, passwordless email code login, and token management for session security. It covers backend implementations, data flow for each method, key classes and functions, and token lifecycle management (access, refresh, and CSRF tokens). The focus includes security measures like rate limiting and cryptographic validation employed across authentication flows.

---

Authentication Architecture Overview

Dify's authentication system encompasses multiple entry points and layers adapted for various client types (Console UI, WebApp, API). Central logic is implemented primarily in AccountService and coordinated through controller endpoints and utility classes.

Authentication Systems and Code Entity Mapping

Sources: api/services/account_service.py130-170 api/controllers/console/auth/login.py107-180 api/controllers/console/auth/oauth.py130-200 api/controllers/console/auth/forgot_password.py59-94 api/libs/passport.py1-50 api/services/webapp_auth_service.py1-100

---

Console Authentication Flows

Email and Password Authentication

The primary method for user authentication is via email and password.

Implementation Details

• AccountService.authenticate(email, password, session):
  • Retrieves user by email with case-insensitive fallback and verifies password using salt and hashed value.
  • Throws specific exceptions for not-found, banned accounts, or password mismatch.
• Passwords are hashed using PBKDF2-HMAC-SHA256 with per-user salt (libs.password.hash_password) and compared with compare_password [api/libs/password.py].
• On success, AccountService.login(account, session, ip_address):
  • Generates a JWT access token, refresh token, and CSRF token wrapped in TokenPair.
  • Stores refresh tokens in Redis for token management and invalidation.
  • Marks last active timestamp and logs IP address.
• Rate limiting implemented with Redis-backed RateLimiter to protect login endpoints from brute force api/services/account_service.py143-165
• The controller endpoint in LoginApi.post (console) handles user input, rate limiting, invitation validation, and triggers login api/controllers/console/auth/login.py117-181

Email/Password Login Sequence Diagram

Sources: api/services/account_service.py167-452 api/controllers/console/auth/login.py117-181 api/libs/password.py1-40 api/libs/helper.py333-370

---

OAuth Authentication (GitHub/Google)

OAuth 2.0 allows users to log in via external providers:

• OAuthLogin.get(provider) initiates OAuth by redirecting users to provider endpoints, passing optional invitation tokens, timezone, language, and redirect URL parameters api/controllers/console/auth/oauth.py153-170
• OAuthCallback.get(provider) handles OAuth provider callback:
  • Exchanges authorization code for provider access token.
  • Retrieves user info from provider.
  • Calls RegisterService.get_or_create_account_by_oauth to find or create a linked user account.
  • Issues session tokens via AccountService.login.
• Account linkage stored in AccountIntegrate model linking provider type and external identifiers.
• Rate limits and invitation verification enforced.

OAuth Flow Diagram

Sources: api/controllers/console/auth/oauth.py131-230 api/services/account_service.py370-402 api/libs/oauth.py1-150

---

Email Code Login (Passwordless Login)

Dify supports login via email codes (short, time-limited one-time tokens) for passwordless auth:

• Send Code:
  • EmailCodeLoginSendEmailApi endpoint sends a 6-digit code by email.
  • The code and an associated token are stored in Redis with 10-minute TTL using TokenManager.generate_token api/libs/helper.py350-400
• Verify Code:
  • EmailCodeLoginApi validates submitted code/token pairing.
  • On success, it fetches or creates the account and calls AccountService.login.
  • Rate limiting applies to reduce abuse api/controllers/console/auth/login.py215-313

Email Code Login Flow

Sources: api/controllers/console/auth/login.py215-313 api/libs/helper.py350-400 api/services/account_service.py760-810

---

Forgot Password Flow

Users who forget passwords can reset it via email verification:

• Send reset email (ForgotPasswordSendEmailApi POST /forgot-password):
  • Calls AccountService.send_reset_password_email to generate and email a reset token with a verification code.
• Verify code (ForgotPasswordCheckApi POST /forgot-password/validity):
  • Confirms the verification code corresponds to the token.
  • Revokes the initial token and issues a new one with a reset phase.
• Reset password (ForgotPasswordResetApi POST /forgot-password/resets):
  • Validates token and phase.
  • Hashes the new password and updates user's account.
  • Revokes reset password token post usage.

All steps enforce rate limiting and token validation for security.

Forgot Password Flow Diagram

Sources: api/controllers/console/auth/forgot_password.py59-192 api/services/account_service.py880-900 api/libs/password.py1-40

---

Token Management and Security

Tokens Managed

Token Type	Purpose	Storage	Example Lifetime
Access Token	Authenticate API requests	HTTP-only cookie	30 minutes (config)
Refresh Token	Renew Access Token	HTTP-only cookie + Redis	30 days (config)
CSRF Token	Prevent cross-site request forgery	Non-HTTP-only cookie	Session duration

• Refresh tokens stored with two Redis keys for lookup:
  • "refresh_token:{token}" → account id
  • "account_refresh_token:{account_id}" → refresh token string
• AccountService.login handles token creation and storing in Redis api/services/account_service.py135-452
• CSRF tokens generated by generate_csrf_token and validated on state-changing HTTP requests api/libs/token.py131-133 api/controllers/console/auth/login.py178

Session and Token Flow Diagram

Sources: api/services/account_service.py135-452 api/libs/token.py1-60 api/controllers/console/auth/login.py174-180

---

WebApp and API Authentication

WebApp Passport Flow

• Web Apps use PassportService for issuing and verifying JWT tokens representing end-user sessions.
• Authentication types handled:
  • Public Apps (no user auth)
  • External Enterprise Users
  • Internal Enterprise Users
• PassportResource (/passport) endpoint manages issuing tokens, requiring app code headers and optional user session parameters.
• Tokens include user and app identification and are validated via PassportService.verify.
• Supports anonymous and named users with session persistence in database EndUser model.

Sources: api/controllers/web/passport.py41-130 api/libs/passport.py1-50 api/services/webapp_auth_service.py1-100

API Key Authentication for Service APIs

• For programmatic access, API keys represent service identity tokens.
• API keys managed via ApiToken model with type annotations.
• Backend APIs validate incoming Bearer tokens against stored API keys.
• API keys are issued, listed, and revoked by tenant and resource-based APIs api/controllers/console/apikey.py50-190

---

Account Lifecycle and Security

Account Activation and Invitation

• New user onboarding often involves invitation tokens linked to workspaces and roles.
• Frontend screens in web/app/signin/invite-settings/page.tsx provide activation UI.
• The service revokes invitation tokens on acceptance, activates accounts, and associates them with tenants web/app/signin/invite-settings/page.tsx63-141 api/services/account_service.py98-117

Rate Limiting and Abuse Protection

• RateLimiter instances restrict request rates on fragile endpoints:
  • Login errors (max 5 attempts)
  • Password reset requests
  • Email code logins
• Implements fixed window rate limiting backed by Redis counters.
• IP-based sending limits guard email operations.
• These mechanisms protect authentication endpoints from brute force and enumeration attacks api/services/account_service.py148-165 api/libs/helper.py545-565 api/controllers/console/auth/forgot_password.py76-78

---

Summary

Dify provides robust multi-method authentication with:

• Conventional email/password sign-in secured by salted hashing.
• OAuth 2.0 integrations with GitHub and Google for federated identity.
• Passwordless email code logins for minimal-friction access.
• Secure token management with access, refresh, and CSRF tokens for session integrity.
• Password reset flows via time-limited email tokens.
• WebApp authentication serving end-users through JWT-based passports.
• API keys for service client authentication.
• Extensive rate limiting and invitation-based onboarding to secure account lifecycle.

These flows are implemented cohesively by AccountService, WebAppAuthService, token utilities in libs, and enforced via decorated REST endpoints.

End of Section 8.2: Authentication Methods and Flows

---

All citations:

• api/services/account_service.py130-900
• api/controllers/console/auth/login.py107-313
• api/controllers/console/auth/oauth.py130-230
• api/controllers/console/auth/forgot_password.py59-194
• api/libs/helper.py333-565
• api/libs/password.py1-40
• api/libs/passport.py1-50
• api/services/webapp_auth_service.py1-100
• api/controllers/web/passport.py41-130
• api/controllers/console/apikey.py50-190
• web/app/signin/invite-settings/page.tsx63-141
• api/models/account.py35-46