‘logon’

/api/v1/logon

/api/v1/logon/{logon_process_id:[a-zA-Z0-9]{32}|chains}*custom_method

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

POST

Implements login process. 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, logon process is destroyed

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

  5. Special HTTP error 434 is returned in case when login session not found or expired

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 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'
}

# example of FAILED method

{ 'msg': 'Wrong 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_logon&is_trusted=true

# decide what chain to complete and...

# 1. start 1st method

POST /api/v1/logon
{ 'method_id': 'SUPER_OTP:1', 'user_name': 'BMW\director', 'event': 'windows_logon' }
Return
{ 'chains':
        [
            # same list of chains as you GET from /api/v1/logon/chains?event=windows_logon
        ],
  'completed_methods': [],
  'current_method': 'SUPER_OTP:1',
  'logon_process_id': 'abc345',
  'msg': 'Process 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': 'BMW\director',
    'event_name': 'Windows logon',
    'event_data_id': 'OSLogon'
}

# 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

GET

Read available chains. is_trusted can be 1, 0, “True”, “False” or missed (None):

GET /api/v1/logon/chains?user_name=LOCALdmin&event='xxx'&is_trusted=1&endpoint_session_id=xxx

Returns:

{ 'chains': [
        {   'is_trusted': None,
            'name': 'full name 1',
            'short_name': 'short name 1',
            'methods': ['PASSWORD:1', 'TOTP:1', 'HOTP:1'],
            'image_name': 'default'

        },
        {   'is_trusted': True,
            'name': 'full name 2',
            'short_name': 'short name 2',
            'methods': ['PASSWORD:1', 'HOTP:1'],
            'image_name': 'f0611f14241a11e59bf5000c294fde0e'
        },
        {   'is_trusted': False,
            'name': 'full name 3',
            'short_name': 'short name 3',
            'methods': ['PASSWORD:1', 'TOTP:1'],
            'image_name': 'default'
        }],
  'user_is_locked': True/False  # returned if you specify user_name,
                                # use it to immediately show error and not ask user creds / chain selection
}

‘chain.is_trusted’ may be None. It means the chain works for both trusted and untrusted endpoints.

If you omit ‘is_trusted’ in your query, service does not filter and returns both trusted and untrusted chains.

If you omit ‘user_name’, service does not filter and returns all chains configured given event/is_trusted.

If you provide ‘user_name’ of user that isn’t yet registered in aucore (such as new LDAP user), service returns only chains made of methods not requiring enroll.

To get chain image file, call:

GET /api/v1/chain_image/<image_name>

DELETE

Destroy logon process:

DELETE /api/v1/logon/abc345