12.52. DD 52: LibEufin Bank Two-factor authentification¶
12.52.1. Summary¶
This document proposes designs for supporting 2-FA for more operations in libeufin-bank.
12.52.2. Motivation¶
Currently, only cashout operations are protected using 2-FA and we want to also protects withdrawal, transactions, account reconfiguration and account deletion.
12.52.3. Requirements¶
Support future TAN channels (YubiKey, trusted devices, etc) without API-breaking changes
Support multiple TAN channels per user
12.52.4. Proposed Solutions¶
12.52.4.1. 2 kinds of operations¶
We have two kinds of operations we would like to protect:
state-machine operations that already have a
pendingandconfirmedstatus and require multiple endpoint calls to complete (cashout and withdrawal).one-shot operations that are currently completed using a single endpoint call (transaction, account reconfiguration and account deletion).
12.52.4.2. Fine-grained or coarse-grained authentification¶
Fine-grained authorization is when one challenge is linked to a unique unalterable operation. They are the most secure and have the usability advantage that clients can show users exactly what they are allowing. They are complicated to implement especially for one-shot operations.
Coarse-grained authorization is when each challenge allows to perform one or many protected operations of any kind. They are the simplest to implement and might be enough for our needs.
We should also take in consideration how hard it would be to maintain the solution and how hard it would be to protect a new kind of operation in the future.
12.52.4.2.1. State machines operations only¶
If we transform all operations to become state-machine ones, we can use the same design currently used for cashout operations. All operations are created in a pending state and need to be confirmed later. The TAN challenge code is sent when the operation is created and checked during confirmation. Operation creation is idempotent and can be used to trigger code retransmission.
12.52.4.3. The good¶
Fine-grained authorization
12.52.4.4. The bad¶
Requires to store pending operations in the database, requires new tables to store pending state for one-shot ones
Requires to add many endpoints to track operations status, list pending operations, confirm operations, etc
Requires to mix TAN challenge logic with operation logic, this means asking for TAN channel alongside operation data and returning TAN specific error in all operation creation and confirmation endpoints, therefore TAN logic changes can impact all those endpoints
Operation logic rewrite
Big backend and database change (new table or column and new API per operation)
12.52.4.4.1. Centralized 2FA endpoints¶
To improve upon the previous design we can separate endpoints to perform TAN challenges from operation ones. When creating operations they return a challenge ID that can be used with TAN-specific endpoints to receive and solve a challenge. Those endpoints will handle the TAN channel choice and TAN-specific errors. Protected endpoints will error when a pending challenge hasn’t been solved.
12.52.4.5. The good¶
Fine-grained authorization
Centralized TAN challenge logic and error handling, TAN logic changes only impact TAN-specific endpoints
12.52.4.6. The bad¶
Requires to store pending operations in the database
Requires adding many endpoints to track operations status, confirm operations, list pending operations, etc.
Operation logic rewrite
Big backend and database change (new table or column and new API per operation)
12.52.4.6.1. 2FA tokens¶
To improve upon the previous design, if coarse-grained authorization is enough, we can have a simpler design where a successful challenge produces a one-use 2FA token. Protected endpoints will error when a 2FA token is required and the token is provided through an HTTP header.
We could require a 2FA token when confirming state-machine operations or when performing one-shot ones. Removing the need for new database tables and operation endpoints.
12.52.4.7. The good¶
Existing database tables stay the same
Centralized TAN challenge logic and error handling
Most endpoints stay the same except the cashout API
Can protect new operations without changing their logic but need to add token consumption logic to the database transaction
Small backend and database change per operation (token consumption logic)
12.52.4.8. The bad¶
Using a nonstandard header can be complicated for some clients
The pending state of one-shot operations is kept at the client level, this is a simplification for the backend but we do not want to lose this state. This might be easy to do as all oneshot operations are simple ones and the token can be obtained in advance.
Coarse-grained authorization, one token for any operation. We could fix this by adding a
kindfield and an optionaloperation_id(state-machine operation) oroperation_body(one-shot operations) field per challenge but this is ugly.
12.52.4.8.1. 2FA auth tokens¶
To improve upon the previous design, we could reuse the existing authentification token logic and create a new scope, 2fa, that works as an augmented readwrite. Those auth tokens would be valid for a short amount of time (~3 minute) and would not be refreshable.
12.52.4.9. The good¶
Existing database tables stay the same
Centralized TAN challenge logic and error handling
Most endpoints stay the same except the cashout API
Can protect new operations without changing their logic
Trivial backend and database change per operation (one line of code per operation)
12.52.4.10. The bad¶
Having a short-term token in addition to a long-term refreshable token can be confusing for clients.
We still keep the pending state of one-shot operations at the client level.
Coarse-grained authorization, one token for any operation for a short amount of time.
12.52.5. Q / A¶
Q: Where do we want to handle TAN challenges logic and error handling, in each operation API or a TAN-specific API?
In each operation means fewer API calls and TAN-specific means more API calls but better/cleaner logic separation.
Q: Where do we want to store pending states for oneshot transactions in the client or the backend database?
In the client makes things simpler for the backend but is incompatible with coarse-grained authorization.
Q: Do we need coarse-grained authorization or fine-grained is enough?
Coarse-grained authorization requires that we store pending states for operations even for the ones that are currently oneshot. We could use a different strategy for each kind.