How to install the WiKID Strong Authentication Server

How to install the WiKID Strong Authentication Server

« Return to page index

Now that you have installed WiKID, it's time to configure it.  Start by running our script that configures or confirms your network settings and creates an SSL certificate for the WiKIDAdmin web UI.

wikidctl setup

Select that you want to change your network settings.  We HIGHLY recommend you run through this and confirm your settings.  The script will pick up your existing network settings, walk you through them and create an SSL cert for the server.  Select No for replication at this time.  Once done, start the server:

wikidctl start

The primary administration interface of the WiKID Strong Authentication Server is via the WiKIDAdmin web UI.

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

https://servername.domain.com/WiKIDAdmin/

Click through your browsers warnings about the self-signed certificate.  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 status of the system and the services it provides.  You can ignore the License Restrictions error - we'll deal with that.

First screen

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.   These are your VPNs, RADIUS servers, etc.

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 review the architecture of the WiKID's two-factor system.

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.
  • We use certificate extensions to manage user licensing and subscription terms.

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.

Configuration tab

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.

Create CSR 2

This form collects the information needed to generate a Certificate Signing Request (CSR) for this server. NOTE: All fields are required and the request must be unique (minor changes will create a unique request).

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.

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 the Cert Management Server immediately above the text box (This URL may have changed).  This will open the Certificate Signing Request submission page for the WiKID Systems Certificate Management Server.  We'll be getting a 30-day Evaluation Certificate.

eval cert

Click on the Enter Evaluation Data link. A box will appear. Paste your CSR into it.

paste_csr

Click Generate/Extend Certificate.  You will get back the Evaluation license.  Click Select Certificate Text and right click/copy the cert.

get eval cert

Step 3: Install the Certificate

Back on the WiKID server, click on the link to Install the Intermediate Certificate.  Paste the cert into the box and enter the passphrase.

install cert

Click Install.

cert installed

While it says to restart, we're going to do a bit more configuration and then restart.

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 below.

create localhost

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 this:

succes

This message provides the location of the generated certificate.

Step 6  Enable Protocols

Click on the link to Enable Protocols.  NEW: note that since 99% of our deployments use only Radius, we have enabled it by default.  You can skip this step.  We recommend against enabling LDAP or any unused protocol.

protocols

Click on the Radius link

radius

Make no changes to this page at this time.  Click Initialize.

radius enabled

Success.  We're almost there!  Next we will setup domains and network clients.

 

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.

Note that the tokens need to be able to connect to the WiKID server on port 80 (no need for SSL as we use asymmetric encryption).  Your server can be NAT'd, but use the external IP for the domain identifier.

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

domain page 1

Selecting [Create New Domain] on this screen will allow the administrator to establish a new authentication domain for this server.

edit domain

Click Create.  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.

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.  This field cannot be edited.  You can delete and create new domains.

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.  Do not select this unless you know what you are doing.

Token Types: You can limit the types of token your users can have. For now, leave it as Allow All Token Types.

Mutual HTTPS Auth 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.

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.

domain created

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.

Configuring RADIUS

We enabled the RADIUS protocol after creating the certificates. Now we will create a Network Client that uses it.  Note that WiKID is not a "RADIUS server" like NPS or Freeradius , but it talks the protocol and in the language of RADIUS it is a "server" to "clients".  A client could be your RADIUS server.

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.

Network Client

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

Network Client 2

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 RADIUS network client, you will need to enter a shared secret. You may also enter additional parameters as discussed above.

radius network client

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.

Note:  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”.

Wauth NC

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.

users tab

Start your WiKID software token on your PC ($ java -jar wikidtoken.x.x.x.jar for example) and enter the domain code you created earlier.

21-Userentersdomaincode.jpg

Enter the Domain Code

You will be prompted to enter and verify a PIN.

22-UserCreatesPIN.jpg

Enter your PIN

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

23-WASreturnsRegistrationCode.jpg 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 any time 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.

reg user

Once you have selected the correct Registration Code, enter the appropriate user name (that - not 'username' ;-).

reg user 2

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

user listed

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:

vim /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

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

Ever since deploying WiKID, we  have  secured our Production systems from unauthorized access and maintained PCI compliance