How to install the WiKID Strong Authentication Server

How to install the WiKID Strong Authentication Server

« Return to page index

If you are using the WiKID RPMS, please install the RPMS first. If you are using the ISO or VMWare image, you will need only to configure networking and start the server. To configure networking, simply run:

wikidctl setup
Select that you want to change your network settings. The script will pick up your existing network settings, walk you through them and create an SSL cert for the server. Once done, start the server:
wikidctl start

The primary administration interface of the WiKID Strong Authentication Server is via an HTML 3.2 compliant browser. This allows the server to be managed effectively from a wide range of platforms and network topologies. It also provides a low-bandwidth interface for ease of management from remote locations.

From a network-connected system, enter the URL address:

http://servername.domain.com/WiKIDAdmin/

Substitute your hosts Fully Qualified Domain Name (FQDN) for . The WiKIDAdmin portion of the URL is case-sensitive. You should see a screen similar to that shown in Figure 1.

01.login.screen.jpg

Figure 1 - Initial login screen

The default login credentials are:

Username:	WiKIDAdmin  	(mixed-case)
Password:	2Factor		(mixed-case)

The main system status screen is shown upon successful login to the administration system as depicted in Figure 2. This screen provides summary information about the current stat of the system and the services it provides.

01-homepage-empty.jpg

Figure 2 -Main Status Summary Screen

Each item is covered in greater detail later in this guide. In overview:

Registered Devices – This indicates the number of devices that are currently serviced by this server. These devices have completed the entire registration process and could successfully gain access to a secured resource.

Unregistered Devices – These devices have partially completed the setup process but have not completed the device to userid mapping. Unregistered devices are automatically purged from the system after 1 hour as specified in the RegCodeTTL paramater. This parameter can be changed in Configuration --> Set Parameters.

Served Domains – The number of distinct domains (server codes) configured for this server.

Network Clients – The number of systems that use this server for authentication. This includes both RADIUS systems and other protocols, such as wAuth.

Protocols Enabled – The number of protocol modules installed and activated on the server.

As we progress through this guide, we will periodically return to this status summary to note the changes in the values. This should provide a well founded understanding of the basic terms and concepts of the WiKID Authentication System. If you need additional background, please rewiew the architecture of the WiKID's two-factor system.

Initial installation page

Setting up the WiKID authentication server is quick and easy. You create an intermediate Certificate Authority (CA), install the CA, create a localhost cert, and enable protocol modules. Once this is done, you can add domains, network clients and users.

01-homepage-empty.jpg

Figure 3 - The Initial Administration Page

Setting Up the Certificate Chain

The WiKID system uses certificate authentication internally in several important ways:

  • Each authentication server is also an intermediate certificate authority
  • Each authentication server uses certificate authentication to identify and authorize network clients

These functions require that a certificate be generated before the server is fully functional. This process is accomplished via the server’s administration interface. Select the – Creating an Intermediate CA - tab to access the certificate functions.

 

Step 1: Generate the Intermediate CA

The first step in the process is to generate the Public/Private keys that will be used to identify this server and to asymmetrically encrypt data via SSL. The server ships with a copy of the WiKID corporate CA certificate. This process will generate your keys and produce a certificate signing request or CSR. Select Generate and complete the form as described below.

03-bCreateIntermediateCA.jpg

Figure 4 - Create Intermediate Certificate Authority Screen

This form collects the information needed to generate a Certificate Signing Request (CSR) for this server. NOTE: All fields are required.

Field definitions:

Intermediate CA Administrator Email: This value provides a contact for delivery of the signed certificate. Please ensure this is a valid working email address.

Servers Fully Qualified Domain Name: This should be the server’s official registered name in DNS. SSL clients will expect the name given here to match the hostname that they use to connect to this server.

Organization Unit: Usually the department or division name. Used for identification only.

Organization Name: The name of the company operating this server. This should match the sales or evaluation unit records at WiKID to speed processing of the certificate issuance.

Locality: Generally the city name.

State: The state or province name. By convention this is not abbreviated.

Country Code: The official two-character code for the country. For the United States, this code is US.

Passphrase: This passphrase will be used to secure the private key in a PKCS12 armored file. It will be needed each time you start the server (it replaces ‘passphrase’ as the default passphrase to start the WiKID Server) to ensure the security and integrity of the server credentials. This value is never stored anywhere and cannot be recovered if lost. Select a strong and memorable passphrase and do not lose it.

