Import OATH tokens in bulk

This topic describes how to bulk upload third-party OATH tokens to authenticate with CyberArk Identity (for example, using tokens generated by a YubiKey). CyberArk Identity uses those tokens to generate time-based (TOTP) or counter-based (HOTP) one-time passcodes that users with enrolled devices can immediately use to log in to the User Portal.

Users without enrolled devices must first log in to the User Portal and scan the CyberArk Identity generated QR code (using a third-party authenticator) to get the passcode pushed to the device.You can direct users to Set up OTPs to authenticate. For details regarding enrolled device support, see Supported devices.

When you upload tokens, they override any existing passcodes users may have generated by scanning the CyberArk Identity generated QR code.

Prerequisites

Verify that you have the following prerequisites before you start importing the OATH tokens:

  • A CSV file with token information (a CSV file template is available on the bulk upload page in the Identity Administration portal).

    CyberArk Identity validates one OATH token per user. If your CSV file contains more than one OATH token for the same user, the last token (the one lowest in the spreadsheet) is validated for that user.

  • Third-party OATH tokens (for example, those generated by a YubiKey; see Additional configuration for YubiKey HOTP).

    If you are using YubiKeys you also need the Personalization Tool (to download the YubiKey Personalization Tool, refer to https://www.yubico.com/support/download/yubikey-personalization-tools/).

Upload OATH tokens

The following procedure describes how to upload your OATH tokens from an already-configured CSV file for validation by CyberArk Identity.

If you have not enabled the OATH OTP policy (refer to Enable OATH OTP) and OATH OTP Client in the Authentication Profile (refer to Create authentication profiles), you need to do so before users can use the generated passcodes. When you configure the OATH OTP policy, you can also define if users can see the QR code from the User Portal.

To bulk upload OATH tokens

  1. Log in to the Identity Administration portal.
  2. Navigate to Settings > Authentication > OATH Tokens.

  3. Click Bulk Token Import.

    If you don't have a CSV file already configured, click the Bulk Authentication Token Import Template link to download a CSV template and update it.

    The CSV file must have the following column headers (header names must match exactly):

    • User Principle Name

    • Token Identifier

    • Secret Key (HEX)

    • Account Name

    • Issuer

    • Algorithm

    • OTP Digits

    • Type

    • Period

    • Counter

    The Secret Key must be in HEX format. For YubiKey configuration details, refer to Additional configuration for YubiKey HOTP.

  4. Click Browse, navigate to your CSV file, and upload it.

  5. Click Next.

  6. Review the first 15 rows and if they look correct, click Next.

    If you see an error, cancel the upload and fix the error.

  7. Confirm the email address or enter a different one where the bulk import report is sent.

  8. Click Confirm.

    A bulk import report email is sent to the specified email address.

  9. Refresh the OATH Tokens page to see the uploaded instance.

Additional configuration for YubiKey HOTP

This topic supplements the token upload information in the previous procedure and provides guidelines on how to configure a YubiKey to work with CyberArk Identity for HMAC-based one-time passcode (HOTP) MFA challenges. Using the YubiKey Personalization Tool, you can program the YubiKeys and generate the secret key for each YubiKey. The secret key can then be entered into the token import CSV file used in To bulk upload OATH tokens.

Step 1: Program the YubiKey using the YubiKey Personalization Tool.

  1. Insert the YubiKey.

  2. Launch the YubiKey Personalization Tool.

    For information on downloading the YubiKey Personalization Tool, refer to https://www.yubico.com/support/download/yubikey-personalization-tools/.

  3. Click OATH-HOTP and then click Quick.

  4. In the OATH-HTOP mode - Quick screen, configure the following settings:

    • Select Configuration Slot 2.

    • Uncheck Hide secret.

    • Copy the Secret Key to be added to the CSV later.

    • Click Write Configuration.

Step 2: Edit the CSV file with the YubiKey information and upload it to the Identity Administration portal.

To upload the YubiKey information, see To bulk upload OATH tokens. Make sure you include the following information in the CSV file for YubiKey HOTP implementations:

Column header Configuration
User Principal Name Enter the user's sign in user name.
Secret Key (HEX) Paste the secret key you copied from the YubiKey Personalization Tool. If you forgot to copy the secret key, you can retrieve it from the configuration log file available as output from the YubiKey Personalization Tool.
Account Name Enter the user’s display name.
Issuer Enter any name, such as your organization’s name.
OTP Digits Leave the value as 6 (only change the value if you configured the YubiKey to use 8 digits).
Type Change the value to Hotp.
 

Set up OTPs to authenticate

Enable OATH OTP

Create authentication profiles