YubiRADIUS Virtual Appliance. Configuration and Administration Guide Software version: 3.6.0 Document version: 1.0

YubiRADIUS Virtual Appliance Configuration and Administration Guide Software version: 3.6.0 Document version: 1.0 December 14, 2012

Introduction Disclaimer Yubico is the leading provider of simple, open online identity protection. The company s flagship product, the YubiKey, uniquely combines driverless USB hardware with open source software. More than a million users in 100 countries rely on YubiKey strong two-factor authentication for securing access to computers, mobile devices, networks and online services. Customers range from individual Internet users to e-governments and Fortune 500 companies. Founded in 2007, Yubico is privately held with offices in California, Sweden and UK. The contents of this document are subject to revision without notice due to continued progress in methodology, design, and manufacturing. Yubico shall have no liability for any error or damages of any kind resulting from the use of this document. The Yubico Software referenced in this document is licensed to you under the terms and conditions accompanying the software or as otherwise agreed between you or the company that you are representing. Trademarks Yubico and YubiKey are trademarks of Yubico Inc. Contact Information Yubico Inc 228 Hamilton Avenue, 3rd Floor Palo Alto, CA 94301 USA info@yubico.com YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 2 of 68

Contents Introduction... 2 Disclaimer... 2 Trademarks... 2 Contact Information... 2 1 Document Information... 5 1.1 Purpose... 5 1.2 Audience... 5 1.3 References... 5 1.4 Version... 5 1.5 Definitions... 5 2 Introduction... 6 3 What s New... 8 4 Pre-Requisites... 9 4.1 One or more YubiKey(s)... 9 4.2 Active Directory or OpenLDAP server... 9 5 Configuration... 10 5.1 Downloading the YubiRADIUS VMware virtual appliance... 10 5.1.1 OVF... 10 5.1.2 VMware... 10 5.2 Configuration of the YubiRADIUS VMware virtual appliance... 10 5.2.1 Adding domains to the Yubico Virtual Appliance management... 11 5.2.2 Setting up the Global configuration parameters... 12 5.2.3 Importing users to the domain... 25 5.2.4 Defining User Group Hierarchy... 29 5.2.5 Importing YubiKeys to YKKSM database or YubiHSM... 29 5.2.6 Enabling Auto-provisioning mode for the domain... 30 5.2.7 Enabling YubiApp Registration... 31 5.2.8 Enable Gradual Deployment... 31 5.2.9 Return user s Group Membership information in RADIUS response... 32 5.2.10 Adding RADIUS clients to the Domain... 33 6 Testing the configuration... 35 6.1 RadTest:... 35 6.2 Validate OTP:... 38 6.3 Ping:... 38 YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 3 of 68

6.4 Common Troubleshooting Steps... 39 7 Users and YubiKey Management... 41 7.1 Enable YubiKey... 41 7.2 Disable YubiKey... 41 7.3 Unassign YubiKey... 42 7.4 Delete User... 43 7.5 Display Users/Group hierarchy:... 44 7.6 Assign Temporary Token:... 44 7.7 Set Users to Single or Two Factor Authentication... 46 8 Reports... 48 8.1 On-Demand Report... 48 8.1.1 YubiKey Assignment... 48 8.1.2 Authentication Request... 48 8.2 Sample report... 49 9 List YubiKeys Tab... 51 10 Appendix 1: Security Considerations... 52 11 Appendix 2: Using YubiHSM... 53 11.1 Configure the YubiHSM:... 53 11.2 Configure YubiRADIUS Virtual Appliance:... 54 12 Appendix 3: Using LDAPS... 56 12.1 Setting LDAPS for YubiRADIUS Virtual Appliance:... 56 13 Appendix 4: Importing Users from Active Directory/OpenLDAP... 57 13.1 Importing Users from Active Directory:... 57 13.2 Importing users with a specific group membership:... 61 13.3 Importing users from multiple groups:... 61 14 Appendix 5: Web API... 63 15 Appendix 6: YubiApp Registration... 64 16 Appendix 7: YubiRADIUS Virtual Appliance Port Information... 68 YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 4 of 68

1 Document Information 1.1 Purpose The purpose of this document is to guide readers through the configuration steps to enable two factor authentications with YubiKey and RADIUS server through the YubiRADIUS virtual appliance provided by Yubico. This document assumes that the reader has advanced knowledge and experience in Linux system administration, particularly how to configure PAM authentication mechanism on a Linux platform. This configuration guide focuses on configuration of FreeRADIUS demon for user authentication using Active directory (AD) or OpenLDAP server. 1.2 Audience This document is intended for technical staff of Yubico customers who want to deploy the YubiKey for securing access to corporate resources via technologies such as Remote Access service or VPN. 1.3 References Part of the Yubico YubiRADIUS solution is based on the Open Source FreeRADIUS and Webmin software. 1.4 Version This version is released to the Yubico community for the usage of Yubico's YubiRADIUS virtual appliance to provide the YubiKey- based two factor authentication primarily for remote access technologies(such as VPN). 1.5 Definitions Term YRVA VPN SSL RADIUS PIN OTP YubiKey ID AD LDAP Definition Yubico s YubiRADIUS Virtual Appliance Virtual Private Network Secure Sockets Layer Remote Authentication Dial In User Service Personal Identification Number One Time Password The 12 character (48 bit) public identifier of a YubiKey Active Directory Lightweight Directory Access Protocol YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 5 of 68

2 Introduction Yubico is a security company founded in 2007, with offices London and Stockholm Sweden, as well as in North America, located in Palo Alto California. Yubico s mission is to make Internet identification secure, easy, and affordable for everyone. To meet that mission, Yubico offers a physical authentication device/token, the YubiKey, to provide users secure authentication to web services and various other applications. The YubiKey device is a tiny key-sized, one-button, authentication device, emulating a USB keyboard. The YubiKey is designed to generate a unique user identity and a one-time password without requiring any software installed on the host computer. When YubiKey is inserted to a USB port on a computer and the illuminated button on the device is pressed, YubiKey sends an OTP (One Time Password) to the computer as a sequence of keyboard characters, thus freeing the user from having to manually type in the one-time password/passcode. Customers utilizing YubiKeys have two options for validation of the YubiKey OTPs. The YubiKey SDK is able to directly provision and verifies OTPs locally. Further, customers have the option of configuring the Yubico web API to verify OTPs online (over the internet) using the YubiCloud Validation Service. In order to provide a reliable online service to its customers, Yubico hosts its servers in highly secure hosting facilities for the critical OTP validation servers. Many organizations utilize the powerful and flexible authentication mechanism provided by the RADIUS protocol. A RADIUS server combined with an industry standard VPN or SSL based VPN access point forms a robust and easy solution for remote access. However, in all secure remote access scenarios a two factor authentication is highly recommended. Yubico provides a FreeRADIUS based remote access solution YubiRADIUS for providing strong two factor based authentication i.e. username + PIN/password + YubiKey OTP. The YubiRADIUS solution supports multiple domains. Each domain configuration works independently and has its own configuration settings. In order to make it easy for customers to quickly deploy a solution Yubico provides a ready to deploy YubiRADIUS VMware based virtual appliance. The ready to deploy VMware virtual appliance contains: FreeRADIUS Server Yubico OTP validation server (YKVAL and YKKSM server or YubiHSM) Webmin server Yubico YubiRADIUS Webmin module Username-YubiKey ID mapping service (YkMap service) AD/LDAP Username and password authentication mechanism YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 6 of 68

YubiRADIUS - Virtual Appliance Free Radius Yubico FreeRADIUS Plug-in Module UID - YubiKey Mapping & Database RADIUS Protocol Cisco ASA Or other Radius Equipment Management Webmin OTP/PW Separator OTP via YubiCloud OR Internal YubiCloud PW via LDAP Int. OR Ext. OpenLDAP *(Optional Internal) YK-VAL Validation Server YK-KSM Key Server Organization s Active Directory Optional - YubiHSM HSM (Hardware Security Module) for Additional Key Protection Overview Diagram YubiRADIUS VA The following diagram illustrates a sample deployment scenario for the YubiRADIUS solution in an organization having two internal domains: YubiCloud Online Validation Service Internet Yubico Local Validation Server YubiRADIUS Virtual Appliance Admin UI based on Webmin OR Yubico WebService API Yubico YubiRADIUS Virtual Appliance RADIUS LDAP RADIUS RADIUS Client Domain1 LDAP/AD Server RADIUS Client YubiRADIUS Virtual Appliance VM Image LDAP Domain2 LDAP/AD Server YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 7 of 68

