Notakey Authentication Server

Introduction

Notakey Authentication Server (NtkAS) is a web based management software for the Notakey Authentication Appliance. It serves as an HTTP API endpoint as well.

3rd-party integration

NtkAS exposes its functionality via a HTTP-based API that is consumed both by 3rd-party software and the Notakey Authenticator.

API integrator’s manual

User Identity

Each end-user must be registered in a specific application, and their username must be set. This username will be used by 3rd-parties to request authentication.

Glossary

Term	Description
Application	Each Application is a logical grouping of users, with a single purpose. For example - VPN authentication could be one application, and web-based login could be another.
Application User	Each application has multiple application users and each user can onboard multiple devices. Application users can be manually created by an administrator or retrieved automatically from user sources during onboarding process.
User Sources	An application can have multiple user sources. These are used to retrieve user info and verify identity during onboarding process. Possible user sources are: Active Directory, LDAP
Onboarding Requirement	Each application can have multiple requirements which must be satisfied by users trying to onboard their devices. These can be: Simple credentials, SMS, Manual (in-person), OpenID Connect

Onboarding

Onboarding is the process, by which a user links their phone (running Notakey Authenticator) to a specific user in a specific application on a specific NtkAS instance.

It is initiated by the user, on their smartphone:

• User requests onboarding on their smartphone for a specific application
• Smartphone queries the application for a list of onboarding requirements. These are configurable, and include (but are not limited to):
  • Username/password input
  • Phone input for SMS onboarding
  • OpenID credential input
• User fulfills the onboarding requirements, and submits response to the NtkAS
• Server verifies the received information, and extracts Notakey user identity from this information. This step can involve manual approval by an administrator.
• Once the user identity is determined, the NtkAS issues an X.509 certificate corresponding to the user’s key in Notakey Authenticator. This certificate can optionally be issued by a third-party CA via the SCEP protocol

User Interface Overview

• Dashboard - welcome page
  • Applications - lists all configured applications (e.g. VPN, Windows Login)
    • Manage - Application management overview
    • Application name
      • Settings - General information about specific application.
      • Onboarding requirements - Each application can have different requirements, which need to be fulfilled by users to successfully perform onboarding.
      • Users - Displays a list of all users created in the system, these users can onboard their devices.
      • User sources - Users can be automatically looked up from different user sources, possible candidates can be “Active Directory” or “LDAP”.
      • Users pending manual approval - Lists all users who have initiated manual onboarding and need approval. (As defined in “Onboarding requirements”)
      • Onboarding activities - Lists detailed onboarding process steps.
      • Authentication activities - Lists detailed authentication workflow steps.
• Event auditing - Can specify Rsyslog endpoint to which audit events will be sent.
• Log out - Logs user out of system.

Applications

To see an overview of current applications, expand “Applications” and click “Manage”. When a new NtkAS instance has been set up, an application should be the first thing you create.

Create Application

To create an application click on “Create an application”. Here you will be able to name your application, as well as customize it’s layout for users Notakey Authenticator app. Only “Name” is mandatory, images can be added later on. When all the info has been filled, click on “Create” - you should now see your first application.

Onboarding Requirements

Each application must have a minimum of one onboarding requirement. If multiple requirements are specified, user will have to meet all of them during onboarding, in the same sequence as they are specified in NtkAS. These requriements should be configured based on available user sources or desired use-cases.

• Simple Credentials - During onboarding process user will have to specify a username/password. NtkAS will try to find corresponding user:

  1. In user pool already in the NtkAS, either created manually or those who have, at some point, already been retrieved from one of the user sources.
  2. Go through every user source specified under “User sources”

• SMS - During onboarding process user will have to specify a phone number to which an SMS with confirmation code will be sent. This confirmation code will then have to be entered during the next step of onboarding. User will have to be created under “Application Users” with correct phone number specified. This is because NtkAS will use phone to find the corresponding application user. This requirement can be set in junction with Simple Credentials as the first requirement. When Simple Credentials requirement has been fulfilled, the application user will be created. Note that users retrieved from LDAP or Active Directory will have to have a mobile phone number specified.

• OpenID Connect - If an OpenID Connect provider is available, then NtkAS can be configured to use it to onboard a user device as well as create corresponding Application user. This requirement requires additional configuration, which must be set clicking “Edit”.

