Documentation

Introduction

A YubiKey device, made by Yubico, generates One-Time Passcodes (OTPs) end-users can use to Pre-authenticate themselves so they can be presented the delivery methods page, and then complete the authentication workflow to access the intended realm.

The YubiKey must first be provisioned as a registered device in the end-user account before it can be used for this purpose.

This guide provides instructions for:

  • Administrators to configure a realm for end-users to provision their YubiKeys to register the devices in their accounts. NOTE: This realm must be configured to provision a YubiKey device and validate the YubiKey ID.
  • Administrators to configure a Self Service account realm end-users can access to manage their YubiKeys. NOTE: This realm must be configured to validate YubiKeys.
  • End-users to provision their YubiKeys.
  • End-users to pre-authenticate themselves using their YubiKeys so they can be presented the delivery methods page, authenticate themselves, and manage their YubiKeys on the Self Service page.
Prerequisites

1. Have access to

  • One or more types of YubiKeys (YubiKey 4, YubiKey 4 Nano, YubiKey 4C, YubiKey Neo) to test configured SecureAuth IdP realms
  • The Yubico site to verify the SecureAuth IdP can communicate with the Yubico API endpoint

     Yubico API URLs...
    HTTPHTTPS
    • "http://api.yubico.com/wsapi/verify?id="
    • "http://api2.yubico.com/wsapi/verify?id="
    • "http://api3.yubico.com/wsapi/verify?id="
    • "http://api4.yubico.com/wsapi/verify?id="
    • "http://api5.yubico.com/wsapi/verify?id="
    • "https://api.yubico.com/wsapi/verify?id="
    • "https://api2.yubico.com/wsapi/verify?id="
    • "https://api3.yubico.com/wsapi/verify?id="
    • "https://api4.yubico.com/wsapi/verify?id="
    • "https://api5.yubico.com/wsapi/verify?id="

2. Create two realms on SecureAuth IdP v9.1 or later

  • Realm A to be used for provisioning end-user YubiKeys to register the devices in their accounts
  • Realm B to be used for validating end-user YubiKeys so the delivery methods page can be presented, and end-users can authenticate themselves and access the Self Service page to manage their YubiKeys

3. Configure the following tabs of the Web Admin on SecureAuth IdP realms A and B

  • Overview – the description of the realm and SMTP connections must be defined
  • Data – one or more data stores can be integrated with SecureAuth IdP
  • Workflow – the way in which users will access the target must be defined
  • Multi-Factor Methods – the Multi-Factor Authentication method that will be used to access the target (if any) must be defined
  • Post Authentication – the target resource or post authentication action must be defined
  • Logs – the logs that will be enabled or disabled for this realm must be defined
SecureAuth IdP Configuration Steps
Realm A
Data

 

1. In the Profile Fields section, specify the search attribute (configured in step 1) as the Hardware Token and make the field Writable

Or, as an alternate, specify the search attribute (configured in step 1) as Aux ID 1 and make the field Writable

Click Save once the configuration is complete and before leaving the Data page to avoid losing changes 

Workflow

 

2. In the Workflow section, under Login Screen Options, specify the workflow to use, making a selection from the Default Workflow dropdown

In the example, with Username only selected, the end-user only needs to enter the username and use the YubiKey device to be authenticated

NOTE: If selecting Username | Password, in which the password entry would be required on the second page, after using the YubiKey device, the end-user is authenticated and the password entry page is skipped

3. Select Public Mode Only from the Public / Private Mode dropdown

4. Select False from the Remember User Selection dropdown

Click Save once the configuration is complete and before leaving the Workflow page to avoid losing changes 

Post Authentication

 

5. Select Yubikey Provisioning from the Authenticated User Redirect dropdown

When making this selection, Authorized/YubikeyProvisioning.aspx appears in the Redirect To field below – this field cannot be edited

Click Save once the configuration is complete and before leaving the Post Authentication page to avoid losing changes 

See End-user Provisioning for the end-user experience resulting from this configuration 

Realm B
Data

 

1. In the Membership Connection Settings section, specify the same Search Attribute entered in the Hardware Token field in the Profile Fields section (see step 3 below)

This attribute stores the information which identifies the unique YubiKey ID used by YubiKey to validate the hardware token

2. Enter the specified search attribute in the searchFilter field

 

3. In the Profile Fields section, specify the search attribute (configured in step 1) as the Hardware Token and make the field Writable

Or, as an alternate, specify the search attribute (configured in step 1) as Aux ID 1 and make the field Writable

Click Save once the configuration is complete and before leaving the Data page to avoid losing changes 

Workflow
Workflow

 

4. Under Login Screen Options, specify the workflow to use, making a selection from the Default Workflow dropdown