3 What s New This section lists important additions to YubiRADIUS Virtual Appliance version 3.6.0 compared to its predecessor: 1. YubiRADIUS Virtual Application 3.6.0 includes support for Radius Access Challenge request, allowing for Username/Password & YubiKey Validations in separate requests. 2. Implements Gradual deployment of YubiKeys, allowing users to continue using single factor until being assigned a YubiKey. 3. With Gradual Deployment enabled, the YubiRADIUS Virtual Application 3.6.0 provides controls to allow Administrators to have users temporarily bypass YubiKey Authentication. 4. YubiRADIUS Virtual Application 3.6.0 can be configured to return highest privilege AD/LDAP groups for users as defined by administrator. 5. YubiRADIUS Virtual Application 3.6.0 can assign the same YubiKey to different users in different domains, allowing one YubiKey to access accounts across different domains. 6. YubiRADIUS Virtual Appliance 3.6.0 comes up with latest OS and related software updates. 7. Additional Bug fixes from the previous version. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 8 of 68

4 Pre-Requisites Before using the YRVA, you will need the following: 4.1 One or more YubiKey(s) For more information regarding YubiKey, please visit the following link: http://www.yubico.com/products/yubikey/ 4.2 Active Directory or OpenLDAP server Yubico YubiRADIUS virtual appliance (YRVA) server supports username and password authentication with Active Directory or with OpenLDAP server. In order to deploy and test the YRVA solution, either Active Directory or OpenLDAP server is required. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 9 of 68

5 Configuration Please follow the configuration steps below to use the YubiRADIUS ready to deploy VMware virtual appliance: 5.1 Downloading the YubiRADIUS VMware virtual appliance 5.1.1 OVF Please download the YubiRADIUS virtual appliance in the OVF format from the link below: http://www.yubico.com/yubiradius-ovf 5.1.2 VMware Please download the YubiRADIUS virtual appliance in the VMware format from the link below: http://www.yubico.com/yubiradius-vm 5.2 Configuration of the YubiRADIUS VMware virtual appliance These steps assume that the YubiRADIUS virtual appliance is already downloaded and running. The configuration of the YubiRADIUS Virtual Appliance image is as follows: 1. Operating system: Debian 6.0.5 (squeeze) 2. Username: yubikey 3. Password: yubico 4. Super Username: root 5. Password: yubico 6. FreeRADIUS server version: FreeRADIUS Version 2.1.10 7. Webmin version: 1.570 8. Webmin Access URL: https://<ip address of the YubiRADIUS virtual appliance> 9. Database used for various YRVA modules/services and Yubico OTP validation server: PostgreSQL 10. PostgreSQL version: PostgreSQL 8.4.11 The virtual appliance is configured for receiving automatic IP address using DHCP. Change the network configuration to static IP Address if necessary. The DNS server will need to be set to resolve the IP Address of the Active Directory domain controller/openldap server. If there is a host name configured for the AD, YRVA server will not work if the IP address of the AD domain controller/openldap server is not set to be resolved. To get the solution into a functional state, these steps are required: 1. Create and configure users in a directory service AD/LDAP or the local OpenLDAP (included on the image) 2. Add a domain to the YRVA management 3. Configure the various global configuration parameters 4. Import users from the AD/LDAP/OpenLDAP server to the domain 5. To use the locally installed OTP validation server instead of the online Yubico OTP validation server, Import YubiKeys to the locally installed OTP validation server (YubiCloud) YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 10 of 68

6. Configure Auto-provisioning options for the domain 7. Add the RADIUS client (e.g. Cisco ASA server) to the FreeRADIUS server installed on the virtual appliance such that the FreeRADIUS server accepts the RADIUS authentication requests from the RADIUS client 8. Start the FreeRADIUS server These steps are described in details below: 5.2.1 Adding domains to the Yubico Virtual Appliance management Login to the Webmin console in order to configure and manage the YubiRADIUS solution. Yubico has created a separate Webmin module to manage the YubiRADIUS solution which is included in the virtual appliance. Please follow the steps below to add a domain to the YubiRADIUS solution: 1) To login to the Webmin console, use the following URL: https://<ip address of the YubiRADIUS virtual appliance> The URL will be automatically redirected to the Webmin console, as shown in the image below: 2) Provide username as root and password as yubico", as shown in the image below: 3) After logging into the Webmin portal the YubiRADIUS Virtual Appliance module will be displayed, as shown in the image below: Enter a domain name and click on Add Domain. For demonstration purpose, we are using yubiradius.com as domain name as shown in the image below: YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 11 of 68

This will add a domain yubiradius.com in the YubiRADIUS virtual appliance. The domain name only supports upper/lower case alpha-numeric (A-Z and 0-9) characters and special characters like period (.). 4) An unlimited number of domains can be added as needed to the YubiRADIUS virtual appliance. Each domain configuration is applied separately and configured independently of all other domains. Only the settings available under the Global Configuration will affect all domains. Note: If more than one domain is used, the UID will need to be entered as <username>@domainname.<ext> in any login screen for RADIUS connected VPN/Remote Access etc. i.e.: For a single domain the UID can be entered as AD/LDAP <user name> For multiple domains the UID must be entered as AD/LADP <user name>@domain.com 5.2.2 Setting up the Global configuration parameters The configuration parameters available under the Global Configuration allow YRVA administrators to access several configuration settings. These include: general FreeRADIUS configuration, enabling FreeRADIUS logging, choosing the Yubico OTP validation server, configuring the Synchronization service or deciding on the Key Storage Module to use. To configure the Global configuration options, please follow the steps below: 1) Click on the Global Configuration tab as highlighted in the image below: 2) The Global configuration options are listed in the following image: YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 12 of 68

The Global Configuration options are explained as follows: 5.2.2.1 General Click on General icon in Global Configuration tab. 1) Enable Auto-provisioning: Check the box to enable auto-provisioning. Auto-provisioning provides automatic YubiKey assignment to the users. When Auto-provisioning is enabled, the administrator can distribute the YubiKeys to end users without any additional work. With Auto Provisioning enabled the end users will be authenticated based on their username + password and a valid OTP on the first login attempt after receiving their YubiKey. After their successful authentication, the corresponding YubiKey ID will be automatically associated with the username (i.e. automatic user name to YubiKey binding). This method greatly simplifies the initial rollout process for administrators and end users. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 13 of 68

2) Enable Auto-provisioning for multiple YubiKeys: If this option is enabled, a single user can be assigned multiple YubiKeys automatically through Auto-provisioning. While users can have multiple YubiKeys assigned to a single username, a YubiKey can only be assigned to a single user, unless the Enable Single YubiKey for multiple Users option is selected. If the Enable Single YubiKey for multiple Users option is selected, a single YubiKey can be assigned to multiple users if and only if each user belongs to a different domain. It is important to note that the global configuration for Auto-provisioning overrides the domain level configuration for Auto-provisioning. This means that auto-provisioning must be globally enabled in order to enable it for a single domain. If global auto-provisioning is turned off then in is not possible to enable it at the domain level). 3) Enable Single YubiKey for multiple Users : When this option is selected, a single YubiKey can be assigned to multiple user accounts, provided that each user account belongs to a different domain. Even with this option enabled, a single YubiKey cannot be assigned to multiple users in the same domain. 4) On service fail, fallback to single factor? : When this option is enabled, when the OTP validation service is not available or there is any problem with validating the OTPs with the OTP validation server, the OTP validation will be skipped and the YRVA will fall back to a traditional single factor authentication based on username and password. At a service failure users will then only be validated using their AD/LDAP password. This option can be used in environments where the internet service is shaky and user availability is of highest priority (The option On service fail, send email alert? should also be enabled when this feature is used in this situation). The recommended use for this function is for an administrator to manually enable it to aid during troubleshooting or similar situations. 5) Append OTP to: This option allows administrator to decide either to append the OTP to the username or the entered password in the authentication request. 6) Temporary token length: This option sets the number of characters in a temporary token provided to the user for limited period of time. Currently Temporary token length is fixed to 8 characters. 7) YubiKey Public ID length (1-8 bytes) : This option sets the number of characters in each OTP which make up the Public ID. By reducing the Public ID length, the OTPs generated by the YubiKey will likewise be shorter each byte represents 2 characters. However, the amount of YubiKeys which YubiRADIUS can identify is also limited by the length of the Public ID. Finally, if the Public ID is set to a value other then 6, the YubiRADIUS will not work with the YubiCloud validation. When setting the YubiKey Public ID to a value other then 6, every YubiKey to be used with YubiRADIUS must also be configured with the same Public ID length. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 14 of 68

8) Enable YubiApp Registration: YubiApp Registration service allows the user to generate soft key tokens from their Smartphone. If the YubiApp Registration is disabled from global configuration then no user from underlying domains can access the YubiApp Registration service. If YubiApp Registration is enabled from global configuration then depending on domain level YubiApp configuration, it will allow the corresponding user to access YubiApp Registration. Please refer Appendix 6: YubiApp Registration for more information about YubiApp registration. 9) Enable Password Authentication through YubiRADIUS: When this option is selected, YubiRADIUS will keep track of Username during authentication, allowing requests for username and passwords to be in separate dialogs/screens as the YubiKey OTP request. 10) On service fail, send email alert?: By selecting this option, the YRVA server will send an email to the email addresses specified in the Email Addresses field if the OTP validation service is unavailable. Administrators can enter multiple email addresses by separating them with commas. Please note that to use this functionality the Exim4 email server installed on the YubiRADIUS Virtual Appliance will need to be configured - following your corporate policy - using the dpkg-reconfigure exim4-config command. 5.2.2.2 FreeRADIUS Click on FreeRADIUS icon in Global Configuration tab. Enable FreeRADIUS Logging: Enabling this option will invoke the debug logging of the FreeRADIUS server. The FreeRADIUS server will need to be restarted after enabling/disabling this option. The FreeRADIUS server can be restarted using the highlighted button as shown in the screen shot below: YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 15 of 68

The FreeRADIUS log file can be viewed by clicking on System System Logs from the Left hand side menu as highlighted in the image below: Clicking on View of radius log link as highlighted below will display the system logs: YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 16 of 68

Please note that RADIUS logging should only be used for trouble shooting. Remember to turn it off once the trouble shooting session is over as it will quickly fill the disk with extensive logs. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 17 of 68

5.2.2.3 Validation Server 1) Set where the YubiKey OTP (provided as a part of user credentials) will be validated by selecting the appropriate option. YubiCloud - Online Validation Service then OTPs will be validated by making a validation request to the YubiCloud Online Validation service. The YubiCloud validation servers provide redundancy and high availability for OTP validation. When selecting YubiCloud note that YubiKeys are enabled for YubiCloud validation so the YubiKeys can be directly distributed to end users without any programming. For more information, please visit the link below: http://www.yubico.com/server-v2-faq If Local validation Server on YubiRADIUS VA is set then OTPs will be validated using the locally installed (installed in the YubiRADIUS VA) OTP validation server. Please note that when the Local validation Server on YubiRADIUS VA option is selected the server will need to import the YubiKey information (YubiKey records) such as AES Key, Private ID etc. before it can start validating the OTPs. Please refer to the section 4.2.4 for more details on importing the YubiKey records. If using another validation server somewhere else, the Validation Server setting will need to be set to the Other option and provided the OTP validation URL in the specified format. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 18 of 68

2) Validation Server Client ID and API key: The API ID/Client ID and API key will need to be entered for the selected validation server as explained below. Note that by default, it looks like YubiRADIUS has one an API key already entered, users will need to enter one when setting up YubiRADIUS. Further, every time a change is made to YubiRADIUS, users will need to re-enter the appropriate API Key. When entering an API key, do not click the Generate button, as that will enter a random API key which will not work with most setups. YubiCloud If the YubiCloud - Online Validation Service is selected in the previous input field then enters the Client ID in the Client ID field. If an API ID for YubiCloud (in base64 format) was not provided, please visit to the following link to generate one: https://upgrade.yubico.com/getapikey/ For more information on API ID and API Key pair, please visit the following link: http://www.yubico.com/developers/api/ For Example: If the Administrator would like to use the YubiCloud with Client ID = 4233 and API key = H9xX7BeTIbhYK3xCb/PSEeRVNvY= which is a valid already registered API ID in the YubiCloud and can be used for quick setup, then he/she need to enter 4233 in the Client ID input field and H9xX7BeTIbhYK3xCb/PSEeRVNvY= (without quotes) in the API Key field. Local Validation Server If the Local validation Server on YubiRADIUS VA is selected in the previous field then it is not necessary to set up the Client ID. By default the Client ID is set to 1 for local validation server. An API key will still need to be configured, For the default (common) key enter "IXazp2MoffwFYj/pfcc+v20SMVc=" (without quotes) as the API Key To enable organizations to choose a custom key the YubiRADIUS Virtual Appliance provides the API key generation functionality for the local validation server. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 19 of 68

This will help the organizations to get the new API Key for their local validation server rather than using the common one. Clicking the Generate button generates a new API that is generated and populates the API Key field. If Show API Key checkbox is checked, the API key is displayed in text format, otherwise in the key is displayed in the masked password format (i.e. *****). Other If the Other option is selected in the previous field then the API ID/Client ID and API Key pair must be known for the OTP validation server. Enter that Client ID and API key in the labeled fields. Refer the installation document of the validation server for more details on adding the client id and API Key in the validation server. 5.2.2.4 Synchronization It is possible to set up multiple YubiRADIUS Virtual Appliances (YRVA) to help avoid a single point of failure when the local on-board validation server is used. In this mode of deployment, a number of YRVA instances can be configured with identical global, domain, user configurations and the same set of YubiKey secrets (AES keys) imported on all the instances. Thereafter, the following configuration parameters need to be set on each instance to enable synchronization of YubiKey assignment information (for users) and OTPs with the other instances of YRVA in the group. This feature was introduced in YubiRADIUS Please note when multiple instances of YubiRADIUS Virtual Appliance are configured for synchronization, to avoid database conflicts Administrators must restrict the use of Webmin administration interface to a single YRVA instance at a time to manage Users and YubiKey assignments to users. 1) Local Server (Secret) Configuration: Server secret: This field allows entering the shared secret for local server. This secret is used to encrypt the communication for synchronization of Username to YubiKey ID mapping. When adding a server each YRVA instance must be configured with the same shared secret as the other YRVA instances to allow synchronization. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 20 of 68

The Local Server (Secret) can be comprised of any upper/lower case alpha-numeric (A-Z and 0-9) characters and special characters (.! # @ etc). 2) Add Server: Provide the details of the other YRVA instances i.e. IP address and shared secret with which this YRVA instance should communicate for synchronization of OTP counters and Username to YubiKey ID mapping. To allow the instances of YRVA to synchronize OTP counters and Username-to-YubiKey ID Mapping with other YRVA instances, the Add Server section must be populated with the IP address (Server IP) and Shared Secret (Sever Secret) of the other YRVA servers. The Server Secret can be comprised of any upper/lower case alpha-numeric (A-Z and 0-9) characters and special characters (.! # @ etc). Please remember the following important points while setting up synchronization between two or more instances of YubiRADIUS Virtual appliance: YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 21 of 68

The synchronization feature in YRVA synchronizes the OTP counters and Username to YubiKey ID mapping information between the configured instances. Other static or seldom changed configurations need to be done manually, meaning that the same settings need to be entered in all the YRVA instances. It is important to import users from same LDAP/AD server with same import settings like Filter, UserDN, BaseDN. Import the same YubiKey import file into all the instances Configure the local server secret (shared encryption key) on each instance To enable synchronization between the YRVA instances, add all other YRVA instances using in the Add Server section. For Example: If there are two instances of YubiRADIUS virtual appliance, defined as Instance 1 and Instance 2, follow the configuration steps below for each instance: On YRVA at Instance 1, define local server secret as test123. On YRVA at Instance 2, define local server secret as test456. In the Add Server section of Instance 1 add the server address for Instance 2 and Server Secret & Confirm Shared Secret as test456. In the Add Server section of Instance 2 add the server address for Instance 1 and Server Secret & Confirm Shared Secret as test123 To test synchronization between both instances, enable Auto-provisioning in Global settings and for the domain, then assign a YubiKey to User4 in the YUBIRADIUS instance 2. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 22 of 68

After successful assignment, User4 should be assigned the YubiKey. Due to synchronization between the two instances, the same YubiKey assignment can also be seen in the other instance (as shown in the following screen): 5.2.2.5 Key Storage Module YRVA supports the use of YK-KSM or YubiHSM to securely store the YubiKey seeds if the on-board validation server is used. This screen allows you to define Key Storage Module to be used to store the YubiKey credentials. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 23 of 68

1) Key Storage module: Select this option to select the YubiKey-KSM (YK-KSM) or YubiHSM module for storing YubiKey credentials. 2) If YubiHSM is selected the information about the key handle must be provided in either Hexadecimal or Decimal format. Enter the Passphrase (Master Key) that was used at the time of initial YubiHSM configuration. For Example: The key handle can be provided in hexadecimal format like 0x8888 or in decimal format such as 34952. The YubiHSM creates or receives secrets and encrypts them before they are transmitted to the authentication server for storage. With this approach, an unlimited number of secrets can be transmitted, stored and authenticated without risk of being compromised. In this mode, the YubiHSM can also decrypt the OTP received from provisioned YubiKeys and also validate with validation server e.g. YK-VAL. If planning to use YubiHSM in the YubiRADIUS Virtual Appliance it will need to first have the YubiHSM device connected physically and then configure it. Please note that if YubiHSM is used, YubiRADIUS Virtual Appliance requires the YubiHSM to be configured in HSM mode. Note: Settings made in the Global configuration affects all the domains. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 24 of 68

5.2.3 Importing users to the domain If upgrading from a previous version of YubiRADIUS, note that there have been significant changes for the user import function. Users are now organized under OUs/Groups. To view an imported user first click on the OU/Group the user belongs to. Once there all users in that OU/Group will be displayed. Due to the new way of viewing users it will take a longer time than before to import users. Please refer Appendix 4: Importing Users from Active Directory/LDAP for more information about what is new for user import. To import users to the domain, please follow the steps below: 1) Click on the domain name as shown in the image below: 2) Click on the Users Import tab, as highlighted in the image below to fetch the users from the AD/OpenLDAP server: YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 25 of 68

YubiRADIUS has simplified the basic User Import functionality. Administrators who require more flexibility while importing users or need to configure an SSL connection to the directory may use the advance section. However, it is recommended to use the simplified interface for the initial YubiRADIUS Setup, and then proceed into the advanced section if additional configuration is required (such as setting up an SSL connection). 3) To setup YubiRADIUS, the following information will need to be provided: a) Directory Type: The Directory type may be set to either Active Directory or OpenLDAP ; Set the Directory type to the same Directory type the users will be imported from. b) LDAP/AD Server Address or Host Name: Enter the IP Address/Fully Qualified Domain Name of the Active directory/ OpenLDAP server. c) Admin User: Enter the User DN for binding with the Active Directory/ OpenLDAP server. Enter the administrator DN YubiRADIUS should use to authenticate with the AD/LDAP server when importing users. For Example: cn=administrator, cn=users, dc=example, dc=com. Most commonly this is a administrator or privileged account. d) Password: Enter the password for the administrator/privileged account to be used for when importing users from the Directory. e) Advance: The Advance button will display the advanced configuration UI. The Advanced configuration UI includes tool to customize YubiRADIUS further, such as using secure connection (LDAPS), applying filters while importing users from directory, and the like. f) Save: The Save button will save the entered settings for this page. g) Import Users: The Import Users button will save the current entered settings for this page and attempt to connect the LDAP/AD server to import the users. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 26 of 68

By clicking on the Advance button, administrators can provide more parameters to import the users with more flexibility as required. 4) Please provide the following information: a) Use Secure Connection?: Select Yes to use LDAPS (encrypted Secure Connection) and No to use regular unencrypted LDAP to connect to the directory server for importing and authenticating users. b) Directory Type: Select the directory type between Active Directory and OpenLDAP ; The Administrator must define the directory type from where he/she importing the users. c) LDAP/AD Server Address or Host Name: Enter the IP Address/Fully Qualified Domain Name of the Active directory/ OpenLDAP server d) Backup LDAP/AD Server Address or Host Name (optional; for user authentication only): Enter the IP Address/Fully Qualified Domain Name of the Backup Active directory/ OpenLDAP server Please note that this AD/LDAP server is used only for the validation purpose when Primary LDAP/AD Server is not reachable. e) Port: Enter the port number on which the LDAP server is running. Leave this blank or set it to zero to use the default LDAP or LDAPS ports, depending on setting in step a above f) LDAP Version: Select the version of the LDAP Protocol to be used for importing the users information from your Directory Service g) Base DN: Enter the Base DN of the Active Directory/OpenLDAP server from where the users need to be fetched. The Base DN represents the starting point in the Directory(AD/LDAP) hierarchy under which the users are located. For Example: ou=users, dc=example, dc=com h) User DN: Enter the User DN for binding with the Active Directory/ OpenLDAP server. Enter the administrator DN YubiRADIUS should use to authenticate with the AD/LDAP server when importing users. For Example: cn=administrator, cn=users, dc=example, dc=com. Most commonly this is a type of administrator or privileged account. Also see related password below. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 27 of 68

i) Password: Enter the password for the administrator/privileged account for use when importing users from your Directory j) Schedule: Select the appropriate schedule for fetching the users from the Active Directory/ OpenLDAP server. Administrators can optionally schedule the automatic import of the users on hourly, daily and weekly basis as shown in the image below: If Administrator selects Hourly option is selected, users will be imported once in an hour. When the Daily option is selected, the users will be imported once every day and when the Weekly option is selected the users will be imported once in a week. This is useful if you have a larger number of users and with users frequently changing roles and moving from one OU to another. k) Filter: Provide the filter value(s). For Example: In the case of Active Directory Server and OpenLDAP server use (objectclass=person) > to import all or specific users. Set an appropriate filter to import the users based on your needs. For more information, please see the examples provided in Appendix 4. l) Login Name Identifier: Provide the Login name Identifier to identify the unique attribute that should be used to authenticate users with AD/LDAP server. (For Active Directory use samaccountname and for OpenLDAP server use uid ) The Save button will save the entered settings for this page. The YubiRADIUS Virtual Appliance utilizes an optimized user import functionality. Thousands of users from LDAP/AD can be imported in YubiRADIUS Virtual Appliance along with their hierarchical information in just a few minutes. Please refer Appendix 4: Importing Users from Active Directory/LDAP for more information about importing users from AD/LDAP. The YubiRADIUS Virtual Appliance supports login names longer than 20 characters. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 28 of 68

5.2.4 Defining User Group Hierarchy In YubiRADIUS 3.6.0 and above, Administrators have greater control over which groups to return for each user. When returning a single group for a user, YubiRADIUS will respond with the highest priority group, as defined in the Groups tab in the Domain settings. If a group has its priority set to 0, it is never displayed for a user unless all groups are being returned. The Groups listed in the Domain Configuration will be automatically populated upon importing users from the AD/LDAP server. By default all groups are set to 0. Administrators can then assign a priority to each group by entering a number above 0. The higher the number assigned, the higher the priority in returning the group associated with the user. When importing new groups, their priority is automatically set to 0 and remains at that value until changed by an Administrator. Once the priority of the groups has been assigned, click the Update button to save the priority for each group. 5.2.5 Importing YubiKeys to YKKSM database or YubiHSM To use the locally installed OTP validation server, it is necessary to import the token (YubiKey) information such as AES Key, Private ID etc. for the YubiKeys to the locally installed YKKSM database or YubiHSM (depending on the selection in Global Configuration). This is to allow the OTPs emitted from these YubiKeys to be validated with the locally installed OTP validation server. Use the YubiKeys Import tab to import the YubiKey s related information to the YKKSM database/yubihsm. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 29 of 68

You can directly import YubiKey secrets can be directly imported from log files generated by the Original Windows Personalization Tool or the Cross-platform Personalization Tool. Select the appropriate option depending on the source of your file. A sample entry in the comma separated text file (generated by the Original Windows Personalization Tool) is as follows: 1,djecuclbjfjh,ebe845d88fa6,a23bf655215e0355e5ae9b08858def33,0,0,0 For uploading the information, the path of the comma separated text file must be entered in the File to upload text box. Once the path is configured, clicking the Upload will upload the YubiKey secrets. 5.2.6 Enabling Auto-provisioning mode for the domain It is possible to enable/disable the Auto-provisioning mode at the domain level as well. However, note that to enable Auto-provisioning mode at the domain level, it must also be enabled in the Global configuration settings. If the Auto-provisioning in the Global configuration settings is disabled then Auto-provisioning is not available for any domain even if the Auto-provisioning option is enabled at the domain level. The same principle is applied to the Auto-provisioning for multiple YubiKeys option. To enable the Auto-provisioning and Auto-provisioning for multiple YubiKeys please follow the steps given below: 1) Click on the Configuration tab as highlighted in the image below: 2) Enable/ Disable the Auto-provisioning and Auto-provisioning for multiple YubiKeys as per requirements in the section highlighted in the image below, then click on Update YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 30 of 68

5.2.7 Enabling YubiApp Registration It is possible to enable/disable the YubiApp Registration at the domain level as well. However, note that to enable YubiApp Registration at the domain level, it will need to also be enabled in the Global configuration settings. If the YubiApp Registration in the Global configuration settings window is disabled then the YubiApp Registration is not available for any domain even if the YubiApp Registration is enabled at the domain level. To enable the YubiApp Registration at domain level, please follow the steps given below. 1) Click On configuration tab 2) Enable/ disable the YubiApp Registration as per requirements int he section highlighted in screen below, then click on Update. 5.2.8 Enable Gradual Deployment YubiRADIUS 3.6.0 and on support a Gradual Deployment feature, allowing users to continue to login with just their AD/LDAP credentials until being assigned a YubiKey. This feature requires Auto-Provisioning to be enabled to function correctly. When Gradual Deployment is enabled in the Configuration tab for a Domain, the Users/Groups interface will have some additional features: YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 31 of 68

a) Single Factor Flag: This reflects if a user is currently allowed to use a single factor login of just their Username/Password credentials from AD/LDAP. A green check means that user does not need to supply a YubiKey OPT, while a red x in this column means a YubiKey OTP is required. When a YubiKey is successfully assigned to a user, this flag is automatically disabled. b) Enable single Factor Option: By checking one or more users and clicking this option, the Single Factor Flag for the selected users is set to on, allowing those users to log in without the need of a Yubikey OTP. This can be used in conjunction with the temporary tokens to assist users who have lost or misplaced their YubiKey. c) Disable single Factor Option: By checking one or more users and clicking this option, the Single Factor Flag for the selected users is set to off, requiring those users to log in with a Yubikey OTP. 5.2.9 Return user s Group Membership information in RADIUS response YubiRADIUS Virtual Appliance provides the functionality to return the user s group membership information in RADIUS response. 1) Return user s Group Membership information in RADIUS response: can enable the functionality by setting Return user s Group Membership information in RADIUS response to yes. In addition, Administrators can specify the format in which the user s group membership information need to be returned. 2) Response Format: It consists of three parts: a) First Textbox: This defines of the prefix to be attached to the user s group membership information. b) Group name: This consists of user s group membership information. c) Second Text box: This defines of the postfix to be attached to the user s group membership information. 3) Group return information: If Group DN is selected, then the entire group DN of the user is returned in the RADIUS response. If Only Group Name option is selected then only the user s group name will be returned in the RADIUS response. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 32 of 68

For Example: If user1 belongs to the group name = people, and we define the prefix as ou= and postfix as ; then user s group membership information returned in the RADIUS response will be, Class = ou=people; Please note that FreeRADIUS returns the user s group information in Class attribute. In YubiRADIUS 3.6.0 and above, Administrators can choose which groups to return for each users by setting the Return All Groups Option a. Yes: Every group a user belongs to is returned. b. No: Only the highest ranking group, as determined by the Domain Group Ranking configured will be returned In YubiRADIUS 3.6.0 and above, administrators are able to rank user groups by importance, allowing users to be identified by the highest ranking group each belong to. When importing users from an AD/LDAP server, the all the groups will also be imported. YubiRADIUS Administrators can sort them by priority. 5.2.10 Adding RADIUS clients to the Domain The RADIUS client s IP address and a shared secret must be added in the FreeRADIUS server so that the FreeRADIUS server accepts incoming RADIUS requests coming from the RADIUS client. To add the RADIUS client, please follow the steps given below: 1) Click on the configuration tab as shown in the image below: 2) Provide the IP address of the Client and Secret (encryption key) in the section highlighted in the image below and click on the Add button YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 33 of 68

YubiRADIUS Virtual Appliance supports configuration for network clients on a subnet only through configuring for all clients on this subnet. For Example: You can set the Client IP address as 192.168.1.0/24 which makes the YRVA to accept the request from any of the terminal having IP address 192.168.1.0 to 192.168.1.255. The YRVA is now ready for testing and evaluation. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 34 of 68

6 Testing the configuration For testing RADIUS two-factor authentication with YubiKey, Yubikey OTP validation and availability of machine users can visit the Troubleshoot tab. 6.1 RadTest: To test the RADIUS two-factor authentication with a YubiKey, use the RadTest utility in the section highlighted in the image below: Examples: We configured a YubiRADIUS virtual appliance as described above in the document. We added the yubiradius.com domain and imported a couple of users from active directory. For demonstration purpose, we are using the User1 user as highlighted in the image below: YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 35 of 68

The user is not assigned any YubiKey yet. We have enabled the Auto-provisioning option at the Global configuration level as well as at domain level. We are using the online Yubico OTP validation server for testing. Note that if you have created only one domain in the YRVA server there is no need to add the domain name after the username at the time of authentication. In this example, if the username is User1 then at the time of authentication you need to just provide username as User1 instead of User1@yubiradius.com. However, for multiple domains then the domain name will need to be added after the username at the time of authentication. The username is case-insensitive. The YubiKey OTP can be provided in all upper or lower case letters. The Password is case-sensitive and supports all upper & lower case alpha-numeric (A- Z and 0-9) characters and special characters. Please refer to the test examples below: 1) We tested the configuration using the RadTest utility as shown below: We provided the correct password for the User1 user and the OTP from a YubiKey which was not yet assigned to anyone and to which OTP can be validated with the online Yubico OTP validation server. We received the response as Successful! from the RADIUS server since the username + Password + YubiKey OTP were validated successfully. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 36 of 68

And a username to YubiKey Public ID mapping was created as highlighted in the image below: 2) We executed the RadTest utility one more time, this time entering the same credentials along with the same OTP that was provided in the test above: This time we received the response as Failed! because the OTP was used already. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 37 of 68

6.2 Validate OTP: To test the validation of YubiKey OTP with the validation server defined in Global Configuration, use the Validate OTP utility in the section highlighted in the image below: Please note that is the YubiKey is configured for adding a enter key as the end of the OTP (default programming) Then use notepad or similar text editor for entering the OTP and then cut and paste in the YubiKey OTP filed. Following example describes the YubiKey OTP validation with the Online YubiCloud service. 6.3 Ping: The Ping utility is another test tool used for checking the availability (network connectivity) of a machine or service. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 38 of 68

The Following image displays ping functionality. Here we are trying to check availability of www.yubico.com 6.4 Common Troubleshooting Steps There are a few common steps users can take to address many OTP issues. If the RadTest returns a failed result, please check these items: YubiKey Is Not Imported To verify the YubiKey has been imported into YubiRADIUS, use the Yubico OTP field. Use the YubiKey to generate an OTP in this field and press the validate button. A successful validation means the YubiKey is imported correctly. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 39 of 68

User Is Not Imported To verify the user account has been imported into YubiRADIUS, open the Domain tab and click in the domain the user belongs to. All of the users should be listed verify the user you are attempting to log in as is present. API Key is not configured correctly Ensure in the Global Configuration > Validation server, the API key is entered correctly. Do not click the Generate button after entering the API key this will overwrite the entered key with a random key. The Local API key is not entered by default. Further, every time the Validation server is updated, it will need to have the API key re-entered in both fields. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 40 of 68