• Manual (in‑person) - If for some reason none of the above requirements are feasible, then manual onboarding can be specified. User will have to be manually approved by an administrator from NtkAS. This is usually used when dealing with confidential data, in which case no automatic onboarding can be performed and requires hand-picked approval from NtkAS administrator himself. The workflow is as follows:

  1. User performs onboarding.
  2. Notakey Authenticator will present a uniquely generated image - this image is specific for the device. When the image is generated on the device, in NtkAS under “Users pending manual approval” a new request will be listed with the same image.
  3. User will then go ahead and contact the NtkAS administrator whom he’ll show the generated image.
  4. Administrator will compare the image from the device and the image in the NtkAS generated under “Users pending manual approval” and determine if the image on user’s device is the same as the one in NtkAS - if it is, administrator can “Approve” the onboarding request from the interface and finish onboarding.
  5. User on Notakey Authenticator clicks “Try again” and sees a message stating that onboarding has been successful.

Users

Each application has it’s own pool of application users. Users can be created in a number of ways:

• Manually by an administrator.
• During Simple Credential onboarding process from one of the user sources.
• During OpenID Connect onboarding process.

Each user can have one or more associated devices. The number of devices a user can onboard is specified under “edit” page.

Bulk actions

To perform action on multiple users – select desired users, choose an action and press Perform.
Available actions are:

• Enable / Disable users
• Destroy devices
• Destroy users

User import from CSV file

It will import users from CSV file. Columns should be named following way:

Username, Full name, Email,         Phone,       Password,  Teams,        Enabled
johndoe,  John Doe,  john@doe.com,  37120000001, p455w0rd,  Root,         yes
jameswho, James Who, james@who.com, 37120000002, 53cr3t,    First|Second, yes

For Teams colum, separate multiple team names with | (vertical pipe) separator.
For Enabled column we accept truthy values such as: true, t, yes, y or 1. Anything else will be processed as falsy value.
If user with the same username already exists – import procedure will just update it’s attributes.

User export to CSV file

It will export whole user list in CSV format - with following columns:

• Username
• Full name
• Device count
• Enabled (disabled) state
• Last authentication timestamp
• Last onboarding timestamp
• Teams
• Created at timestamp
• Last Updated at timestamp

User Sources

Each user could be created manually, but that would take too much time. During onboarding process a user can be looked up in one of the user sources and automatically created as an Application User. Currently two user sources can be specified Active Directory and LDAP. Each application can have multiple user sources specified. During onboarding process a user will be searched through each of the sources.

Specifying an Active Directory user source requires the following:

• Name - Active Directory domain name. If, during onboarding, user hasn’t specified a domain - the configured one will be appended.
• Host - Active Directory address. This address must be reachable from Notakey Authentication Appliance. Port is mandatory as well.
• Bind username / Bind password - This user will be used to lookup and sync Application Users with Active Directory. Bind user must have access to all of the potential Application Users
• Parameters - Additional configuration can be specified here. Possible options are:
  • upn_suffix - User can have one or more UPN suffixes in addition to the default domain.
  • mandatory_group - User must be a member of this Active Directory group.

User lookup

During onboarding process user lookup happens as follows:

• NtkAS tries to find it in it’s own “Application User” list
• If the user is not found there, NtkAS starts going through all of the user sources until it finds the user it’s looking for.

Let’s take an example. We have an Active Directory user source defined with the following attributes:

• name: notakey.com
• host: 10.0.1.23
• parameters:
  • mandatory_group=employees
  • upn_suffixes=notakey_other.com

User starts Simple Credential onboarding process:

• He fills in onboarding form with these credentials: user@notakey_other.com / 123456
• NtkAS tries to find the user in existing Application Users
• The user is not found. NtkAS proceeds to find the user within all available user sources.
• It starts with Active Directory.
  • NtkAS checks which domain has been set. If no domain is passed, then the configured one is added. In this case, “@notakey_other” domain has been set. Which is allowed by the upn_suffixes config parameter.
  • NtkAS tries to authenticate against AD with the provided credentials and ensures that user is within mandatory_group config parameter.
  • The user has been found in AD, so NtkAS stops looking.
• “Application User” is created from the attributes found in the AD.
• Onboarding step has been completed.

Onboarding Activities

This section allows administrators to inspect onboarding processes and possibly assist users.

Each onboarding activity can be expanded to see detailed steps where in the onboarding process the user is currently in. Each step is shown sequentially, the top one being the most recent. If for some reason the onboarding process is stuck or cannot be continued, administrator can click “Destroy”, so that the onboarding process can have a fresh start. These activities are grouped by onboarding requirements ( or system if the step is not associated with any of the requirements).

Authentication Activities

All ongoing authentication requests will be listed under Authentication Activities. The layout is the same as Onboarding Activities.

Event Auditing

