Alified Authentication Server

This documentation applies to Alified Authentication Server v.1.8.1

Table of Contents

• Alified Authentication Server
  • Table of Contents
  • Requirements
    • Supported hypervisors
  • Quick start
  • Appliance configuration and usage
    • Dashboard
      • Top row
      • Appliance status line
      • Authentication metrics
      • Real time activity
    • Users
      • User card
      • Tags
      • Local users
      • Import users
      • Add local user
      • List all users
    • Logs
    • Licensing
    • Appliance management
      • Restore a configuration backup
      • Reboot Appliance
      • Restart server daemons (services)
      • Backup configuration
      • Change local admin Password
      • Update appliance FW
    • Settings
      • General settings
      • User Portal settings
      • Network settings
      • HA settings
      • LDAP backend settings
      • SMS providers
        • JSON REST with header basic auth
        • HTTP POST
        • HTTP GET
        • Other SMS Settings
      • Mail settings
      • BankID settings
        • BankID
        • CGI
    • MFA
      • Manage HW/SW tokens
        • Add new HW/SW token
      • Manage grids
      • RADIUS clients
      • RADIUS daemons
      • SQL backend settings
        • SQL Query
      • WebAuth settings
        • WebAuth request format
        • WebAuth response format
      • API settings
    • SSPR
      • SSPR settings
  • Self Service Password Reset
    • Password Change
    • Password Reset
  • End User Portal
  • REST API
  • ADFS Plugin
  • Guides
    • First time setup
      • Configure using the appliance console
      • Configure using the appliance web GUI
      • BankID and RADIUS

Abrevations

Thru out the documentation, the following abbreviations are used:

Requirements

AAS is build to be utilizing as few resources as possible. However, the use of the different features will require more or less resources in form of CPU and RAM. The default configuration with 1 CPU and 1GB RAM will support < 50.000 MFA users (RADIUS and ADFS adapter). Activating the EUP and SSPR features increase the load on the appliance and might depending the amount of traffic need additional CPU and RAM resources. The default configuration with a single node will probably support at least 10.000 ADFS / SSPR users but this has baselined in each environment.

The time out setting for the administrative portal is 30 minutes.

To set up a two node cluster, the nodes must be able to communicate using TCP port 3306 as destination port.

Supported hypervisors

AAS supports the following hypervisors:

• VMWare ESX/vSphere > 5.0.0
• Citrix Hypervisor (aka. XenServer) > 6.2
• Microsoft HyperV > 2012
• Azure

Quick start

To get up and running in a short time, the basic steps is to:

1. Import the appliance to your hypervisor of choice.
2. Configure network settings using the hypervisor console ot web based GUI. Don't forget to configure at least one working NTP server.
3. Aquire a license from your Alified representative by supplying the HostID of a single or master node.
4. Apply the license code.
5. Verify General settings and enter a Appliance LDAP admin group.
6. Configure LDAP backend settings.
7. If you want to enable the mail based daemon, Google Authentication code distribution using email and/or administrative email alerts, complete the Mail settings configuration.
8. Configure and enable at least one RADIUS daemon.
9. Add one or more RADIUS clients.
10. Configure at least one user to use the configured authentication method or methods.

Appliance configuration and usage

Log on to the administrative portal by accessing one of the appliances using http://[ip-address] or https://[ip-address] of the appliance. The ip-address can be found using either the hypvervisor console or the virtual console of the Alified VM.

Dashboard

The dashboard displays an overview of the current authentication metrics as well as some appliance and cluster status. All metrics on the dashboard but the Authentication metrics graph are updated every 10 seconds.

Top row

The top row displays appliance status, current used and available licenses, successful and failed logins. You can go directly to the full log by clicking on any of the green (success) or red (failed) boxes.

Appliance status line

The appliance status line displays the local appliance status metrics as CPU load, memory and disk usage. It also displays the time collected from the current appliance which can be usable since all time based authentication methods as Google / Microsoft Authenticator and hardware and software tokens are time sensitive.

