Advanced Authentication API doc

Endpoints ¶

Endpoint session management

Endpoint sessions ¶

Endpoint session management. Does not require login/endpoint session. Instead, it requires endpoint secret.

Session lifetime (TTL): expire on inactivity 60 min, max lifetime 10080 min. It may change without notice. Please handle 434/433 HTTP codes to re-open session on-the fly and re-send request.

Logon ¶

Implements logon process. Requires endpoint_session_id. Add it to all requests.

Login procedure:

1. Start login process, grab login_process_id

2. Series of do_logon calls. Client software sends ‘response’ to server; server replies with ‘challenge’

3. Received status=‘OK’ or ‘FAILED’ is the end of the process.

   OK - logon is complete, login session has been created. FAILED - logon failed, the process destroyed (note - HTTP status is 200).

4. HTTP errors 400 or 500 do not destroy the process, it is possible to continue.

5. Special HTTP error 444 is returned in case when logon process is not found or expired. Not possible to continue. Start new logon.

6. Special HTTP error 434 is returned in case when login session not found or expired. (433 is same for endpoint session)

Simple logon ¶

First, you create login process::

POST /api/v1/logon
    {
        "method_id": "PASSWORD:1",
        "user_name": "REPONAME\\USERNAME",
        "is_1N": true/false,   # optional, default false
        "unit_id": "xxx",   # for 1N login
        "event": "xxx"   # can be empty string for testing (allow any method)
    }

For 1N login, you set is_1N to True and pass unit_id. For normal login, you pass user_name.
Return::

{
    "chains": [],
    "completed_methods": [],
    "current_method": "PASSWORD:1",
    "logon_process_id": "Ww323YxvYv6IVj3J3EaLNlkVM2aoHfLa",
    "msg": "Process has been started",
    "status": "MORE_DATA"
}

Grab logon_process_id and perform series of do_logon calls while getting status ‘MORE_DATA’::

POST /api/v1/logon/Ww323YxvYv6IVj3J3EaLNlkVM2aoHfLa/do_logon
    {
        "response": "method-specific dictionary, maybe omitted if method does not requires data on 1st do_login"
    }

Return
    {
        # method-specific data such as
        "challenge": {"rounds": 100, "salt": "cdf123Dx"},
        "status": "MORE_DATA"
    }