7 Users and YubiKey Management Using the YubiRADIUS Virtual Appliance interface, it is possible to enable/disable the YubiKey associated (assigned) to a user, unassign a YubiKey from a user or delete a user from the YubiRADIUS database. These functionalities are explained in details in the following sections: 7.1 Enable YubiKey The Enable YubiKey button allows an Administrator to re-enable a Yubikey assigned to a user from the disabled state. Doing so will allow the YubiKey to be used for authentication again. To do so, first select the user from the Users tab and click on Enable YubiKey button. The YubiKey ID to username association will be enabled again and the YubiKey may be used once more by the user. The YubiKey status changes to enabled (Tick mark sign) as highlighted below: 7.2 Disable YubiKey The Disable YubiKey button allows an Administrator to disable a Yubikey assigned to a user from the enabled state. Doing so will prevent the YubiKey from being used for authentication. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 41 of 68

Select the user from the Users tab and click on Disable YubiKey button. The YubiKey ID to the username association will be disabled and the user will not be able to use the YubiKey. The YubiKey status changes to disabled (cross sign) as highlighted below: 7.3 Unassign YubiKey The Unassign YubiKey button allows an Administrator to Unassign a Yubikey assigned to a user. Doing so will prevent the YubiKey from being used for authentication. Select the user from the Users tab and click on Unassign YubiKey button. The YubiKey Public ID to the username association will be deleted and the user will not be able to use the YubiKey. The YubiKey gets unassigned as highlighted below: YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 42 of 68

7.4 Delete User The Delete button allows an Administrator to delete a user from the from YubiRADIUS Virtual Appliance. To delete a user from YubiRADIUS Virtual Appliance t click on the Delete User button. The user only will be deleted from the YubiRADIUS Virtual Appliance and not from the Active Directory or LDAP. Further, all the YubiKey ID to username associations for that user will be deleted and those YubiKeys will no longer be able to be used for authentication. The user gets deleted as highlighted below: YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 43 of 68

Please note that if a user is deleted from the AD/LDAP, then that user is not automatically removed from the YubiRADIUS Virtual Appliance s domain. An Administrator has to manually delete that particular user from YubiRADIUS Virtual Appliance s domain. If a user is renamed in the LDAP/AD then the changed name is also renamed in the YubiRADIUS Virtual Appliance domain in next importing activity of the users. 7.5 Display Users/Group hierarchy: By default YubiRADIUS Virtual Appliance displays all the users without organizing them into groups and sub-groups. All Users button: By clicking the All Users button, YubiRADIUS displays a list of all the users in the LDAP/AD, irrespective of their group hierarchy. After being clicked, the button toggles to the Group Hierarchy button. Group Hierarchy button: By clicking the Group Hierarchy button, YubiRADIUS displays the users in their group hierarchical structure, using Groups and Sub-Groups imported from LDAP/AD. 7.6 Assign Temporary Token: If user forgot to bring their YubiKey, an Administrator can assign the user a temporary token, which will allow the user to authenticate without the use of a YubiKey for a specific number of authentications set by the administrator. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 44 of 68

To assign a temporary token, an administrator can select the user and click on the Temporary token settings as highlighted in the above screenshot. 1) Enable Temporary Token: Select yes to assign a temporary token. 2) Temporary Token: The Temporary token can be manually entered as a fixed 8 character string, or randomly generated by clicking the Generate Button. 3) Temporary Token Expires After: You can specify the expiry date for the temporary token. For example: If you specify the expiry date as 21 March 2012, then user can use temporary token from now through the 21 March 2012 11.59 P.M. midnight). Any attempts to login with the temporary token after this will be rejected by the server. Once the temporary token has expired the user must use his/her assigned YubiKey for successful authentication. 4) If you specify an expiry date from the past, an error message will be shown asking you to Please specify todays date or a future date 5) Maximum Authentication Allowed: This field is used to set the number of times the user is allowed to use the temporary token. This field value decreases after each successful validation of the user with a Temporary Token. Once an Administrator has assigned a Temporary Token to the user, then Temporary Token Status column displays enable (green checkmark) status as shown in the screenshot below for user1: YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 45 of 68

The Temporary Token Status disables automatically in following cases, a. On expiry of the Temporary Token configured date. b. When Maximum Authentication Allowed turns to 0 (zero) c. When user enters a valid YubiKey in validation request. d. When user enters a new YubiKey (unassigned YubiKey) in validation request and has auto-provisioning is enabled (for both global as well as domain level). Please note (as described above) that the temporary token functionality will be automatically disabled once the user uses their valid YubiKey for first time or uses their YubiKey again (if forgotten). The Temporary token also supports all upper/lower case alpha-numeric (A-Z and 0-9) characters and special characters. 7.7 Set Users to Single or Two Factor Authentication When Gradual Deployment is enabled for a domain, administrators can switch users between single factor authentication using only their AD/LDAP credentials and two factor authentication using a YubiKey alongside their Username & Password. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 46 of 68

The user list reflects which authentication mode a user is in with the Single Factor Flag column. A green check means that user does not need to supply a YubiKey OTP, while a red x in this column means a YubiKey OTP is required. Administrators can select users and switch their authentication methods using the Enable/Disable single Factor options. By checking one or more users in the list and selecting the Enable single factor option, the Single Factor Flag for the selected users is set to on, allowing those users to log in without the need of a Yubikey OTP. This can be used in conjunction with the temporary tokens to assist users who have lost or misplaced their YubiKey. By selecting the same users and clicking the Disable single Factor Option the Single Factor Flag for the selected users is set to off, requiring those users to log in with a Yubikey OTP. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 47 of 68

8 Reports The YubiRADIUS virtual Appliance can also generate reports. The reporting feature is available under the Reports tab as highlighted in the image below: The reporting feature provides On-Demand Reports. 8.1 On-Demand Report You can generate following two types of On-Demand reports: 8.1.1 YubiKey Assignment YubiKey Assignment report will show the username to YubiKey assignment depending on the filter chosen. The report is generated in a CSV format which can be downloaded. There are three filters available; All, Enabled and Disabled. The All filter will have the report show all the username to YubiKey ID mappings. The Enabled filter will have the report show only the currently enabled username to YubiKey ID mappings. The Disabled filter will have the report show only the currently disabled username to YubiKey ID mappings. Also, for the YubiKey Assignment On-Demand report, additional filters can select the particular date range for which to generate the reports. 8.1.2 Authentication Request Authentication Request report will show the result of the total authentication requests handled by the YubiRADIUS virtual appliance, depending on the filter chosen. The report is generated in a CSV format which can be downloaded. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 48 of 68

There are three filters available; All, Success and Failed. The All filter will have the report show all the authentication requests handled by virtual appliance, irrespective of whether they were successful or failed. The Success filter will have the report show only the successful authentication requests. The Failed filter will have the report show only the failed authentication requests. For the Authentication Request On-Demand report, additional filters can select the particular date and time range for which to generate the reports. All the reports will be saved in the /usr/share/webmin/yubico-rop/reports directory. Reports can be managed from this directory. 8.2 Sample report For demonstration purpose, we will show how to generate an Authentication request report using the All filter. To generate the report, follow the steps below: 1) In the Reports tab, select Type as Authentication Requests and Options as All for On-Demand Report. Select Time Range as, From 1 st Jan 2012 00:00 to 20 th March 2012 00:00, also highlighted in the image below: Please click on the Generate button; the report will be generated and a message saying Report generated successfully is displayed. Click on View under Action to view the report. Note the message text will appear on the screen as highlighted in the image below 2) Click on click here link or the View button to view the report. A new tab will be opened automatically and the report will be generated in the following format: YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 49 of 68

3) You can also delete the generated report, select the report and click on the Delete Selected button YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 50 of 68

9 List YubiKeys Tab The List YubiKeys tab displays all the YubiKeys imported in the database along with their corresponding assigned usernames including domain name. The List YubiKeys tab is designed to help the administrators keep track off the YubiKeys that are imported into the database as well as which are assigned to users and which are unassigned so that an administrator can easily determine which YubiKeys are available to be assigned to new users. YubiRADIUS Virtual Appliance provides a built-in UI to the AEADs that are generated using YubiHSM device and displays the YubiKeys imported using YubiHSM device. If an administrator configures the Key Storage Module as YubiKey-KSM in the Global Configuration tab then only YubiKeys imported in the database are displayed in the List Yubikeys tab with the corresponding username of the user. Similarly, if an administrator configures the Key Storage Module as YubiHSM then only YubiKeys imported using YubiHSM are displayed in the List YubiKeys tab (irrespective of the selected key handle) with the corresponding username of the user. The Administrator can search the imported YubiKey assignment and status details by searching for the YubiKey ID or username. Administrators can directly assign the user a YubiKey by clicking on Assign new YubiKey to User menu. Please note that YubiKeys tab is available only with local validation server and disabled for online (YubiCloud) validation service. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 51 of 68

