OAuth Login Flow#

Dify supports OAuth login via GitHub and Google. The implementation lives in api/controllers/console/auth/oauth.py and the OAuth client library in api/libs/oauth.py 1.

The flow has two endpoints, both under /console/api/oauth/:

Both endpoints are protected by two decorators:

• @setup_required — ensures system setup is complete
• @social_oauth_login_enabled — ensures social OAuth login is enabled in system config

Provider instances are constructed in ext_application_services.py via application_services.oauth_providers, with callback URIs pointed at CONSOLE_API_URL + /console/api/oauth/authorize/<provider>.

State Management Across the Provider Redirect#

Because the provider redirect breaks the HTTP session, four pieces of context are serialized into the OAuth state parameter and recovered on callback:

These fields are defined in OAuthState (a TypedDict with total=False, so all fields are optional).

Encoding (encode_oauth_state()): the dict is serialized as compact JSON, UTF-8 encoded, then base64url-encoded with padding stripped. If all fields are absent, None is returned and no state parameter is added to the authorization URL.

Decoding (decode_oauth_state()): padding is restored, then the process is reversed. Any decoding or validation error silently returns an empty dict.

On the login side, OAuthLogin.get() reads the four query params, validates timezone and language, and passes them into get_authorization_url() 2. GitHub requests the user:email scope 3; Google requests openid email 4.

On the callback side, OAuthCallback.get() calls decode_oauth_state() to recover all four fields before processing the authorization code 5.

Redirect URL Validation#

After a successful login, the user is redirected to the URL recovered from state. Because the OAuth callback runs on the API origin (CONSOLE_API_URL) while the user's browser belongs to the web origin (CONSOLE_WEB_URL), redirect URLs must be validated carefully.

_safe_console_redirect_target() applies these rules:

1. No URL supplied → fall back to CONSOLE_WEB_URL.
2. Relative path (no scheme, no authority, doesn't start with //) → pass through as-is. The browser resolves it against the web origin.
3. Absolute URL, same origin as CONSOLE_WEB_URL (same scheme + hostname + port via _url_origin()) → allowed.
4. Anything else (cross-origin, protocol-relative, malformed port) → fall back to CONSOLE_WEB_URL.

This design supports split-domain deployments (e.g., api.example.com / app.example.com) — a relative redirect_url like /apps/123 is passed through and the browser appends it to the console web origin automatically. 6

The oauth_new_user flag is appended as a query parameter before the final redirect so the frontend can show first-time-user onboarding 7.

Callback Account Resolution & Session Creation#

Inside OAuthCallback.get(), authorization is completed by calling AccountOAuthService.complete_authorization(), which returns AccountSessionTokens or raises specific error types:

1. Account resolution: The service resolves the account by provider OpenID or email, or registers a new one. timezone and language from state are applied to new accounts.
2. Invite path: If a valid invite_token is present, the identity is linked to the invited account and the user is sent to /signin/invite-settings. This flow is handled through OAuthInvitationResult.
3. Standard path: The service returns an OAuthSignInResult containing AccountSessionTokens and an oauth_new_user flag.
4. Session: _redirect_with_console_session() takes AccountSessionTokens instead of an Account object, and attaches access, refresh, and CSRF token cookies to the redirect response.

Error cases are handled through specific exception types (OAuthAccountBannedError, OAuthSeatsLimitExceededError, OAuthRegistrationError, OAuthWorkspaceCreationNotAllowedError, InvalidOAuthInvitationError, OAuthInvitationAccountMismatchError) that all redirect to CONSOLE_WEB_URL/signin?message=....

Key Files#