NAV Navbar

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.

You can find current version of API integrator’s manual on our documentation site documentation.notakey.com, look for link to “3rd-party integration”.

API integrator’s manual for your Notakey Authentication Server version can be found on admin dashboard URL https://<appliance-address>:<port>/docs/api/.

User Identity

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

Glossary

Term Description
Service Each Service is a logical grouping of users, with a single purpose. For example - VPN authentication could be one service, and web-based login could be another.
Service User Each service can have unlimited number of users and each user can onboard multiple devices. Users can be manually created by an administrator or retrieved automatically from user sources during onboarding process.
User Sources A service 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 and RADIUS. RADIUS allows only password verification.
Onboarding Requirement Each service 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.
Service URL NtkAs instance requires setting up a FQDN (fully qualified domain name, e.g. ntk.example.com) that will be used for devices to perform onboarding and signing operations. Typical service URL then is https://ntk.example.com.
Service Domain Service URLs can be referenced by service domain for convenience, e.g. myexample.com or example.com. Users add service domain in Notakey Authenticator application and actual service URL lookup is performed automatically.

Onboarding

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

Onboarding is initiated by the user, on their smartphone:

  • User adds service URL or service domain in application settings or by scanning QR code
  • User requests onboarding on their smartphone for a specific service by clicking on
  • Smartphone queries the service URL for a list of onboarding requirements. These are configurable and can be combined, and include (but are not limited to):
    • Username/password verification
    • Phone number verification for SMS/WhatsApp onboarding
    • Manual onboarding by NtkAS administrator
    • OpenID credential input for custome onboarding flow
  • User fulfills the onboarding requirements, and submits response to the NtkAS
  • Server verifies the received information, and extracts Notakey user identity from this information.
  • 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 - Overview of latest authentication and onboarding activities in all services, manage server license
    • Services - lists all configured services (e.g. VPN, Windows Login)
      • Manage - Shows all configured services
      • Service name
        • Settings - General service security and usability settings.
        • Onboarding requirements - Each service 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”.
        • 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.
  • Settings - Syslog and service domain configuration.
  • Teams - Administrator user teams, used to configure permissions to services.
  • Access credentials - Configure API keys for client applications that use REST API, e.g. Notakey Windows Credential Provider, Wordpress plugin or your custom user management.
  • Documentation - Link to doccumentation of current version, hosted locally.

Services

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

Manage services

Create a Service

To create a service click on “Create a service”. 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 service. If “Name” contains “VPN” or “Windows” text, images are loaded automatically from builtin resources.

Created services

Onboarding Requirements

Each service 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.

Onboarding requirements

  • 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”
  • Phone Number - 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 “Users” with correct phone number specified. This is because NtkAS will use phone to find the corresponding service user. This requirement can be set in junction with Simple Credentials as the first requirement. When Simple Credentials requirement has been fulfilled, the service 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 Service 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 service has it’s own pool of service 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,   Password,       Email,            Phone,          Full Name,    Enabled,  Teams,    Groups
jdeere,     newPassword,    john@example.com, +37122000000,   John Deere,   yes,     root|beta, Manager|Developer
jameswho,   53cr3t,         james@who.com,    37120000002,    John Who,     yes,     alpha,     Developer
johndoe,    p455w0rd,       john@doe.com,     20000001,       John Doe,     yes,     alpha,     Developer

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 service can have multiple user sources specified. During onboarding process a user will be searched through each of the sources.

Create Active Directory configuration

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 Users with Active Directory. Bind user must have access to all of the potential 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. Filtering will be done on memberOf attribute, CN part of group DN.

User lookup

During onboarding process user lookup happens as follows:

  • NtkAS tries to find it in it’s own “Service 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 service 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 sync user credentials, finds user by full username user@notakey_other.com and ensures that users memberOf attribute contains mandatory_group config parameter.
    • To validate password, NtkAS tries to bind to AD user source with username user@notakey_other.com and user specified password.
    • The user has been found in AD and password validated, so NtkAS stops looking.
  • “Service 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).

Onboarding Activities

Authentication Activities

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

Authentication Activities

Event Auditing

All audit events can be sent using Rsyslog protocol to a specified endpoint. These events should help investigation of any problems user may experience during onboarding or authenticating. All mesages with INFO level indicate normal operations and should be kept for documentation as logs in appliance version are not persistent. WARN indicates authentication failures which should be investigated if in high numbers. ERROR level indicates some unexpected state, possibly due to external resource being unavailabe and have to be looked into. More details about the audit event can be found in standard docker log of container that runs Authentication Server service (e.g. container called dashboard in appliance version). It can help investigation as it contains more details, including basic information about request.

Audit logging feature uses structured logging in JSON format.

Each message contains the following fields:

Field name Description Example
type Describes type of message as explained below AUTH
resource Identifies the affected resource (e.g. user, enrolled device, service) {“id”:“main”,“type”:“EventLogConfiguration”}
actor Identifies who made the change {“source”:“WEB”,“username”:“admin”,“remote_ip”:“192.168.0.11”}
message Text describing event “User updated”

Audit messages can be of the following types:

Type Description
AUTH Authentication request processing
ONBOARDING Onboarding activities
OFFBOARDING User onboarded device removal
CONFIG Service configuration
TESTLOG Test messages from UI
USER User manipulation
DEVICE User device changes
RSAM Remote user source related activities
LSAM Local user authentication activities
ADMIN Administrator session activities
OIDC Open ID Connect provider autentication

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.

New immediate approval authentication policy

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.

New pre-approval authentication policy

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

New approval request

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?

For express license a license is issued when user onboards first device. License is freed when user is deleted. For enterprise license 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 Service User from Active Directory?

Latest information is pulled from AD during onboarding process. To synchronize, press sync in user profile or enable automatic AD sync.