10 Appendix 1: Security Considerations For security reasons, we strongly recommend to change the default passwords before setting up YubiRADIUS Virtual Appliance in your environment. At the very least we recommend changing the passwords before taking YubiRADIUS into production. YubiRADIUS Virtual Appliance is built on standard Debian 6.0 Operating System. Available OS patches have been applied at time of creation of the YRVA. The YubiRADIUS Virtual Appliance has only security updates enabled by default. Update of any other module will require manual updates. YubiRADIUS Virtual Appliance is not specifically hardened, though we are limiting automatically starting services to only those needed for YubiRADIUS authentication. We highly recommend users review and adjust system configuration and security settings according to applicable corporate security policies and best practices. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 52 of 68

11 Appendix 2: Using YubiHSM Yubico YubiHSM is a Hardware Security Module (HSM) designed for protecting secrets on authentication servers, including cryptographic keys and passwords, in a clear and easy to use manner. YubiRADIUS Virtual Appliance has built-in support for YubiHSM and provides flexibility for users to use either YK-KSM or YubiHSM to securely store the YubiKey credentials. Follow these steps to setup YubiHSM with YubiRADIUS Virtual Appliance: First connect the YubiHSM device physically to the device running the YubiRADIUS Virtual Appliance. Once connected, the YubiHSM will need to be configured. The YubiRADIUS Virtual Appliance only supports a YubiHSM device when it is configured in HSM (AEAD) mode. When the YubiHSM device is connected, the corresponding device entry is automatically added in the dev directory as ttyacm0. The core steps to configure the YubiHSM device are listed in this document below. For complete instructions and additional details on configuring the YubiHSM in HSM (AEAD) mode, refer to the following document: http://static.yubico.com/var/uploads/pdfs/yubihsm%20manual%202011-09-14.pdf 11.1 Configure the YubiHSM: 1) Connect the YubiHSM device to a USB on a computer (To setup the YubiHSM device on a Windows Computer the following.inf file may need to be download and used: http://static.yubico.com/var/uploads/files/yubihsm.inf) 2) Access HyperTerminal 3) Configure the YubiHSM device via the following steps. For more detail, refer to the configuration steps in section 8.1 of the YubiHSM Manual i. Place the YubiHSM in configuration mode by holding down the configuration switch on the hardware when powering on the YubiHSM device. ii. In HyperTerminal connect to the COM port assigned to the YubiHSM device. The port can be determined with Windows Device manager. Leave the COM port settings to the default values. iii. HyperTerminal should start communicating with the YubiHSM device. 4) Set the master key via the following steps. For more detail, refer to the configuration steps in section 8.4 of the YubiHSM Manual i. In HyperTerminal, type hsm to display the configuration menu. For information on these settings, refer to the YubiHSM Manual. ii. Hit the ENTER key to proceed to the optional configuration password option. To skip adding a configuration password, only hit ENTER. To enable the password, either hit g and ENTER to generate a random password or paste in a 16 byte hexadecimal string. Keep this password stored securely for future reference. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 53 of 68

iii. The next step allows the setup of "administrative Yubikeys" to be used in conjunction with the YSM_HSM_UNLOCK command. To skip this step, only hit ENTER. To add administrative Yubikeys, enter the public IDs in modhex format for each administrative Yubikey, separated by ENTER. iv. The next step is the creation of a AEAD key storage master key. Hit g and ENTER to generate a random Master Key or paste in a 32 byte hexadecimal string. Keep this key stored securely for future reference. A default key of all zeroes is applied if only ENTER is pressed. v. The final step is the confirmation of the entered configuration. Type yes and ENTER to accept and save the settings. Any other text will abort the entered configuration. vi. Wait the configuration is complete, indicated when system prompt in HyperTerminal displays HSM>. 5) Next, generate key handles and keys via the following steps. For more detail, refer to section 8.8 of the YubiHSM Manual. Note the key handles generated in YubiHSM are in hexadecimal format. i. To generate and store a range of key handles, type: keygen <start id> <count> <key_length> For example, to create three keys - 5, 6 and 7 with 32 bytes length, type: keygen 5 3 20 ii. Use cut-and-paste or input capture from the terminal program to keep a backup copy for these generated keys. 6) It is important to commit the generated Keys so the YubiHSM configuration is stored in permanent memory. Commit the keys via the following steps. For more detail, the process described in section 8.11 of the YubiHSM Manual. i. In HyperTerminal, type: HSM (keys changed)> keycommit ii. The key database must be committed even if no master key has been set. The keys are then encrypted with a default (all zero) key. Note the configuration details such as key handle, master key, etc. and use the same configuration details while configuring the YubiRADIUS Virtual Appliance 11.2 Configure YubiRADIUS Virtual Appliance: 1) Log on to YubiRADIUS Virtual Appliance 2) Acess Global Configuration >> Key Storage Module option 3) Select YubiHSM option 4) Enter the 'key handle' and 'passphrase (master key)' that was set during the configuration of YubiHSM. 5) Save the configuration. The YubiHSM Key handle can be provided in either hexadecimal format (such as: 0x8888 ) or in decimal format (such as: 34952 ). For Example: We have configured YubiHSM with key handle as 8888 and master key (passphrase) as: 9528b6642b06cd219eb8dd784091dcdbbce4dee49efda4cc73614ed01e2fdf09 When YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 54 of 68

configuring the YubiRADIUS Virtual Appliance we are use the same configuration details as shown in following window. Another import of the YubiKey secret keys between the Key Storage Module options (YKKSM or YubiHSM) will required after changing the configuration. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 55 of 68

12 Appendix 3: Using LDAPS The YubiRADIUS Virtual Appliance has support for LDAPS to allow it to securely connect to directory servers for importing and authenticating users. To use LDAPS, first set the Use Secure Connection option to Yes. Set the Port as 636, the default port for LDAPS. Ensure other details are set as per LDAPS configuration: Setting the Port field to blank or zero will result in YRVA using the default port for LDAP (389) or LDAPS (636), depending on if Use Secure Connection is set as No or Yes. 12.1 Setting LDAPS for YubiRADIUS Virtual Appliance: Administrators must add the CA certificate from the AD/LDAP server. When YRVA is configured to use LDAPS communication, it asks for the certificate while communicating. The CA certificate must be provided to the YRVA instance and be configured in the ldap.conf file. Quick Setup Steps: 1) Obtain the CA certificate used to sign the CSR for AD/LDAP 2) Copy it to /etc/ssl/certs on YubiRADIUS host 3) Add the following lines to /etc/ldap/ldap.conf: # Define location of CA Cert TLS_CACERT /etc/ssl/certs/cacert.pem TLS_CACERTDIR /etc/ssl/certs #--end-- 4) Put the hostname in the "user import" screen of YubiRADIUS instead of the IP address (Make sure the host entry is present in the DNS server or in /etc/hosts file) YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 56 of 68

13 Appendix 4: Importing Users from Active Directory/OpenLDAP 13.1 Importing Users from Active Directory: The organization in this example uses Active Directory (AD) to organize users. They have offices around the country, with one AD domain for all locations. Each office has their users organized in one or more Organizational Units (OUs). There are only a few users from each different office that initially (during a testing period) will be given the privilege to log in remotely using YubiKey two-factor authentication. We are assuming that Active Directory domain is configured at IP address 192.168.1.48 in domain yubiradius.com hence Base DN is DC=yubiradius,DC=com We want to import the users managed by user Administrator hence User DN is CN=Administrator,CN=Users,DC=yubiradius,DC=com We put an Administrator account password of AD in the password field and set the filter as (ObjectClass=person) and the Login Name Identifier as samaccountname A sample configuration for Active Directory is shown in the image below: Importing Users from OpenLDAP server on the YRVA instance: For quick evaluation and testing, the YubiRADIUS Virtual Appliance comes preconfigured with an OpenLDAP server with1 administrator and 5 users defined in an Organizational Unit. User names are from user1 to user5 and all users have the same password yubico The domain preconfigured for OpenLDAP server is example.com, hence the Base DN is DC=example,DC=com. We want to import all the users managed by the Admin user, hence User DN is CN=admin,DC=example,DC=com YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 57 of 68