Authentication metrics

The Authentication metrics frame displays a graph of authentication success rate. The displayed time frame can be adjusted using the drop down box at the top right of the frame.

Real time activity

The Real time activity frame displays the last 10 log entries.

Users

To support a lot of different usage scenarios, AAS can fetch user information from different sources.

• Local users
• LDAP users
• External database users
• WebAuth users

NOTE When deleting a user, ALL log entries liked to that user will also be deleted.

The Users menu allows you to perform user based operations. The search field searches both the local database as well as the LDAP backend.

User card

The user card is displayed when a users is searched for or opened by using the edit button in the List all users table. In the user card, and administrator can change which MFA features a user will have access to as well as entering tags or delete the user from the local database.

The header of the user card will state if the user account is a local only user or fetched using LDAP.

If Authenticator is enabled, an administrator can download a .PDF file or choose to send the same .PDF with enrollment information to the user using e-mail. This requires that e-mail settings is configured and that the user has an e-mail address specified or fetched using LDAP.

Tags

A user can have one or more tags to be used to group users. The tags field a free text field and tags can be entered in any formate suitable.

Local users

Local users are stored in the local database of the appliance(s). Local users don't validate to a back end user source and can be used to supply an "island" authentication source using the supported authentication methods.

Import users

It is possible to import a list of user and optional automatically enable Authenticator for all imported users.

Note that there is a link to a sample .CSV file at the bottom of the page.

Add local user

A local user can be added using the Add local user button in the Users menu.

NOTE A local users doesn't have a "normal" password. A local users expects to use the generated MFA as password.

When adding a local users, the only mandatory field is the username.

List all users

The List all users button opens a searchable list of all users registered in the local database.

The Show Authenticator keys button makes the Authenticator seeds for the currently visible users.

Logs

Using the logs menu selection, an administrator can access the detailed authentication logs. You can step thru the different log pages as well ass search to complete log database using the search bar.

Licensing

To enable the different features of AAS, you need to install a valid license key. You can add as many license keys as you want. The total amount of licenses for each feature will be aggregated. If the appliance cannot find a valid license, all services are stopped.

NOTE If AAS services is stopped due to missing licenses, it can take up to one minute for the appliance to detect the new license and start it's services.

All license keys are linked to the Host ID that are displayed in the Licensing menu selection. The Host ID is unique for each AAS node.

Licensing are applied to the Master node in a HA setup. The Slave node will piggy back on the master nodes licenses and no additional licenses are required to run a active active cluster setup.

To ass a new license, press the Add new button and enter the license key you have received.

NOTE Until a valid license is installed, there will be limited menu options available.

Appliance management

Restore a configuration backup

Here you can restore a previous downloaded backup archive.

NOTE Restoring a backup completely reverts all configuration, user settings and logs to the point of when the backup was created!

Reboot Appliance

This reboots the entire appliance.

Restart server daemons (services)

Restart all services including RADIUS and HTTP / web services.

Backup configuration

Create and download a backup archive.

Change local admin Password

Change the local admin account password.

Update appliance FW

Upload and apply a new firmware. Make sure to apply this to the master node first.

Settings

The settings menu contains sub menus with settings which is common for all or most features of the appliance.

General settings

User Portal settings

This menu controls the End User Portal settings.

NOTE You cannot use the same ports for the EUP as the administrative portal.

Network settings

HA settings

AAS can be configured in single mode or in a two node active / active cluster. All state, user and log information is replicated in real time between the both nodes in cluster setup so there is no need to configure persistence in a load balanced setup.

In a cluster setup, only the master node has to be licensed. The Slave node uses the licenses of the Master node.

To configure HA between two nodes:

• Choose which node that should have the Master node and set it's role to master.
• Enter the hostname (can be either the short name or FQDN) of the Slave node.
• Enter the ip-address of the Slave node.
• Save the configuration.

Head over to the slave node and:

• Set it's role to slave.
• Enter the hostname (can be either the short name or FQDN) of the Master node.
• Enter the ip-address of the Master node.
• Save the configuration.
• Press the Intialize Slave button.

The Slave node now fetches information from the Master node and if successful, the HA Status on both the Master and Slave node till state HA initialized.

If the HA Status don't states HA initialized, please make sure the both nodes can communicate over TCP 3306.

LDAP backend settings

AAS uses LDAP over TCP port 389. There is an option to disable TLS but we strongly advice against it.

NOTE You can only use ONE ip-address for LDAP server.

SMS providers

AAS uses external SMS service providers to send OTP's using text messages. These providers are accessed using a HTTP(s) calls.

Each SMS prover is assigned a weight value. Providers with the same value will be accessed in a round robin scheme and if more than one provider is configured but with different weight values, the providers will be access in a failover scheme where to lowest value will be more preferred than a higher value.

You add provers by pressing the Add new button a the SMS providers menu. From the SMS providers menu, you can add, edit and delete SMS providers.

JSON REST with header basic auth

This provider type sends a JSON payload with the username and password. It authenticates to the API using a basic header bearer. This method is used by for example Generic Mobile.

POST data

• URL Path: /SmsGateway/api/v1/Message
• Auth header: Authorization - Basic [base64 encoded username:password]

JSON payload

{
  "From":  "[username]",
  "To": "[phone number]",
  "Text": "[OTP Text]",
}

HTTP POST

When configuring a HTTP POST provider, you configure the field names that the API endpoint expects.

HTTP GET

When configuring a HTTP GET provider, you configure url query parameters that the API endpoint expects.

Other SMS Settings

The Other SMS Settings frame displays generic SMS configuration parameters.

Mail settings

Configure mail setting to be able to send enrollment information to users, administrative messages and usage reports.

BankID settings

The settings in the BankID settings menu are specific the Swedish BankID service.

BankID

When using the native BankID API, you will be provided with two authorization certificates. The certificates for the test environment is common for all customers but you will have to upload your certificates used for production. The certificates has to be in .PEM format and without a key password.

CGI

MFA

Using the MFA menu, an administrator can configure all MFA specific settings.

Manage HW/SW tokens

Using the Manage HW/SW tokens menu, you can manage user hardware and software tokens.

Unassign releases a token from a user and makes it available for assignment to another user.

Delte completely removes the token from the token database.

Add new HW/SW token

Using the Manage HW/SW tokens menu you can manually add hardware and / or software tokens. By pressing the Add new you can enter the token information or using the button Generate SW token to create a new software token with a random seed.

NOTE Make sure to select the correct token Type.

Manage grids

Grid tokens are generated in advance and then assigned to end users. By pressing Add new, you will be able to enter the number of new grids to create.

In the Grids frame, an administrator have the option to unassign a grid from a user as well ass completely remove a grid from the grids database or download the grid as a .PDF document.

RADIUS clients

RADIUS daemons

From the RADIUS daemons menu, an administrator can configure which MFA methods that will be available and optionally set the listening port for each of them.

SQL backend settings

AAS can do backend authentication using a native SQL query to an external Microsoft SQL or mySql / MariaDB database.

SQL Query

The SELECT query must return a single line with the following column names:

The SELECT query takes one single input which is the username. Insert the username in the SELECT query as $username.

WebAuth settings

AAS can do backend authentication using a WebAuth based API. WebAuth uses JSON payloads for both request and response.

WebAuth request format

{
  "auth":
    {
      "username": "[username]",
      "password": "[password]"
    }
}

WebAuth response format

The result key must be accept for a successful authenticaton and reject for a failed authentication.

{
  "authresponse":
    {
      "result": "",
      "email": "",
      "mobile": "",
      "phone": ""
    }
}

API settings

Using the API settings menu, and administrator can configure API settings.

SSPR

The SSPR menu is used to configure SSPR features.

SSPR settings

Self Service Password Reset