In the example, with Username | Second Factor selected, the end-user only needs to enter the username and use the YubiKey device to be authenticated

NOTE: If selecting Username | Password, in which the password entry would be required on the second page, after using the YubiKey device, the end-user is authenticated and the password entry page is skipped

5. Select Private Mode from the Public / Private Mode dropdown

6. Select False from the Remember User Selection dropdown

7. Optionally, select True from the Show UserID Textbox dropdown to have the User ID appear on the post authentication page

Custom Identity Consumer

 

8. In the Custom Identity Consumer section, select Token from the Receive Token dropdown

9. Select True from the Require Begin Site dropdown

10. Select YubiKey from the Begin Site dropdown – note that YubiKeyValidation.aspx appears by default in the Begin Site URL field; this entry cannot be modified

Click YubiKey Settings to configure YubiKey Settings in the Multi-Factor Configuration section on the Multi-Factor Methods tab

Be sure to click Save before clicking YubiKey Settings to avoid losing configuration settings made on the Workflow page 

11. Enter the URL of the realm configured for the YubiKey Provision Page – e.g. https://company.com/SecureAuth#

The end-user will be redirected to this URL if the YubiKey device is not yet provisioned

12. Select Name from the Token Data Type (Receive) dropdown

13. Select User ID from the Token Data Type (Send) dropdown

Click Token Settings to configure YubiKey token settings in the Forms Auth / SSO Token section on the Post Authentication tab

Be sure to click Save before clicking Token Settings to avoid losing configuration settings made on the Workflow page 

14. Select True from the UserID Check dropdown

Click Save once the configuration is complete and before leaving the Workflow page to avoid losing changes 

Multi-Factor Methods

 

15. In the Multi-Factor Configuration section, select and configure Multi-Factor Authentication methods to be made available to the end-user during authentication

16. Under YubiKey Settings, select Disabled from the YubiKey Authentication dropdown

When making this selection, Hardware Token appears in the Store YubiKey data in field below – this field cannot be edited

If Enabled is selected from the YubiKey Authentication dropdown on a realm currently configured as a Begin Site for Pre-authentication, then the warning icon (white exclamation symbol in a red circle) appears beside this field

See sample image showing warning icon...

Hover over the icon to view information pertaining to the warning which specifies a realm configured as a Begin Site for Pre-authentication should not also be configured for Multi-Factor Authentication

17. If the YubiKey device AND an OTP from the device is required for authentication, select True from the Validate Yubikey dropdown

If the YubiKey device only is required for authentication, select False from the Validate Yubikey dropdown

Click Save once the configuration is complete and before leaving the Multi-Factor Methods page to avoid losing changes 

Post Authentication
Post Authentication

 

18. Make a selection from the Authenticated User Redirect dropdown to specify the type of page the end-user will access after successfully authenticating – example: Self Service Account Update

In this example, with Self Service Account Update selected, Authorized/AccountUpdate.aspx appears in the Redirect To field below and cannot be edited

Click Save once the configuration is complete and before leaving the Post Authentication page to avoid losing changes 

Identity Management

 

19. In the Identity Management section, click Configure self service page

NOTE: Refer to Self-service Account Update page configuration for more information about configuring a self service page

Self Service

 

20. On the Self Service page, configure settings for the page and set YubiKey to Show Enabled

If Aux ID 1 is specified on the Data tab (in step 1) as the Profile Field in which to store YubiKey data, then set Aux ID 1 to Show 

Click Save once the configuration is complete and before leaving the Self Service page to avoid losing changes 

See End-user Pre-Authentication for the end-user experience resulting from this configuration 

End-user Experience

End-user Provisioning

These steps register the YubiKey device in your account.

 

1. Enter your Username and click Submit

2. Place the cursor in the text box

3. Plug the registered YubiKey device into the USB port and touch the sensor button on the device

 

 


 

 

4. Upon verification by the Yubico website, the validated YubiKey ID is saved to your profile

 

 

 

End-user Pre-authentication

These steps show how the YubiKey device is used to Pre-authenticate you and present the delivery methods page. Once you are authenticated, manage the device on the Self Service page.

NOTE: The sample end-user workflow shown below is pertinent to the settings made in the steps above – workflows will differ based on the realm configuration made in each customer environment.

 

1. Place the cursor in the text box

2. Plug the provisioned YubiKey device into the USB port and touch the sensor button on the device

3. Select the passcode delivery method and click Submit

 

 

 


 

 

4. Enter the passcode and click Submit

5. The Self Service page shows your device's YubiKey ID beside the YubiKey Device checkbox – this information also appears in the User ID field above

 

NOTE: To remove the YubiKey device from your profile, uncheck YubiKey Device, and then click Update

 The YubiKey device must be provisioned again if the device will be re-associated with your profile

  • No labels