Select generate to create the keys and the CSR. You should be presented with a screen similar to Figure 5.

04-TheCSR.jpg

Figure 5 - The CSR

The Certificate Signing Request will be provided in base64 DER encoding. Select all of the text in the textbox and copy it to the clipboard.

Step 2: Submit the CSR for Signing

Click on the link to https://ca.wikidsystems.com/wikid/newcertreq.jsp immediately above the text box. This will open the Certificate Signing Request submission page for the WiKID Systems CA.

05-InstallIntermediateCA.jpg

Figure 6 - CSR Submission Screen

Paste your Certificate Signing Request text (including ---- lines) into the area provided and submit for processing.

(Figure 7 removed.)

 

You signed Intermediate Certificate will be returned immediately in the same browser window.   Cut and paste the certificate including the  -----Begin... and End ---- lines:

 

06-theintermediateCA.jpg

Figure 8 – Certificate Block


Note: Please remember that the certificate is useless without the private key generated and secured in step 1. Also, be sure to cut-and-paste the certificate as plain text. Outlook and Gmail will often convert text to UTF-8.

Step 3: Install the Certificate

Once the certificate has been received, return to the certificate management screen via the – Install Intermediate CA - tab. Select the Install option.

08-installCA.jpg

Figure 9 – Certificate Installation Screen

Paste the certificate into the text area provided as shown in Figure 9. Enter the passphrase you used to secure the private key in step 1 and install the intermediate certificate. Note: If you receive an error, double check that the passphrase is correct and make sure you are cutting and pasting as plain text. If you have forgotten the passphrase you will need to return to step 1 and complete the process again.

Step 4: Generate a Localhost Certificate

All systems that communicate directly with the authentication server require a valid certificate issued by that server. Before these clients can access the server you must create a certificate signed by this intermediate CA. This prevents any unauthorized systems from communicating with the authentication server.

It is important to understand that some protocols such as RADIUS (for the Enterprise version), LDAP, wAuth, etc. do not provide facilities for certificate authentication or transport encryption. The WiKID Strong Authentication Server provides protocol modules that transparently convert these protocols into the secure communications required. This in turn means that the LDAP interface on the WiKID Strong Authentication serve requires a certificate to validate credentials even though RADIUS has no concept of certificates.

The protocol modules that run locally on the WiKID Strong Authentication Server itself may share a single certificate for localhost. You can create this certificate by specifying “localhost” as the fully qualified domain name at the generate certificate screen. It must be called “localhost”. This is illustrated in Figure 10.

09-localhostCertificateGeneration.jpg

Figure 10 – Certificate Generation Screen

The values in this form signify the following:

Client’s Fully Qualified Domain Name: This is the name that the server will resolve when a client connection is made using this certificate. For local services it must be “localhost”.

Organization Name: The name of the company operating this client.

Locality: Generally the city name.

State: The state or province name. By convention this is not abbreviated.

Country Code: The official two character code for the country.

Client PKCS12 Passphrase: This is the passphrase that will armor the generated certificate.

Passphrase again: Repeat the Client PKCS12 Passphrase for verification.

Server Keystore Passphrase: This is the passphrase for the intermediate certificate authority that was created in step 1.

Select Generate and you should be presented with a screen similar to Figure 11.

10-PKCSDeliveryScreen.jpg

Figure 11 – PKCS Delivery Screen

This message provides the location of the generated certificate. If this certificate is for the localhost services. It is already installed in the appropriate location.

Step 5: Restart the WiKID Server

Login to the authentication server as root and type:

wikidctl restart

This will shutdown the WiKID Strong Authentication services. You will be prompted for the wAuth passphrase. This is the passphrase you created in step 1 for the intermediate certificate. Entering the correct passphrase will allow the server to begin using the new certificate for client authentication. If you would like to avoid entering a passphrase each time, you can create a file called /etc/WiKID/security with one line: WAUTH_PASSPHRASE=yourpassphrase.

 

 

The certificate infrastructure is the key element in securing communications between the WiKID Strong Authentication server and the network services that require two-factor authentication. Next we will create a WiKID authentication domain.

Creating a WiKID Authentication Domain

The WiKID Authentication System employs the concept of authentication domains. An authentication domain is a segmentation of authentication authority. Any given device using the system can participate in any number of authentication domains. These domains may exist on an individual WiKID Strong Authentication Server or they may exist on separate and discrete servers (or any combination). Conversely, a WiKID Strong Authentication Server may provide authentication services for any number of discrete domains. These domains may be exclusive or inclusive of any set of devices.

