Authentication Flow
Relevant source files
The following files were used as context for generating this wiki page:
The Authentication Flow in the MBBank library is a multi-step process designed to secure interactions with the MBBank retail internet banking API. It encompasses session establishment, captcha resolution, payload encryption using WebAssembly (WASM), and biometric verification. This flow ensures that all subsequent requests to protected endpoints are authorized via a valid sessionId and appropriate request headers.
This system is implemented in both synchronous and asynchronous variants through the MBBank and MBBankAsync classes, which inherit shared logic from a base implementation.
Session Lifecycle and Initialization
Authentication begins with the initialization of the core bank class. Upon instantiation, the system generates a unique deviceIdCommon and prepares default headers required for all API communication.
Primary Identity Components
| Component | Description | Derived From |
|---|---|---|
deviceIdCommon | A unique string identifying the client device, formatted with a timestamp. | mbbank/base/mbbank.py:65 |
sessionId | The token returned by the bank after a successful login, used for subsequent requests. | mbbank/sync/mbbank.py:90 |
FPR | A static fingerprint string used during the login payload construction. | mbbank/base/mbbank.py:20 |
Sources: mbbank/base/mbbank.py:20-65, mbbank/sync/mbbank.py:90
The Authentication Loop
The library utilizes an internal _authenticate method that orchestrates the login sequence. It attempts to log in up to a maximum number of retries (defaulting to 30) to account for potential captcha OCR failures.
The diagram above illustrates the retry logic and sequence of operations during the initial login phase.
Sources: mbbank/sync/mbbank.py:165-182, mbbank/aio/mbbank.py:145-162
Secure Payload Handling
The MBBank API requires sensitive request payloads, including credentials and transaction details, to be encrypted before transmission. This library utilizes a WebAssembly module (main.wasm) to perform this encryption.
WASM Integration
The client fetches the main.wasm file from the MBBank assets server and caches it. This module provides the wasm_encrypt functionality used to wrap JSON payloads into a dataEnc field.
Request Interception and Re-authentication
The internal request method _req acts as a middleware. It monitors for GW200 response codes, which indicate an expired session, and automatically triggers the authentication flow before retrying the original request.
| Error Code | Meaning | Action Taken |
|---|---|---|
GW200 | Session Expired | Call _authenticate() and retry request. |
GW283 | Captcha Invalid | Continue authentication loop to try new captcha. |
428 | Precondition Required | Raise CryptoVerifyError. |
Sources: mbbank/sync/mbbank.py:84-102, mbbank/aio/mbbank.py:164-210
Transactional Authentication
Beyond simple login, specific operations like money transfers require a secondary "Contextual" authentication flow. This involves verifying the destination account and obtaining a transaction-specific QR code or ID for OTP verification.
Transfer Authentication Sequence
The TransferContext (or TransferContextAsync) manages this stateful flow.
- Inquiry: Verifies the destination account name and bank details.
- Verify: Performs a preliminary "verify-make-transfer" call with an empty OTP to check limits and fees.
- Auth List: Retrieves available authentication methods (e.g., SMS OTP, Soft Token) via
getAuthList. - Transaction ID: Generates a
transactionAuthenID used to build a QR code string. - Finalize: Executes
make-transferwith the user-provided OTP.
Data Models for Identity
Authentication results are mapped to complex Pydantic models to provide structured access to user data. The UserInfoResponseModal contains comprehensive details about the authenticated session.
Key Identity Fields
| Field | Type | Description |
|---|---|---|
sessionId | str | Active session token for the authenticated user. |
cust.id | str | Internal customer identifier. |
cust.isSoftToken | str | Indicates if the user has Soft Token authentication enabled. |
cust.softTokenList | List[SoftTokenModel] | List of registered soft token devices. |
biomatricAuthDeviceList | List[BiometricAuthDeviceModel] | Devices registered for biometric authentication. |
Sources: mbbank/modals/userinfo.py:192-230
Summary
The Authentication Flow provides a robust mechanism for maintaining secure sessions with MBBank. By abstracting the complexities of captcha solving, WASM-based encryption, and automatic session recovery, the library allows developers to focus on banking logic while ensuring all communication adheres to the bank's security requirements. The flow is tightly integrated into every API call, ensuring that credentials and session tokens are valid before any transaction is attempted.