AAS has two different features for user self service password reset.

• Password Change
• Password Reset

All SSPR features requires the LDAP service account to have rights to change other users password

Password Change

Password Change is a feature which allows end users to change their password using a web based portal as long as they still know their current password.

The Password Change feature is available on the same IP address and port as the administrative portal (80, 443). The URL to the Password Change feature are: /pwd/change

Password Reset

Password Reset is a feature which allows end users to reset a lost password using any of the configured MFA methods supported by AAS. The URL for Password Reset is available at: /pwd/reset and are using port 82 (unencrypted) and 8444 (encrypted).

End User Portal

The End User Portal is a web portal where the end users can enroll configured MFA features them self. The EUP is optional and is configured at Settings/User Portal settings.

The EUP defaults to a forms based login page. It will also accept login using the following methods:

• HTTP Basic

  • Use: username and password as logon parameters.

• POST

  • Use: username and password as POST fields.

• GET

  • Use: ?username=[username]&password=[password] as get parameters.

REST API

AAS has a API that can be used to interface the Appliance and integrate it with other services.

The API is accessible on the same ip-address and port as the administrative portal (80, 443) and the base path is: /api/v1

The API has it's own documentation which is available at /api/v1/docs

NOTE Currently, only the public unauthenticated parts of the API is accessible. The ADFS PLugin uses ip whitelisting to provide the best performance possible.

ADFS Plugin

AAS comes with an ADFS plugin which can be installed in an ADFS infrastructure to allow the use of Alifieds MFA methods and configuration.

To be able to use the plugin, configure AAS using the MFA/APIsettings menu to allow specified ADFS server to use the plugin with your AAS environment.

When installing the ADFS plugin, it will ask you for a server address. This is the ip-address or server name of the AAS server or in a cluster setup, a load balanced ip / vip of the AAS nodes.

The ADFS plugin reads the user configuration for each user at logon and presents the available MFA methods.

Guides

First time setup

Importing the virtual appliance

VMware

1. Download and unzip the installation package.
2. Choose to import .OVF and import the appliance to you environment.

Citrix Hypervisor

1. Download and unzip the installation package.
2. Choose to import .XVA and import the appliance to you environment.

Microsoft HyperV

1. Download and unzip the installation package.
2. Choose to import .VMDK and import the appliance to you environment.

When you have imported the appliance to your hypervisor of choice, you have two options.

1. Access the appliance console using the hypervisors admin console.
2. Access the appliance web GUI using it's ip-address acquired using DHCP. (IF DHCP isn't available on the attached network, the only option is to use the appliance console). NOTE NTP configuration is crucial for reliable Google Authenticator, Software token and TOTP hardware token support.

Configure using the appliance console

1. Log on to the console using the setup user and password:
2. Console setup user: setup
3. Console setup password: alifiedotp
4. You will be presented with a setup menu where you can configure the appliance network settings.
5. Remember to save the config and reboot the appliance to apply the new settings.
6. When the appliance has finished rebooting, all other configuration is made using the web based GUI.

Configure using the appliance web GUI

1. To be able to perform the first time setup using the web GUI, the attached network must have DHCP available.
2. Get the appliance ip-address from your hypervisors console.
3. Access the web GUI byt the appliance ip-address (http://a.b.c.d).
4. Log on to the web GUI using the default appliance username and password:
5. Web GUI default username: admin
6. Web GUI default password: alifiedotp
7. Access Network Settings under the Settings menu and complete network configuration.
8. Reboot the appliance to enable the new settings.

BankID and RADIUS

Using BankID as MFA requires some specific considerations.
A RADIUS server normally responds to a authentication request within a few milliseconds or in worst case seconds. BankID by nature works in an other way.
When using BankID over RADIUS, the authentication request are sent to the server which then waits for the BankID backend to report if the authentication was successful or not. This means that you have to configure the RADIUS client to have a long time out (60-90 seconds is usually a good value) and to not send any retries.