Authentication flow

When two-factor authentication required, server responds with "401 Unauthorized" code on main authentication, and puts 'WWW-Authenticate' header with requested authentication. If client logins with method Session.StartSession, then session will be created even though 401 code is returned. Created session id provided by server in 'X-KSC-Session" header in a reply:

    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: KSCMFA type="totp", lengthHint="6"
    X-KSC-Session: nf5M5KGjlhbrLj7JvZ05gMA==
    Content-Type: text/plain
    Content-Length: 27

    Authentication not finished

lengthHint is a hint for UI to know how many characters to ask user for. When such response received, initial login request must be repeated with same URL and request body. TOTP code must be provided in Authorization header, KSCMFA scheme. For authenticated sessions session id must be provided as well:

    POST /api/v1.0/Session.StartSession HTTP/1.1
    Authorization: KSCMFA totp="276069"
    X-KSC-Session: nf5M5KGjlhbrLj7JvZ05gMA==
    Content-Length: 2

    {}

Upon successful authentication server responds with usual "200 OK" reply and response body and headers according to login method. If provided TOTP code is invalid, server again responds with "401 Unauthorized", and code entry may be repeated.
Since session is created before second factor check, Session.EndSession must be called if user rejected or failed to enter TOTP code.

TOTP registration during authentication

Administrator may set up a requirement for users to register second factor. In such case KSC server will not allow user to login until he registers second factor. After successful first factor authentication server responds with "401 Unauthorized" and 'WWW-Authenticate: KSCMFA type="totpreg"' header:

    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: KSCMFA type="totpreg"
    X-KSC-Session: nKUKaZusyKge/xgUmD0EfEg==
    Content-Type: text/plain
    Content-Length: 27

    Authentication not finished

When such code is received, methods TotpRegistration.GenerateSecret and TotpRegistration.SaveSecretForCurrentUser must be used to register second factor. Though session now is created, security context is not yet built on server, and any calls other than required for second factor registration are forbidden. After successful second factor registration login method must be repeated with 'Authorization: KSCMFA totpregistered="1"' header to finish authentication process:

    POST /api/v1.0/Session.StartSession HTTP/1.1
    Authorization: KSCMFA totpregistered="1"
    X-KSC-Session: nKUKaZusyKge/xgUmD0EfEg==
    Content-Length: 2

    {}

Since session is created before successful second factor registration, Session.EndSession must be called if any method fails or user rejects to configure second factor.