We put the admin user account password of LDAP in password field (yubico), the filter as (ObjectClass=person) and the Login Name Identifier as uid A sample configuration for OpenLDAP is shown in the image below: Save the configuration by clicking on the Save button and then click on the Import Users button to import the users. After a successful communication with the OpenLDAP Server, a message will be displayed indicating that users have been imported successfully. The users and groups will be displayed in the Users/Groups tab according to their hierarchy in the Active Directory as shown in the image below: YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 58 of 68

In the above image, all the groups are displayed. If you click on the group you can see the users belonging to that group. For Example: If you click on the Domain Users, all the users belonging to the group Domain Users will get displayed on the screen, as shown in the image below. In the case of importing the users from LDAP, we get the users and OUs according to their hierarchy in the LDAP in the Users/Groups tab. For Example: After importing the users from LDAP, as shown in the below screen, we have OUs (like groups, people) as well as users present inside the domain (like EXUser1) YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 59 of 68

If you click on the people, all the users and OUs present in the OU people are displayed. Here we get admin_users OU along with all the users that belongs to the OU people. If you click on the OU admin_users you will get the all the users and OUs belonging to the OU admin_users and so on. Special group All Users display a list of all users in the LDAP or AD. Sometimes it is easier to just view all users without worrying about what OU or Group they are a member of. YubiRADIUS therefore automatically create a special single group called All Users displaying all the users present in the LDAP/AD. When you click on the All Users, all the users present in AD/LDAP are displayed in alphabetical order. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 60 of 68

After importing the Users along with their hierarchical information from LDAP/AD, any group which does not contain any (imported) users are not displayed in the Users/Group tab. 13.2 Importing users with a specific group membership: YubiRADIUS can be set up to import users from different OUs but having specific group membership. The Directory administrator can set up a new group in AD called testing. The group testing can then be added to the AD import filtering import criteria and thereby only users in the testing group will be imported. See below for steps to set it up: 1) We are assuming that the Active Directory domain is yubiradius.com and all the users that need to use Yubikeys have been assigned to be members of the group called testing. The complete distinguished name (DN) of the testing group is CN=testing,CN=Users,DC=yubiradius,DC=com 2) In order to import only users belonging to this group, testing under OU Users, you need to provide the Filter in the Users Import field as follows: memberof=cn=testing,ou=users,dc=yubiradius,dc=com 3) The rest of the parameters will remain the same. A sample import configuration with all parameters filled out is shown on the image below: 13.3 Importing users from multiple groups: 1) It is possible to import users belonging to multiple groups. See the example below. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 61 of 68

2) In the domain Yubiradius.com you need to import the users belonging to both groups testing and marketing 3) The complete DN of testing group is CN=testing,CN=Users,DC=yubiradius,DC=com. 4) The complete DN of marketing group is CN=marketing,OU=test,DC=yubiradius,DC=com 5) In order to import only users belonging to both these two groups, you need to apply the Filter in the Users Import field as follows: ( (memberof=cn=testing,cn=users,dc=yubiradius,dc=com)(memberof=cn=marketi ng,ou=test,dc=yubiradius,dc=com)) 6) The rest of the parameters will remain the same. A sample import configuration with all parameters filled out is shown on the image below: That if username is changed in AD/LDAP, after importing users again, then the new username gets assigned to respective uid and all the YubiKey credentials get assigned to the new username. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 62 of 68

14 Appendix 5: Web API The Yubikey provides secure additional authentication factor to web services and the various other applications. YubiRADIUS Validation Protocol is a Web API from YubiRADIUS virtual Appliance that can be used for YubiKey-based strong two-factor authentications using an existing enterprise directory. The Web API leverages existing YubiRADIUS capabilities to provide strong two-factor authentication. The Web API verifies the username+password+yubikey OTP as per the configuration defined in the YubiRADIUS Virtual Appliance. Web API validate the OTP first with online validation server and if that fails then with Local validation server. After successful validation it will verify username password with LDAP or AD then it checks the mapping of the registered YubiKey and provided OTP. If the Yubikey is not mapped to any user and Auto Provisioning is enabled then that YubiKey will; automatically be assigned to the user that supplied the OTP. Please Refer following document for more information about the Web API YubiRADIUS_validation_protocol.pdf is available from the http:www.yubico.com/yubiradius/ page YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 63 of 68

15 Appendix 6: YubiApp Registration YubiApp Registration service provides ability to generate keys to provision the YubiApp software based backup to physical YubiKey(s) to be used on Smartphone or Tablets. This allows a user to use a backup method on the phone if a user forgets their YubiKey at home or while waiting for a new YubiKey if the physical YubiKey gets lost or stolen. The backup YubiApp requires the user s physical YubiKey to register and generate the AES key to be used in the YubiApp. Up to three YubiApps can be registered for each physical YubiKey. Once registered the YubiApp provides the user with two factor YubiKey authentication on Smartphones or Tablets without having immediate access to the physical YubiKey. Please note that because the AES key for the YubiApp is stored on the Device the YubiApp does not provide the same security against being hacked compared to a physical YubiKey and should only be used most sparingly in an organization. 1) Configuration: YubiApp Registration service must be enabled at two levels: First Global configuration to enable YubiApp: Administrator can enable/disable YubiApp registration at a global level in General menu from Global Configuration tab. Please note that Global enabling/disabling the YubiApp Registration will affect all the domains. See next page for enabling YubiApp at the Domain level. Next Domain Configuration to enable YubiApp: YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 64 of 68

Administrator can enable/disable the domain level YubiApp configuration under domain>> Configuration tab. 2) YubiApp registration: User can access YubiApp Registration service on following URL: https://<ip address of the YubiRADIUS virtual appliance>/yubiapp/ Above URL will take the user to YubiApp Registration page. YubiApp Registration page also provides the link to download the android application for mobile phones. For example, we have user1 from yubiradius.com YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 65 of 68

Note that if YubiRADIUS contains only a single domain, then the YubiApp registration can be done by simply entering the login name rather than the login name followed by the domain name. For example: If we have user1 from yubiradius.com, and yubiradius.com is the only domain available, then the user can enter user1 as a Username for YubiApp registration, as opposed to user1@yubiradius.com. Please refer following screenshot: If Username, Password and OTP (One Time Password) from physical YubiKey is valid, then only YubiApp Registration allows user to create (backup YubiKey) soft-yubikey tokens. After a successful validation, a user can select any key as a backup YubiKey in YubiKey Type drop-down box. When a user selects a backup YubiKey from YubiKey Type, the corresponding QR code gets generated. Then the user will need to capture the QR code in the mobile device and will be able to generate the soft key tokens. Once the user clicks on the Continue to upload AES key, the backup YubiKey gets added to the database and gets assigned to the corresponding user. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 66 of 68

Hence the user can self-generate YubiApp (Soft-YubiKey OTPs) for their smart phone for mobile based two factor authentication. YubiKey Import File: When the YubiApp Registration successfully completes, the corresponding backup Yubikey details (like AES Key, Public Id) gets stored in the YubiApp_import.csv file which is present at location: /var/www/yubiapp/import. Under Synchronization tab, administrators can import the YubiApp_import.csv file on synchronized instances so that backup YubiKey functionality can be used with synchronization. YubiApp_import.csv file is a log file containing backup YubiKey credentials in the Original Windows Personalization Tool format. (1,ejcbfgjjlftu,108c23fed523,6f4e4acb435b11455f8daa6dc49e41dd,000000000000,,,) The Administrator can import YubiApp_import.csv file manually from YubiKeys Import tab of the corresponding domain to add these backup YubiKeys on synchronized instances. YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 67 of 68

16 Appendix 7: YubiRADIUS Virtual Appliance Port Information Sr. No Protocol Port 1. LDAP 389 2. LDAPS 636 3. Webmin 10000 4. Validation Request to the YubiHSM 8002 5. freeradius 1812 6. Web-API 80 7. ykval 80 8. ykropval 80 9. Ykmap-sync 80 10. Ykval-sync 80 YubiRADIUS Virtual Appliance 2012 Yubico. All rights reserved. Page 68 of 68