ЕСОЗ - публічна документація

2FA Data model

Owned by Edward Voloshin (Unlicensed)
Last updated: Feb 28, 2024 by Serhii Boldin (SoE eHealth)
2 min read

Data structure

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:

ColumnTypeM/OPurpose
iduuidM
user_iduuidMUser FK 
typevarcharM
factorvarcharOFactor value
is_activebooleanM
inserted_attimestampM
updateed_attimestampM
typefactor 

SMS

"+380677778899"
PHONE"+380677778899"
EMAIL"pupkin.vasya@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:

    AttributeTypePurpose
    otp_error_counterbooleanCount for error-entered OTP attempts 
    login_hstr[]arrayArray for store login history & OTP generate/send history
    login_hstr.timetimestampDate+time login/OTP item
    login_hstr.typevarchar

    Type of item: `password` or `otp`

    login_hstr.is_successbooleanIs success state for item

  • Information about blocked/unblocked directly in entity `users`. 

    ColumnTypeM/OPurpose
    is_blockedbooleanO
    block_reasonvarchar (255), NULLOBlock / Unblock reason

OTP 

This entity defines OTP (one tome passwords) entity information structure:

ColumnTypeM/OPurpose
iduuidM
keyvarcharMСomposite key: <token.id> + <separator> + <Value of factor>
codevarcharMValue of OTP
statusvarcharMStatus (Dictionary: OTP_STATUS)
code_expired_attimestampMTimestamp which OTP expired (now() + param from config)
attempts_countintegerOCount of trying OTP authorization process
updateed_attimestampM

 

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 .
Examples for type = SMS:

(      factor = NULL  or factor = "" )

ACTIVEUser 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` 
(SELECT * FROM authentication_factors AS 2FA 
WHERE 2FA.user_id = $.user_id AND 2FA.is_active = 1

-- return  0 rows)

BLOCKED

User have `is_blocked`=true 

(SELECT * FROM users AS U
WHERE U.id = $.user_id AND U.is_blocked = true

--- return 1 rows)

OTP states 

  • Dictionary: `OTP_STATUS`

    ValuePurpose
    NEWInitial status for newest OTP item. Ready to use in OTP verification process.
    VERIFIEDStatus for successful OTP verification process
    UNVERIFIEDStatus for unsuccessful OTP verification process
    EXPIREDExpired after OTP lifetime.
    CANCELED

    Status for manual admin action.

  • Status Chart for OTP
  • Transitions
    From
    Transition
    Result

    		Created new OTPstatus = NEW
    status = NEWSuccseful OTP verifystatus = VERIFIED
    status = NEWUnsuccseful 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 = NEWAll OTP by `key` in status=`NEW` before creating new OTPstatus = CANCELED

Сonstraints

Authentication factors

  • user have one active 2FA factor ( one of any type)
  • unique index on user_id+type

ЕСОЗ - публічна документація