How to Configure OATH OTP

You can enable users to scan a IBM Security generated QR code (using a third party authenticator application or the IBM Security application) to authenticate to Privileged Access Service. A one-time-passcode (OTP) is displayed and users can use that OTP to log in to Privileged Access Service. You can direct users to Using OTPs to Authenticate.

Additionally, you can upload existing OATH tokens and allow users to authenticate using the one-time passcode generated from those tokens. See Importing OATH Tokens in Bulk

Important: You must configure an authentication rule with the OATH OTP mechanism enabled in the associated authentication profile for the relevant policy. If you do not have this configured, users will not be able to authenticate using the QR code. See Creating Authentication Rules.

To Enable the OTP Policy

  1. Log in to Admin Portal

  2. Click Access > Policies.

  3. Select a policy set or create a new one.

  4. Click User Security > OATH OTP.

  5. Select Yes in the Allow OATH OTP Integration drop down.

  6. Click Save.

  7. Select the policy you created. Enable users to configure an OATH OTP client.

    1. Select User Security > Authentication Settings.

      The Authentication Settings window opens.

    2. Select Yes in the Enable user to configure an OATH OTP client.

    3. Enter a user-friendly name (for example the name of the OTP client used by your organization) in the OATH OTP Display Name text field. This name is what users will see.

    4. Select an authentication profile to require users to provide additional authentication before they can access the QR code.

  8. Click Save.

Importing OATH Tokens in Bulk

You can authenticate with Privileged Access Service using your existing third-party OATH tokens (for example, those generated by a YubiKey) by bulk uploading those tokens. Privileged Access Service uses those tokens to generate one-time passcodes (OTP) that users with registered devices can immediately use to log in to the admin portal.

Users without registered devices must first log in to the Admin Portal and scan the Privileged Access Service generated QR code (using a third party authenticator) to get the passcode pushed to their devices. You can direct users to Using OTPs to Authenticate.

When you upload these tokens, they will override any existing passcode users may have generated by scanning the Privileged Access Service generated QR code.

Prepare the CSV File

Prior to importing OATH tokens, you need a CSV file containing information for each token. Privileged Access Service 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.

The CSV file must contain the following column headers and the header names must match the ones listed below:

A CSV file template is available on the bulk upload page in Admin Portal.

  • User Principle Name: Required. Username associated with the user's account. This is typically the user's email address.

  • Token Identifier: Optional. A unique identifier used to associate multiple OATH OTP tokens with the same user.

  • Secret Key (HEX): Required. An arbitrary key value in HEX format.

  • Account Name: Required. The name for the user's account.

  • Issuer: Optional, but strongly recommended. A string value specifying the associated provider or service for this account.

    The string must be URL-encoded according to RFC 3986

    If the issuer parameter is not provided, the issuer information may be pulled from the label's issuer prefix.

    For example, the valid value to the following label prefix example would be

    Copy 
    issuer=Example:
    otpauth://totp/Example:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=Exampl

    Older Google Authenticator implementations ignore the issuer parameter and rely on the issuer label prefix to disambiguate accounts. Newer implementations will use the issuer parameter for internal disambiguation, and the parameter will not be displayed to the user. We recommend you use both the issuer label prefix and the issuer parameter to safely support both the old and new Google Authenticator versions.

  • Algorithm: Optional. Algorithm used to process the information. Algorithm may have one of the following values:

    • SHA1 (Default)

    • SHA256

    • SHA512

      Currently, the algorithm parameter is ignored by Google Authenticator implementations.

  • OTP Digits: Optional. Determines the display time of the one-time passcode shown to the user. OTP digits may have the values 6 (default) or 8.

    Currently, for Android and Blackberry devices, the digits parameter is ignored by Google Authenticator.

  • Type: Required. Determines if the key will be used for counter-based HOTP or for TOTP. Valid type values are hotp and totp.

  • Period: Optional when the type value is totp. Defines the time (in seconds) that a TOTP code is valid. The default value is 30.

    Currently, the period parameter is ignored by Google Authenticator implementations.

  • Counter: Required when the type value is hotp. Sets the initial counter value.

Upload OATH Tokens

To bulk upload OATH tokens:

  1. Log in to Admin Portal.

  2. Navigate to Access > OATH Tokens.

  3. Click Bulk Token Import.

  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 a bulk import report will be 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.

    If you have not configured the OATH OTP policy, 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 Admin Portal. See How to Configure OATH OTP.