OAuth2 and OIDC Providers
Relevant source files
The following files were used as context for generating this wiki page:
FLEXT Auth provides a robust framework for integrating enterprise-grade authentication through OAuth2 and OpenID Connect (OIDC) protocols. These providers enable the system to act as a client or a relay for identity federation, allowing users to authenticate via external identity providers (IdPs) while maintaining local authorization and session management.
The architecture relies on a modular provider system where FlextAuthOAuth2Provider handles standard token-based flows, and FlextAuthOidcProvider extends this functionality to support identity-layer features such as ID Tokens and UserInfo endpoints. The system uses a lazy-loading mechanism to ensure high performance by only loading provider logic when required during the authentication lifecycle.
Sources: src/flext_auth/providers/__init__.py:46-70, src/flext_auth/history.json:constants.py:228-251
Provider Architecture and Components
The provider system is organized into specialized components that handle configuration, token management, and introspection. This separation of concerns ensures that the core authentication logic remains decoupled from specific protocol implementations.
Component Map
- Config Management:
FlextAuthOAuth2Configmanages endpoint discovery and client credentials. - Token Handling:
FlextAuthOAuth2Tokensmanages the lifecycle of access, refresh, and bearer tokens. - Introspection:
FlextAuthOAuth2Introspectionprovides mechanisms to validate active tokens against the authorization server. - Protocol Extensions:
FlextAuthOidcProviderbuilds upon OAuth2 to add OpenID Connect capabilities.
Sources: src/flext_auth/providers/__init__.py:46-51, src/flext_auth/providers/__init__.py:55-58
Class Hierarchy
The following diagram illustrates the relationship between the base OAuth2 provider and the specialized OIDC implementation.
The diagram shows the inheritance structure where OIDC extends OAuth2, both fulfilling RFC standards.
Sources: src/flext_auth/providers/__init__.py:52-60
OAuth2 Configuration and Supported Flows
FLEXT Auth defines strict constants for OAuth2 operations to ensure compliance with the specification. These include support for multiple grant types and secure defaults such as PKCE (Proof Key for Code Exchange).
Supported Grant Flows
The system supports three primary OAuth2 flows:
- Authorization Code: The default flow for most web applications, supporting PKCE for enhanced security.
- Client Credentials: Used for machine-to-machine (M2M) authentication where no user is present.
- Implicit: A legacy flow supported for compatibility but not recommended for new integrations.
Sources: src/flext_auth/history.json:constants.py:233-238
Default Settings
| Parameter | Default Value | Description |
|---|---|---|
SCOPE_DEFAULT | "openid profile email" | Standard OIDC scopes requested by default. |
FLOW_DEFAULT | "authorization_code" | The preferred secure flow for user authentication. |
USE_PKCE_DEFAULT | True | Enforcement of Proof Key for Code Exchange. |
TOKEN_ENDPOINT_AUTH_METHOD_DEFAULT | "client_secret_basic" | Default method for authenticating the client at the token endpoint. |
Sources: src/flext_auth/history.json:constants.py:228-251
Authentication Lifecycle Flow
The authentication flow involves exchanging authorization codes for tokens and optionally introspecting those tokens to ensure they remain valid.
This flow represents the standard Authorization Code flow with PKCE as configured in the provider constants.
Sources: src/flext_auth/history.json:constants.py:233-241, src/flext_auth/providers/oauth2_introspection.py
Token Endpoint Authentication Methods
FLEXT Auth supports several methods for client authentication as defined in RFC 6749 and related OIDC specifications.
| Method | Description |
|---|---|
client_secret_basic | Client ID and Secret sent via HTTP Basic Auth header. |
client_secret_post | Client ID and Secret sent in the request body. |
none | Used for public clients (e.g., mobile apps) relying solely on PKCE. |
Sources: src/flext_auth/history.json:constants.py:243-247
OpenID Connect (OIDC) Enhancements
The OIDC provider layer extends the standard OAuth2 flow by introducing identity-specific features. This includes the handling of the id_token, which is a JWT containing claims about the authenticated user.
OIDC Specific Constants
OIDC integration in FLEXT Auth defaults to a specific set of scopes to ensure identity data is retrieved correctly.
- Default Scopes:
openid,profile,email. - Identity Handling: The provider interacts with the
identity_managerto link the external sub (subject) claim to a localAuthIdentity.
Sources: src/flext_auth/history.json:constants.py:231, examples/comprehensive_demo_03.py:75-80
Implementation Details
The providers package uses a lazy-loading map (_LAZY_IMPORTS) to optimize the import chain. This prevents the overhead of loading complex crypto libraries until an OAuth2 or OIDC operation is actually invoked.
# Example of the lazy-loading structure used for OAuth2/OIDC
_LAZY_IMPORTS = build_lazy_import_map(
{
".oauth2": ("FlextAuthOAuth2Provider",),
".oauth2_config": ("FlextAuthOAuth2Config",),
".oauth2_introspection": ("FlextAuthOAuth2Introspection",),
".oidc": ("FlextAuthOidcProvider",),
}
)
Sources: src/flext_auth/providers/__init__.py:55-60
Conclusion
OAuth2 and OIDC Providers in FLEXT Auth provide the necessary infrastructure for secure, protocol-compliant identity federation. By implementing secure defaults like PKCE and supporting multiple grant flows, the system ensures enterprise-level security. The modular design, separating config, tokens, and introspection, allows for easy extension and maintenance across different external identity providers.