| Table of Contents |
|---|
Entities (tables)
On this page are described data structure only for new entity of 2FA flow.
Full described data model of Auth (with schema & erd file) see on parental page : Auth .
Authentication factors
This entity defines authentication factors entity information structure:
| Column | Type | M/O | Purpose |
|---|---|---|---|
| id | uuid | M | |
| user_id | uuid | M | User FK |
| type | varchar | M | |
| factor | varchar | O | Factor value |
| is_active | boolean | M | |
| inserted_at | timestamp | M | |
| updateed_at | timestamp | M |
| type | factor |
|---|---|
SMS | "+380677778899" |
| PHONE | "+380677778899" |
| "pupkin.vasya@gmailvasya@gmail.com" |
Users
This entity enrich a few attributes:
Store
...
few new parameters for
...
in `users.priv_settings` as structure (example):
{"login_
...
- hstr": [{"time": "2017-12-26T10:11:38.232508", "type": "password", "is_success": false}],"otp_error_counter": 0}
where:
Attribute Type Purpose otp_error_counter boolean Count for error-entered OTP attempts login_hstr[] array Array for store login history & OTP generate/send history login_hstr.time timestamp Date+time login/OTP item login_hstr.type varchar Type of item: `password` or `otp`
login_hstr.is_success boolean Is success state for item Information about blocked/unblocked directly in entity `users`.
Column Type M/O Purpose is_blocked boolean O block_reason varchar (255), NULL O Block / Unblock reason
OTP
This entity defines OTP (one tome passwords) entity information structure:
| Column | Type | M/O | Purpose |
|---|---|---|---|
| id | uuid | M | |
| key | varchar | M | Сomposite key: <token.id> + <separator> + <Value of factor> |
| code | varchar | M | Value of OTP |
| status | varchar | M | Status (Dictionary: OTP_STATUS) |
| code_expired_at | timestamp | M | Timestamp which OTP expired (now() + param from config) |
| attempts_count | integer | O | Count of trying OTP authorization process |
| updateed_at | timestamp | M |
State charts
2FA state chart
We need minimal 4 state for user & 2FA:
- DISABLED - Disable 2FA for this user (via NHS Admin)
- BLOCKED - User blocked after N-unsuccessful attempts via authentication process.
- RESET - NHS Admin reset value of factor or factor type. At first login user must fill value of factor.
- ACTIVE - normal status: 2FA enable
Propose don't use statuses model, and use logic calculating for state 2FA user:
| Logic status for 2FA & user | Purpose |
|---|---|
| RESET | User don't blocked (`is_blocked`=false) & exist 1 active item in `authentication_factors` with empty value of factor . ( factor = NULL or factor = "" ) |
| ACTIVE | User don't blocked (`is_blocked`=false) & exist 1 active item in `authentication_factors` with fill value of factor. Examples for type = SMS: ( factor= "+380677778899" ) |
| DISABLED | User don't blocked (`is_blocked`=false) & not exist any active items in `authentication_factors` -- return 0 rows) |
| BLOCKED | User have `is_blocked`=true (SELECT * FROM users AS U --- return 1 rows) |
OTP states
Dictionary: `OTP_STATUS`
Value Purpose NEW Initial status for newest OTP item. Ready to use in OTP verification process. VERIFIED Status for successful OTP verification process UNVERIFIED Status for unsuccessful OTP verification process EXPIRED Expired after OTP lifetime. CANCELED Status for manual admin action.
- Status Chart for OTP
- TransitionsFromTransitionResult
Created new OTP status = NEW status = NEW Succseful OTP verify status = VERIFIED status = NEW Unsuccseful OTP verify afterexcess of count [param: OTP_ERROR_MAX] status = UNVERIFIED status = NEW [AUTO] Termination process after end of life-time OTP [param: OTP_LIFETIME] status = EXPIRED status = NEW All OTP by `key` in status=`NEW` before creating new OTP status = CANCELED
Сonstraints
Authentication factors
- user have one active 2FA factor ( one of any type)
- unique index on user_id+type