How minvws/nl-rdo-max works
• Core Application – Represent the MAX core engine (started through app/application.py and app/main.py) that orchestrates the authentication flow.
• Dependency Injection & Configuration – Include the “dependency_injection” module which manages the configuration, service initialization, and encryption services. Note the separation of configuration (config.py) and container management (container.py).
• Service Layer – Represent the various “services” modules. This includes authentication handlers (loginhandler submodule with multiple authentication_handler implementations), token factories (response_factory), encryption services (jwe, jwt, RSA, xed25519, etc.), and SAML identity provider services.
• External Providers – Identify the providers in “providers” which are concrete implementations for different authentication protocols (e.g., oidc_provider, saml_provider, digid_mock_provider, pyop_provider). Also capture that MAX interacts with external systems like DigiD, TVS, and the nl-uzi-login-controller.
• Storage & Caching – Include the storage system (especially under app/storage/redis) which uses Redis for authentication caching. This is key for tracking states (like random state and user limits).
• Encryption/Key Management – Outline the “services/encryption” module that handles JWT signing, JWE encryption, and key generation/management as described in the README. Include a note on the presence of both Ed25519 and X25519 keys.
• Mock Environment – Since the system supports a DigiD mock for development (if not in production) and supports a “mock” login method, include a component that represents this “DigiD Mock” flow.
• Rate Limiter – Represent the rate limiter mechanism found in app/misc/rate_limiter.py that can route traffic to a secondary (“overflow”) identity provider when necessary.
• External and Third-party Integration – Optionally include external systems like the NL UZI Login Controller, a separate identity provider’s backends, and any external registers from which BSN properties are retrieved.
Relationships and Interactions
• Flow from the authentication endpoints (in routers) to appropriate service handlers (from loginhandler and auth handlers) that engage the providers.
• That after user authentication, MAX retrieves or validates tokens either by contacting an external TVS or handling SAML flows internally.
• Data flow between the authentication services, the encryption layer (for signing or encrypting JWT token data), and the storage/cache (Redis).
• If desired, include Docker/Container references (e.g., through docker-compose.yml) as a surrounding infrastructure context, noting that these containers are meant for development.
Architectural Patterns & Design Principles
• The project follows a modular, layered architecture where responsibilities are clearly separated (e.g., routing, service logic, data models, and providers).
• It uses dependency injection to decouple configuration and service instantiation.
• The design emphasizes plug-ability: different authentication flows (OIDC vs. SAML vs. DigiD mock) are handled by separate providers and service implementations.
• It employs an external caching mechanism (Redis) for stateful operations and rate limiting.
• To call out how the PKCE OIDC flow is integrated by showing its specific endpoints and the code snippet verification process.