Utilizing Yubico 2FA

Introduction

Document Number

ENG-010624

Purpose

This document will describe how to use Yubikey secure Tokens as the 2^nd authentication element in a 2FA system.  The Yubikey token generates OTP (One Time Passwords) that can be used for authentication. The Yubico secure tokens can be utilized in conjunction with any of the existing EMS or OLT authentication mechanisms.

Applies To

This applies to all OLTs and the Panorama EMS when running software release SR31.1 or above.

Definitions

2FA - Two-factor authentication.  Authentication where the user is prompted to provide two authenticators to verify the identity of the user.  Usually one is related to something you possess like a token, and the other is typically a password that is only known to that user.  Authentication only proceeds if the user has the proper token and knows the proper password for the account.  This helps provide more security.

OTP - One-Time Password.  The Yubikey token generates One-Time Passwords that can be validated by the authenticator as being generated by a specific user’s token.  The authenticator ensures that an OTP is never re-used or used out of order.  The authenticator will fail to authenticate an OTP that it determines has been used before.

Yubikey Token - The USB stick that generates OTPs or One-Time Passwords

Yubikey TokenID - The unique identifier of the Yubikey token that appears in the first 12 characters of all OTPs.

Yubico Authentication Model

The diagram above documents the standard Yubico authentication model.  These are the following components:

Yubico Client - The local application / driver that collects the OTP and forwards it to the Yubico Authentication server and enforces the result of authentication.  It depends on the type of authentication being used whether this is needed.

Yubico Authentication Server - The Yubico Authentication server receives authentication requests and responds with a pass / fail result back to Yubico Authentication clients.  The Yubico authentication server also records all used OTPs and checks to ensure the OTP has not been used before an that the OTP is not an older/stale OTP.

 The typical sequence of authentication is as follows:

1. The user plugs in the Yubico FIPS token into the machine.  
2. The user is prompted for username, password, and OTP.  When the user presses and holds the button on the Yubikey token, it will put a One-Time Password (OTP) into the currently selected field.  The local client will check the username to Yubikey binding to ensure the user matches what is configured on the OLT.  It will then send the OTP to the authentication server.
3. The Yubikey client will pass the OTP to the Yubikey Authentication server via an encrypted path.  
4. The Yubikey authentication server will validate that the OTP has not been used before, ensure that it is a newer OTP than the last one received, and return a result to the client if pass or fail.
5. If the OTP authentication result passes, the local authenticator at the OLT or EMS will then perform the normal username/password check via whatever mechanisms are in use.  If both the username password and the Yubico OTP pass, the user will be allowed access to the resource.

EMS Yubico Authentication

The two-factor authentication feature is enabled as a method for the Panorama PON Server to grant users access only after successfully presenting two pieces of evidence to the authentication mechanism.   One piece is the traditional user and password, the other is provided by a Yubikey OTP.   Each Yubikey token is bound to a single EMS user and users cannot share a key.  All users are required to have a Yubikey token prior to enabling Yubikey support.

By default, Panorama PON is configured to use the Yubico proprietary YUBICLOUD server.  In addition, a Validation Server is made available via Panorama PON's HTTPS Server.  Additional configuration is required, if the Panorama PON OTP Validation Server (POVS) is required, typically when internet access (and or the YUBICLOUD server) is not available.   The recommended mechanism is to use the EMS-hosted Yubikey Authentication Server (POVS) as it will continue to work even when connectivity to the internet is lost.  YUBICLOUD authentication requires internet access to access the cloud-based Yubikey authentication server.  

 Yubikeys have two slots available.  The first slot is already configured to function with YUBICLOUD and is activated with the Yubikey short button press (1-2) seconds.   Slot two is activated via the long button press. The user should simply hold down the button on the Yubikey until an OTP comes out on the screen.  The second slot is typically configured for use with an external (non YUBICLOUD) server.      

The second slot will need to be reprogrammed, and the private key registered with the Authentication Server.

The following section shows what the 2FA login screen will look like for the EMS:

The user will be prompted for the username, password, and One Time Password (OTP).

When entering the OTP, place the cursor into the One-time Password field, then hold down the button on the Yubikey until the Yubikey fills in the One-time password field.  If all three fields are valid, then the user will be allowed into the system.  If any of the three fields are in error, the user will not be allowed access to the EMS.

Setting up the EMS for 2FA with Yubikey OTP

The following section will detail the steps to set up the EMS for 2 factor authentication using the Yubikey OTP.

The steps for setting Yubico authentication are:

• Enable Panorama OTP Validation Server (POVS)
• Register all the Yubikey tokens with the validation server.
• Validate each Key to ensure it is properly registered with the server
• Bind each Yubikey token to a user
• Enable 2FA on the EMS
• Restart the EMS Server
• Restart the EMS client

Enable the Panorama OTP Validation Server (POVS)

The validation server is a process in the EMS server that performs Yubikey validations.  This server simply validates whether a Yubikey token is known and whether an OTP given to it is valid for a given token, hasn’t been used before, and is in sequence.  This server is not started by default and must be manually started.