An authentication domain is initially defined by the 12-digit code used in device provisioning. This code allows any un-configured, unrelated device to locate and register with a particular WiKID Strong Authentication Server and domain. In practice, the 12-digit code signifies a zero-padded IP address that is Internet accessible. Optionally, it may designate a prefix in the wikidsystems.net domain. For example, a WiKID Strong Authentication Server with the public IP address of 27.232.7.14 would be directly accessible via the 12-digit code 027232007014. Using the wikidsystem.net service, codes signifying non-routable IP addresses may be used, such as 999888777666. You can also alter the DNS settings by deploying a custom jw.properties file with your software token.

Selecting the [Domains] header option will display the current domains served by this WiKID Strong Authentication Server. See Figure 12 below.

11-DomainConfigurationScreen.jpg

Figure 12 – Domain Configuration Screen

Selecting [Create New Domain] on this screen will allow the administrator to establish a new authentication domain for this server. The new domain parameter screen is depicted in Figure 13.

ent-12-DomainConfigurationParameters.jpg

Figure 13 – Domain Configuration Parameters

The required domain configuration options are:

Domain Name – This is a descriptive label for this domain visible only in the administration system.

Device Domain Name – This is the domain label that will appear in the menu option on the client device. This label should be relatively short to facilitate viewing on a mobile device.

Registered URL - LEAVE THIS EMPTY unless you are implementing mutual https authentication. Enter an HTTPS URL here if you want this domain to support mutual authentication. In brief, the WiKID server will fetch the certificate and store a hash of it. When a user requests a one-time password from a PC software token, the token client will also get this hash and URL. Before presenting the one-time password, it will fetch the URL's certificate, hash it and compare the two. If the hashes match, the OTP will be presented and the default browser (if supported) will be launched to the URL. This system will prevent network-based man-in-the-middle attacks.

Minimum PIN Length - This is the minimum allowable PIN length for this domain. Any attempt to set a pin shorter than this value will generate an error on the client device.

Passcode Lifetime – This parameter specifies the maximum lifetime of the one-time passcode generated in this domain. After N elapsed seconds, the one-time passcode will automatically be invalidated.

Server Code – This is the zero-padded IP address of the server or the pre-registered prefix in the wikidsystems.net domain. This value must be exactly 12 digits in length.

Max Bad PIN Attempts – The maximum number of bad PINs attempted by a device in this domain before the device is disabled.

Max Bad Passcode Attempts – The maximum number of bad passcodes entered for a userid registered in this domain before the userid is disabled.

Max Sequential Offlines – The maximum number of times a device may use the offline challenge/response authentication before being required to authenticate online. This feature is used in the Enterprise version for the wireless clients when they are out-of-network coverage.

Use TACACS+ Select this to use TACACS+ for this domain.

After specifying these parameters, select Create to add the domain. Figure 18 indicates the successful creation of the domain.

After adding the domain, select the [Domains] option from the header bar. You should see the new domain listed under Current Domains as in Figure 14.

13-CurrentDomains.jpeg

Figure 14 – Current Domains

Selecting [Main] from the header bar will now indicate that this WiKID Strong Authentication Server is serving the new domain. See Figure 15 below.

14-SummaryScreenafterDomainCreation.jpeg

Figure 15 – Summary Screen After Domain Configuration

 

Your two-factor authentication users will be associated with WiKID domains, which in turn are associated with network clients - those services which require two-factor authentication for access. Now that one domain has been configured, we will focus on configuring protocols such as RADIUS and LDAP and setting up network clients.

Enabling a Protocol Module

Protocol modules enable the WiKID Strong Authentication Server to provide authentication services to various types of network clients. Currently, the Community Edition of the WiKID Strong Authentication Server provides support for LDAP, TACACS+ and wAuth.