All audit events can be sent using Rsyslog protocol to a specified endpoint. These events should help debugging any problems user may experience during onboarding or authenticating.

Example entry:

[ONBOARDING] [8c620] [mkarklins] [apple] Check if user device has been onboarded. Not found.

Multi-user approval

Multi-user approval (MUA) is used in cases when a user needs access to an application, requiring manager’s approval. There are two possible policies: immediate approval and pre-approval.

Immediate approval

This policy is used when manager has to approve every request an employee is trying to perform. Example workflow would be as follows:

1. NtkAS administrator has configured immediate approval policy for user “Employee1”. All requests will need to be approved by his supervisor “Manager1”.
2. Employee1 tries accessing “Demo VPN”
3. Employee1 approves his own request
4. Manager1 receives access request, stating that Employee1 wants to access “Demo VPN”.
5. Manager1 approves access.
6. Employee1 is granted access.

Pre-approval

This policy is used when an employee requires access to a particular application for a specific time frame, e.g. full day. In this case manager doesn’t want to approve every request. Instead, manager pre-approves all requests to an application for a requested time period. Example workflow would be as follows:

1. NtkAS administrator has configured pre-approval policy for “Employee1”. All requests will need to be approved by his supervisor “Manager1”.
2. Employee1 needs access for “Demo VPN” for 30 minutes, so he goes to web and creates a new request using a given link.
3. The request must be confirmed by Employee1.
4. Request must then be approved by Manager1.
5. When Employee1 has given his approval - Employee1 can proceed to use the “Demo VPN” system for the next 30 minutes.

Administrator can configure approver, opening user list and clicking policy. The url shown in the grey box, must be given to a user who will want to request access for an application. Each user can have one approver. If manager hasn’t approved the request in 1 hour, user must create a new request.

When user’s requested time has expired - user will no longer receive authentication requests to Notakey Authenticator.

When user visits the provided link, his username and desired access time must be entered.

Authentication profiles

Authentication profiles allow to invoke URL events initiated by authentication requests. Invoked URLs can be protected by OAuth 2.0 client credentials or any header based http authentication, e.g. shared token. Authentication profiles defines properties of authentication request, like validity period, content and title.

Profile also defines certain variables and allows to pass custom variables in the event of creation of request, that can be later displayed to the user, e.g. authentication session identifier.

Number of callbacks per single authentication profile is unlimited, but will take considerable amount of resources to invoke and may cause delays if many are invoked in parallel, if all threads are busy. Callback invoking is performed in the background and will not affect the performed operations.

Variables can be contained in any relevant field, enclosed by curly braces, like this {var}.

Supported variables in callbacks

Variable	Description
response_type	Type of response, if applicable.
state	Auth request state parameter.
event	Event type, see “Supported events”.
uuid	Auth request unique identifier.
username	Auth request username.
user_email	Auth request user email.
user_phone	Auth request user phone.
user_full_name	Auth request user display name.
user_id	Auth request user ID.
user_guid	Auth request user external GUID, e.g. from ActiveDirectory.
biometry_check	True, if biometric check is requested.
keytoken	Issued keytoken for key acquisition from registry.
fingerprint	Auth request fingerprint parameter.
action	Title of auth request.
description	Auth request text body.
response_payload_base64	Signed payload of response, if applicable.
response_payload_type	Type of signed payload, if applicable.
response_ip	Responders IP address, if applicable.
request_ip	Auth request senders IP address.
error	Error type (Exception type).
error_message	Exception message.

Supported variables in auth request fields

Variable	Description
username	Auth request username.
user_email	Auth request user email.
user_phone	Auth request user phone.
user_full_name	Auth request user display name.
user_id	Auth request user ID.
user_guid	Auth request user external GUID, e.g. from ActiveDirectory.
fingerprint	Auth request fingerprint parameter.
state	Auth request state parameter.

Supported events

Event	Description
Create	Invoked when auth request is created (user scans QR or API consumer sends create request).
Approve	User pressed Approve.
Deny	User pressed Deny.
Response	User pressed Deny or Approve.
Error	There was an error while invoking URL generated by event, use {error} and {error_message} to investigate.
Any	Invoked on any event, except error, use {event} to investigate.

FAQ

Is an onboarded user and active user?

No, an active user is one who has used Notakey Appliance for authentication purposes at least once in the last 90 days.

Which phone number does the Active Directory user source use?

It uses the first entry under “Telephones” -> “Mobile”

How to synchronize Application User from Active Directory?

Latest information is pulled from AD during onboarding process. To synchronize, delete the Application User and let the user perform onboarding process again.