POST /api/v1/logon/Ww323YxvYv6IVj3J3EaLNlkVM2aoHfLa/do_logon
    {
        "response": {"answer" : "my-password" # method-specific dict in "response" field}
                                              # this is "response" to "challenge" which server sent in previous do_logon
    }

At some iteration, you get either status=OK or FAILED. ‘OK’ gives you also information about logged user::

{ 
    "chains": [],
    "completed_methods": ["PASSWORD:1"],
    "login_session_id": "YTxTmMW6RPv051RmeCiyBn7txzE0JoM2",
    "msg": "Welcome",
    "repo_id": "703f7c641beb11e48c69000c294fde0e",
    "user_id": "7044631e1beb11e48c69000c294fde0e"
    "user_name": "LOCAL\\\\user1",
    "event_name": "Windows logon",
    "event_data_id": "OSLogon",
    "status": "OK",
    "completed_chain": {
        "name": "Admin Password",
        "position": 0,
        "id_hex": "3c8c306e061e11e6b224080027983191",
        "apply_for_ep_owner": false,
        "required_chain_id_hex": null,
        "methods": ["PASSWORD:1"],
        "short_name": "",
        "image_name": "PASSWORD_1.png",
        "is_trusted": null,
        "is_enabled": true,
        "grace_period": null,
        "mfa_tags" : []
    }
}

Example of FAILED method

{ 
    "msg": "Incorrect password",
    "status": "FAILED"
}

Grab login_session_id, you will pass it to other services. 1-N logon does not know user name before login starts, and now it knows.

Chained logon ¶

Depending of event and endpoint_session_id (trusted/untrusted endpoint) you receive list of chains.

Chain defines:

• list of methods user must login to, one-by-one.

• After login, you can access data of the event by using ‘user_data’ service.

‘NEXT’ status says that current method is complete (OK) and user must start next method. What method to start is up to user (or client UI) - it depends on what chain user wants to complete.

Login is completed as soon as any chain is completed.

Chained logon example::

optional - read chains

GET  /api/v1/logon/chains?event=Windows%20logon&is_trusted=true

decide what chain to complete and...

1. start 1st method

POST /api/v1/logon
    { "method_id": "SUPER_OTP:1", "user_name": "MARIA\\director", "event": "Windows logon" }
    
returns
    { "chains":
            [
                # same list of chains as you GET from /api/v1/logon/chains?event=Windows%20logon
            ],
      "completed_methods": [],
      "current_method": "SUPER_OTP:1",
      "logon_process_id": "abc345",
      "msg": "Process has been started",
      "status": "MORE_DATA"
    }

Grab login_process_id (abc345) and…

2. call do_logon

POST /api/v1/logon/abc345/do_logon
    { "response": "some_secret" }
    
returns
    { "status": "MORE_DATA", "current_method": "SUPER_OTP:1", "completed_methods": [] }

3. continue 1st method (it is 2-phase method)

POST /api/v1/logon/abc345/do_logon
    { response: "second_secret" }
    
returns
    { status: "NEXT", "completed_methods": ["SUPER_OTP:1"] }

Status=NEXT means ‘SUPER_OTP’ is OK, completed_methods has method name.
You start next method by POSTing to same process::

4. start next method

POST /api/v1/logon/abc345/next
    { "method_id": "LDAP_PASSWORD:1" } # user_name will be same as before
                                       # you may pass unit_id and is_1N=true,
                                       # it will work - but unit_id must be owned by same user
                                       
returns
    { status: "MORE_DATA", "current_method": "LDAP_PASSWORD:1", "completed_methods": ["SUPER_OTP:1"]}

5. call do_logon, as usual

POST /api/v1/logon/abc345/do_logon
    { "response": "Password1" }
    
returns
    {
        "status": "OK",
        "completed_methods": ["SUPER_OTP:1", "LDAP_PASSWORD:1"],
        "login_session_id": "YTxTmMW6RPv051RmeCiyBn7txzE0JoM2",
        "msg": "Welcome",
        "repo_id": "703f7c641beb11e48c69000c294fde0e",
        "user_id": "7044631e1beb11e48c69000c294fde0e",
        "user_name": "MARIA_GROUP\\user1",
        "event_name": "Windows logon",
        "event_data_id": "OSLogon",
        "completed_chain": {
            "name": "Admin Password",
            "position": 0,
            "id_hex": "3c8c306e061e11e6b224080027983191",
            "apply_for_ep_owner": false,
            "required_chain_id_hex": null,
            "methods": [
            "PASSWORD:1"
            ],
            "short_name": "",
            "image_name": "PASSWORD_1.png",
            "is_trusted": null,
            "is_enabled": true,
            "grace_period": null,
            "mfa_tags" : []
            }
    }

The chain is complete! Grab login_session_id!

OK, grab login_session_id and user info.

Chained logon - wrong password in the middle

Consider a chain has 3 methods, user completed 2 of them but provided wrong credentials for 3rd method. In that case:

1. Result is NEXT (not FAILED because it means end of the process)

2. completed_methods still contains 2 methods

3. Re-start method by POSTing as usual to /api/v1/logon/abc345/next

Login sessions ¶

Manage login sessions. Requires endpoint_session_id

Session lifetime (TTL): expire on inactivity 20 min, max lifetime 1440 min. It may change without notice. Please handle 434/433 HTTP codes to re-open session on-the fly and re-send request.

Enroll ¶

The service for creation authentication template (enroll). Requires login_session_id of Helpdesk or Authenticators Management events. Any user may start enroll process.

When process is finished, you create template from process result by using ‘user_template’ service. Until that, process result lives at the server for some time. Admin may assign process result to any user. User may assign process result to himself. It is possible that user1 created the process, tell enroll_process_id to user2 and he assigns it to himself.

Enroll procedure:

1. Start enroll process, grab enroll_process_id

2. Series of do_enroll calls. Client software sends ‘response’ to server until it replies ‘OK’ or ‘FAILED’

3. POST/PUT enroll_process_id and user_id to ‘user_templates’ service.

Policies ¶

Read object policies. Requires logged_session_id.

No writes. Setting policies is the task of admin UI.

Policies are defined for component. “Component policies” is dictionary of values. Value is any json-serializable object, maybe nested dict::

{ “component_id”: { “policy1”: value, “policy2”: value } }

Service returns effective policies. Effective is default component policies overridden by object-specific policies.

User data ¶

Access to data of the user.

Requires login_session_id of user or admin.

Data is defined for events. You may access data only of the event you are logged in. The event defines accessible data_id. Several events may share data_id. By default data_id = Event.name.upper().

Data permissions

1. Restricted records - admin and user can read, but only admin can write (restricted write)

2. Sensitive records - admin and user can write, but only user can read (restricted read)

User templates ¶

Access to user’s authentication templates. Requires login_session_id of user or admin.

Categories of templates ¶

Read authenticator categories. Requires login_session_id of any user authenticated to any event.

Users ¶

User lookup by name, list of users.

Requires login_session_id. Logged user must be member of FULL ADMINS or ENROLL ADMINS.

Events ¶

Events manager rest api. Requires login_session_id. Logged user must be member of FULL ADMINS or ENROLL ADMINS.

Cookie and Ticket services ¶

Chain image ¶

Provides chain images. This API is not restricted by endpoint/logon session.

Custom messages ¶

Read localization items. Requires endpoint_session_id. No writes.

Status ¶

Read server status and version. Requires endpoint_session_id to read version.

Logon by Basic Auth to /account ¶

Provides basic authentication.

Cached Logon notification ¶

This API should be used by desktop clients. It allow them to notify server about cached logons. As result server can

1. Track such logons to the syslog
2. Update templates (HOTP counter for example)
3. Return template hashes which allow clients to clear local cache (if templates was changed since last server logon)

OOB Logon ¶

Out-of-band authentication.

OOB logon procedure from the point of view of “custom SSH server” or “Windows Client”.

1. User connects to SSH server. The server asks user_name.

2. SSH server starts OOB logon process. Pass user_name, grab oob_secret. You need endpoint_session, as normal endpoint.

3. Periodically (5-10 seconds) check the status of oob logon process.

   Meanwhile, user opens "aucore-server/oob/{login_url}, sees WebUI logon page and logons. User can’t change user_name on WebUI login page.

   SSH server may grab login_url and ask user to open it. Another option is to use “Authentication Agent” running on user’s device (computer).

4. As soon as the answer is “success: True”, SSH server resumes its normal login into the shell.

   AuCore server returns user.data[event.type], such as OS_PASSWORD. Windows Client needs real user password to perform domain login (event.type OS_LOGON)

OOB logon procedure from the point of view of “Authentication Agent”. Differences:

• no endpoint_session is needed

• user_name is not required, any string is possible. User may change user_name in WebUI logon page.

1. User starts Authentication Agent.

2. Agent creates OOB logon process, grabs oob_secret and logon_url.

3. Agent opens logon_url in browser, user does login.

4. Periodically the agent checks the status of oob logon process.

5. As soon as the answer is “success: True”, the agent registers itself in OOB Daemon by using oob_secret.

   AuCore server does not return user.data[event.type] (OS_PASSWORD).

   AuCore server returns user_name. The agent may check that user_name is what the agent expects. The format of user_name: TENANT\REPO\USER or REPO\USER depending on multitenancy is ON or OFF.

Methods ¶