The wAuth protocol is the native interface to the WiKID Strong Authentication Server. This protocol uses SSL and certificate authentication to allow distributed (or local) clients to communicate authentication data over an insecure network. The demonstration registration system (/opt/WiKID/tomcat/webapps/WiKIDAdmin/example.jsp or https://servername/WiKIDAdmin/exmample.jsp) uses a Java bean (wClient) to verify user authentication information. See this document on editing this file.

Select the [Protocol Modules] header option to begin the initialization. You will see a list of protocol modules available on this server, as in Figure 16.

ent-17-InitialNetworkClientScreen.jpeg

Figure 16 – Un-initialized Protocols

Note: The wAuth protocol is enabled automatically as no other protocol will operate without it.

Configuring RADIUS

As with the wAuth protocol, RADIUS is supported through the use of a protocol module. You must initialize and enable RADIUS for RADIUS-based devices to communicate with the WAS.

Select the RADIUS protocol to view the initialization parameters in Figure 17.

ent-18-EnableRadius.jpeg

Figure 17 - Radius Configuration Screen

The required parameters for the RADIUS module are:

Host Name – A descriptive label for this protocol module on this host.

IP Address – The IP address where this module will be accessible.

Port – The port number this protocol will bind with (the standard RADIUS port is 1812 UDP).

Multihomed – Select if this module should listen for connection on every network interface.

Debug Level - The debug level for logging events for this protocol.

Use Accounting – Indicates whether RADIUS accounting will be turned on.

Accounting Port – If RADIUS accounting is to be used, the port that the RADIUS accounting listener will run on (standard is 1813).

Restrict Network Clients – Deprecated, network clients MUST be restricted; an unknown/unregistered network client is unsupported. This value in not used and will be removed in a future version of the server.

Password Encoding – the encoding type for passwords passed by a network client.

Secret Encoding – the encoding type for the shared secret passed by the network client when the network client communicates with the RADIUS protocol module.

In general, you do not want to change any of these choices unless you really know what you are doing.

Enable the RADIUS protocol by clicking on the “Enable” link.

Note: You must stop and start the WiKID server after enabling the RADIUS protocol. Login to the authentication server as root and type “wikidctl stop”. This will shutdown the WAS services. Once the services are stopped, type “wikidctl start” at the command prompt. You will be prompted for the wAuth passphrase. This is the passphrase you created in step 1 for the intermediate certificate. Entering the correct passphrase will allow the server to begin using the new certificate for client authentication.

When using RADIUS, you must include the shared secret in the protocol specific section of the configuration when you create the Network Client later in the set up process. Without a shared secret for the network client AND on the network client, RADIUS communication will not function properly.

You may also include specific return parameters in the form in the Return Parameters text area. To support multiple parameters, put each on a separate line. For example, if you want to specify an idle timeout of 1 minute for the session, you may include the parameter as follows:

Idle-Timeout=60

This text area accepts all standard RADIUS settings as detailed in RFC 2865. Through this text area you can support AppleTalk and other protocols. Future releases of the WAS will make this task easier for common parameters. IMPORTANT: This text area is NOT required. If nothing is included in this text area, TCP/IP will be supported by default.

NOTE: the RADIUS protocol module accepts the following RADIUS encoding types: PAP, CHAP, MSCHAP and MSCHAPV2.

RADIUS network clients vary greatly from vendor implementation to vendor implementation. Please refer to your vendor’s documentation for configuring your network client to use RADIUS.

Enabling the LDAP Protocol

Click on the LDAP protocol on the Enable Protocols page to bring up the the Enable LDAP page. The required parameters for the LDAP module are:

LDAP_wauth_host: IP address of the WiKID Server that will validate LDAP bind requests (always 127.0.0.1)

LDAP_wauth_kfile Location of the Network Client cert for LDAP access to the WiKID Server (usually /opt/WiKID/private/localhost.p12)

LDAP_wauth_pass Passphrase for the Network Client cert above.

LDAP_wauth_port Port the WiKID server is listening on (usually 8388) NB: LDAP will actually listen on port 10389

LDAP_wauth_server 12-digit code for the domain LDAP will check bind requests against

Once complete, click Update

Creating Network Clients

Network clients are systems that request one-time password validation from a WiKID Strong Authentication Server. These systems act in a proxy capacity, accepting questionable information from users and communicating with the WiKID Strong Authentication Server for validation. Network clients utilize one of the installed protocol modules. The protocol module must be installed, initialized and enabled before you can configure add a network client for it.

Each network client must be configured on the WiKID Strong Authentication Server before it will allow the client to request validation. For wAuth clients, this will require the generation of a certificate for the network client. The exception is the localhost client that is pre-installed by default. You may (and should) regenerate this certificate, as well as any remote client certificates, on a periodic basis. Figure 18 shows the initial network client screen.

17-InitialNetworkClientScreen.jpeg

Figure 17 - Initial Network Client Screen

Select – Create new Network Client - to begin adding a network client. You will be presented with a screen similar to Figure 19 below.

18-NetworkClientProperties.jpeg

Figure 19 - Network Client Properties Screen

These are the general network client properties. These values are required for each network client configured, regardless of the protocol selected. Property definitions are:

Name – The descriptive name of the server. This will be the primary display name in the administrative system and in system logs and reports. It is recommended that you use a combination of hostname, and WiKID domain for clarity.

IP Address – The IP address of the network client.

Protocol – The communications protocol used by this network client. Only protocols previously enabled will be available. The protocol selection will dictate the additional properties that must be defined for this client.

Domain – This is the WiKID authentication domain in which this client will request credential validation.

If you are creating a Wauth network client, you will need to create a Certificate for the network client. Complete the required information as shown in Figure 20. Note the the network doesn't require a routeable Fully Qualified Domain Name. It is acceptable to use a computer name or a nickname such as “www” or “extranet” rather than “vpn.wikidsystems.com” or “extranet.wikidsystems.com”.

19-CreateNetworkClientCert.jpg

Figure 20 – Creating a Certificate for a Wauth Network Client

If you are creating a RADIUS network client, you will need to enter a shared secret. You may also enter additional parameters as discussed above.

ent-19-RadiusNC.jpeg

Figure 21 - Creating a Radius Network Client - Page 2 - Setting the shared secret.

We have now configured a two-factor domain, enabled authentication protocols and created network clients. All that remains is to enable users for two-factor authentication and test.

User Management

Now that you have created a Domain and a Network, client you will need to set up Users to test the system. We will manually configure a user. Of course, one of the major benefits of using WiKID is the automated initial validation system. We provide you with example scripts that show how your users to easily configure WiKID themselves.

First, click on the Users tab.

20-UserManagementPage.jpg

Figure 22 – The main User Management Screen

Start your WiKID software token on your PC ($ java -jar jWiKID.x.x.x.jar for example) and enter the domain code as in Figure 21 (the J2SE client isa shown here).

21-Userentersdomaincode.jpg

Figure 23 – Enter the Domain Code

You will be prompted to enter and verify a PIN.

22-UserCreatesPIN.jpg

Figure 24 – Enter your PIN

You will receive a Registration Code back. This code is only used once during the initial validation process.

23-WASreturnsRegistrationCode.jpg Figure 25 – The initial validation Registration Code

On the WiKID User Management screen, click on Manually Validate a User and you will see the registration code listed. By default a registration code can be validated anytime within 24 hours after it is created. The administrator can control this lifetime by changing the UnRegDeviceTTL value in the Parameter Settings (it is listed in minutes). Click on the registration code.

24-RegistrationCodeonWAS.jpeg Figure 26 – Manually Validating a User

Once you have selected the correct Registration Code, enter the appropriate user name as shown in Figure 25.

25-Adminentersusername.jpeg

Figure 27 - Enter the User name

Returning to the main User Management screen will show the validated user.

26-NewuserinWAS.jpeg

Figure 28 – One user is validated

Testing One-time passcodes on the WiKID Strong Authentication Server

Just to make sure that wAuth is working using the localhost certificate, we will edit the previously mentioned example.jsp and login with a one-time password. On the terminal of the WiKID server, edit the file with your preferred editor:

vi /opt/WiKID/tomcat/webapps/WiKIDAdmin/example.jsp

Edit line 47 and change defaultservercode  from '127000000001' to your WiKID server domain code and line 52 changing the localhost passphrase from 'passphrase' to your passphrase.  You may need to restart WiKID for the changes to be cached.  Once saved, browse to https://servername/WiKIDAdmin/example.jsp. If you are not logged in, you will need to login as the WiKIDAdmin administrator. You page should look like this:

27-example.jsp.jpg

Figure 29 - The example.jsp page

Enter the username you just added to the WiKID Strong Authentication Server in the Username box under Online Login. Get a one-time password from your token client, enter it into the Passcode box and hit Check Online. If you are authenticated, you should see Success at the top of the subsequent page.

Congratulations. You have now configured the Community Version of the WiKID Strong Authentication Server. The WiKID Strong Authentication System is a dual-source two-factor authentication system. For more information on what you can do with WiKID, please visit the WiKID Website.

From here, you can see our extensive collection of documents on adding two-factor authentication to a variety of services and VPNs and once you are ready, please purchase seat licenses online.

Join our email list
How do I add two-factor auth?

Download a registration-free free eGuide on How to Add Two-factor Authentication to Your Network, complete with examples.

    Thanks for responding so fast! Great service.

    INFOSEC PRO
    SAN DIEGO, USA