Open Windows CMD Shell with elevated privileges (i.e. as administrator)

    cd %EMS_HOME%server

    OTPMgr.bat

You are presented with the following menu after entering a Panorama PON Administrator's credentials;

To enable POVS, select menu item 8 (Local OTP Verification Server Menu).  You are presented with the following menu options:

Select item 1, Enable Local OTP.

The user should see that the Local OTP Validation has been enabled, and the default Yubicloud OTP validation was disabled.  It is required to restart the EMS for this change to take effect.

Register Yubico Tokens

The next step is to register Yubico tokens to the POVS Panorama OTP Validation Server.  

Registration of youbikeys should not be attemped until 2fa is enabled as defined in the step above  and the EMS has been rebooted.

If using POVS, the yubikey slot 2 needs to be configured and registered.   To configure the yubikey, administrators must download and run the YubiKey Personalization Tool.

    https://www.yubico.com/products/services-software/personalization-tools/use/

The user will be presented with the following interface:

Select Yubico OTP Mode.

Click on Quick.   The user is presented with the following Dialog:

Select Configuration slot 2, then press regenerate.  This is needed to generate a new secret key that is needed to register the Yubico token to the authentication server.  This is the only time and only way a secret key can be obtained.  Once written, it can never be viewed again.

Care should be taken to protect the private key. This must be guarded very carefully.  It should simply be used to register the token, then it should be discarded, and no record should be kept of it unless the key is used with multiple authenticators.  A bad actor with a private key can compromise the system.

Save the private key to the cut/paste buffer or in a temp text file.  Then press Write configuration to write the keys to the Yubikey token.

Go back to the OTP manager application and select option 3, Register OTP Key.

Paste in the private key that was saved from the Yubico personalization tool when prompted as below.

Enter the AES/Secret Key in Hex format:

Paste in the Secret key.  Then discard the key.  

Plug in the Yubico token, and when the EMS Prompts with:

Enter the OTP:

Do a long press on the Yubikey.  The token private key and public key is now securely stored in the authentication server and can be used for authentication.

Configuring User/Key Associations

This step should only be used for associating EMS usernames with EMS logins.  This step can be skipped for olt users.  OLT users only need to register the key but do not need to associate a username. This is done at the OLT.  When used for EMS authentication Yubikeys need to be associated with specific users and must be unique.  That is, each Panorama PON user is assigned (and associated with) a different Yubikey token.   To associate a user with a Yubikey, use the OTPMgr.

Enter the username to associate the key with.  Then at the Enter the OTP prompt, do a long press on the Yubico Token.  Look to ensure that the token ID is repeated with the OK indication which indicates the Token to user association was accepted into the database.  This binds the token to a specific user in the EMS.  Repeat this for every user of the EMS.  Please note that users cannot share keys.

The key to user bindings can be viewed using the menu item 5.  Since this displays the public key, there is no security concerns with displaying this information.

Key bindings can be added or deleted using the menu items create / modify / delete.

You can re-validate a key binding using item 4.   If you need to re-validate a key binding and are using POVS, the Panorama PON Http Server must be running.   If you need to re-validate a key binding and are using Yubicloud, the Panorama PON Http Server does not need to be running.

When prompted with Enter the OTP, do a long press on the Yubico token button and if the binding is valid, you should see the key repeated with OK after it.  This indicates the validation was successful, and the key is ready for use.  It is a good idea to do this validation to ensure any problems with login are not due to the Yubico token setup.

Enable Yubico 2FA in the EMS

Once all users have an associated Yubikey token, the Yubikey 2FA can be enabled.
To enable 2FA, refer to the OTPMgr menu above.  Select menu item 6 (Enable 2FA).  Panorama PON (all of the services) must be restarted for the changes to take effect.  

The user must stop and restart the Panorama PON Server before the changes will take effect.  Use menu items 10 and 11 to accomplish this.

At this point the EMS will begin prompting for username, password, and Yubico OTP.

When, entering the One Time Password in the EMS, put the cursor in the One Time Password and do a long press of the button on the Yubikey.

Utilizing the Yubico cloud Authenticator for EMS logins

The Yubico Cloud is configured much the same as the POVs, with one exception.  The Panorama OTP Validation Server is disabled.  This will force all authentication on the EMS for 2FA through the Yubico cloud server.

Option 8 on the main menu of the OTP configuration script will bring up the Local OTP Verification Server Menu.

Then press 2 to ensure the Local OTP server is disabled.

Ensure the user always uses the short press (1-2 seconds) to get OTP slot 1 which has the public/private key which is registered at the time of manufacture with the Yubico cloud server.

All other steps are the same.

OLT Yubico Authentication

The OLT also supports Yubico Authentication, utilizing Yubico 2-Factor authentication using Yubico OTP (One-Time Passwords).  The OLT must be configured to utilize the Yubico OTP in a manner very similar to the EMS.

The steps are as follows:

• Register the Yubico Tokens with the Panorama OTP Validation Server (POVS)
• Configure Trust Anchor to use for Authentication Link
• Configure the Yubikey URL for authentication
• Configure the Authentication Server IP
• Configure the Authentication Server ID
• Reboot
• Configure User to Yubico Token Associations
• Enable Yubikey 2FA on OLT
• Login using 2FA on the OLT

 Register Yubico Tokens for OLT

It should be noted that Tokens can be registered with the EMS, and then used for the same user on the EMS and CLI.  The user binding is held in each authentication client and therefore a single token can be used to log the user into either the EMS or the OLT.

Configure Trust Anchor to use for Authentication

The link to the authentication server must be secured by a certificate.  The trust anchor for that certificate must be stored in the Yubico authentication client.  If a site-specific certificate has be placed on the EMS, the trust anchor should be used.  Otherwise the default Tellabs certificate can be used for this purpose.

The default trust anchor to be utilized when using the EMS POVS can be found in the following folder:

     C:TellabsPanoramaPONbbmgrserverdataAuthenticationControllerems_anchor.pem

It is also posted on the AppNote in the same section as this document.

Then log into the OLT ssh session as a certificate admin user.  This function can only be done by a user of that type.  Normal users cannot perform this function.

 The user can validate it was accepted by issuing the following command:

ne security yubikey show cert  

Configure the server hostname

 The user needs to configure the hostname of the EMS server which will serve as the Yubikey authenticator.

Configure the EMS IP address

The IP address of the EMS must be configured via the following command: 

 The user can verify the configured IP as follows:   

After setting the IP you need to reboot or switch the ESU to protection to ensure that the host table entry gets written out.

Configure User / Key Associations

All of the users now need to bind their tokens to their CLI username using the command shown below:

Use the command:

    Yubikey edit user=<username> terminal

When prompted to enter the Yubikey Token ID, simply do a long press on the Yubikey.  It will output a valid OTP.  The first 12 characters of the OTP is the public key which is used to bind the user to the token.

 The user can list the binding for each user using the Yubikey show command as follows:

Show all yubikey associations and public keys as follows: 

Enable Yubico 2FA on the OLT

The next step is to enable Yubico 2FA on the OLT.  The system will not allow enabling of 2FA unless all users in the user database have a user to Yubikey token binding.

The following command enables Yubico 2FA on the OLT:

     ne security Yubikey edit admin=enabled.

The command can only be issued by a user with the Security Admin (sec-admin role).  Once the command is enabled, users will be forced to ssh using Yubico 2FA.

    Logging into OLT using Yubico 2FA

The procedure for logging into the OLT differs slightly with SR31.1 in order to accommodate the Yubico 2FA.  The user must use the keyboard interactive mode when logging in. 

  The user will then be prompted for the Yubikey OTP.

Do a long press on the Yubikey Token which will send the OTP assigned to slot two in the Yubikey.

The user will then be prompted for the user’s password:

If a valid username is entered, a valid OTP for that user, and the correct password for that user, access is allowed.  Otherwise, access is denied.

If the Yubico server is not available, all SSH access will be denied.  The serial port can still be used to access the system.

If using Putty, it will automatically detect the keyboard interactive mode, and the user will be prompted as follows: 

At the login as: prompt, enter your username.

At the YubiKey for: <username> prompt, do a long press on the Yubikey button.

At the password prompt: enter your password.

If all three are correct, the user will be allowed access.  If any of the three are incorrect, no access will be granted.

Deleting Existing Users

A user can be deleted via the following command: 

Deleting an Anchor Certificate

The anchor certificates can be deleted from the OLT as follows, please note that this will disable yubikey as these certificates are needed to authenticate transactions: 

Using Yubico Cloud Authenticator

To utilize the Yubico Cloud Authenticator the following steps should be followed:

• Set the URL to the Yubico Cloud Authenticator
• Add the IP of the Yubico Cloud Authenticator
• Set the ID to 16 which is the default for the Cloud Authenticator.
• Enable the 2FA service.

To set the URL to point to the Yubico Cloud Authenticator, set the url as follows:

Ping the address api-yubico.com, add the IP address of the Yubico Cloud authenticator.

 A user can verify the IP and URL with the following commands.

Set the Yubikey application ID to 16 which is the default used by the Yubico Cloud Authenticator.

ne security Yubikey cfg id=16

Configure the User to Yubico Token Associations and Enable 2FA on the OLT as shown above.  You should be able to log in using the Yubikey token via the Yubico cloud authenticator.

If the user has any issues, make sure the user can ping the Yubico server at api.yubico.com to validate IP connectivity to the site. 

Yubikey Debug 

The OLT also supports several CLI commands for debugging the current configuration of Yubikey.

The trust anchor certificates that allow trust of the EMS Yubikey validator can be displayed: 

Display of just the certificate subject name and issuer is also supported: 

The yubikey debug also supports a configuration check: 

Perform a test transaction with the EMS: 

Verify whether a given key is registered at the EMS authentication server.  Issue this command, performing a long press at the appropriate time: 

Turn on Debug logging for yubikey: 

Display whether is enabled or disabled: