Documentation
Introduction

The OATH Provisioning realm is utilized to enroll end-users' desktop and mobile devices for OATH OTPs; and mobile devices for Push Notifications for Multi-Factor Authentication.

OATH OTPs can be employed on the SecureAuth App for iOS and Android, the Blackberry and Windows OTP Mobile Apps (deprecated), Chrome Browser OTP Extension, and Windows and Mac Desktop Passcode Applications; Push Notifications can be employed on the SecureAuth Authenticate App for iOS and Android and the Blackberry and Windows OTP Mobile Apps only.

The OATH Provisioning realm enables OATH Seed or OATH Token provisioning. OATH Seed (Single) configurations generate a single OATH seed that is utilized by all devices for all realms; OATH Token (Multi) configurations generate an OATH Token that contains the unique OATH seed and the device ID for each individual enrollment. Using OATH Tokens, end-users can provision their devices against diverse SecureAuth IdP appliances and / or enterprise directories to create distinct tokens that ensure that the associated OATH seed can only work with that device.

Be sure to provision devices / browsers to the appropriately configured SecureAuth App Enrollment realm:

  • Chrome Browser SecureAuth OTP Extension only supports the OATH Seed (Single) configuration
  • Credential Provider (Windows 2-Factor Authentication login) only supports the OATH Seed (Single) configuration
  • Blackberry OTP Mobile App only supports the OATH Seed (Single) configuration (deprecated application)
  • Windows OTP Mobile App supports both Single and OATH Token (Multi) configurations (deprecated application)
  • SecureAuth App for iOS and Android supports both Single and OATH Token (Multi) configurations
  • Windows and Mac Desktop OTP Client Applications support both Single and OATH Token (Multi) configurations

Multiple SecureAuth App Enrollment realms can be created on a SecureAuth IdP appliance to make available the correct configuration for the application support requirements

Once an end-user has provisioned a mobile device against the OATH Provisioning realm, OATH OTPs and Push Notifications requests are available for use.

Prerequisites

1. Create a New Realm or access an existing realm that is configured for OATH Provisioning in the SecureAuth IdP Web Admin

2. Configure the following tabs in the Web Admin before configuring the specific steps for each of the realms:

  • Overview – the description of the realm and SMTP connections must be defined
  • Data – an enterprise directory must be integrated with SecureAuth IdP
  • Workflow – the way in which users will access the target must be defined
  • Registration Methods – additional 2-Factor Authentication methods that will be used to access the target (if any) must be defined
OATH Provisioning Realm Configuration Steps
Data

The following Data tab steps are for LDAP directories only

If using a different directory (SQL, ASPNET, Oracle etc.), then the Properties need to be mapped to the data store via stored procedures (step 2)

 

1. In the Membership Connection Settings section, note the Search Attribute directory field, e.g. sAMAccountName

The Search Attribute directory field must be the same in the OATH Provisioning realm and all realms utilizing OATH OTPs for Multi-Factor Authentication

Profile Fields

2. Map the necessary Properties to data store fields and check Writable:

The OATH Seed Property is required if OATH Seed (Single) is selected in the Multi-Factor App Enrollment section in the Post Authentication tab (step 6a below); otherwise, no mapping is necessary

Map the OATH Seed Property to a directory field that fulfills the following requirements:

    • Directory String (syntax: 2.5.5.12)
    • Upper Range of at least 4096
    • Supports Advanced Encryption, as selected from the Data Format options

For Active Directory data stores, the postalAddress field can be used

The One Time OATH List Property is required to enable the use of the feature; otherwise no mapping is necessary

The One Time OATH List feature temporarily stores a Time-based Passcode in the directory until the configured expiration to ensure that the OTP is used only once throughout its validity

Map the One Time OATH List Property to any directory field that is a Directory String

For Active Directory data stores, the wWWHomePage field (among many others) can be used

The OATH Tokens Property is required if OATH Token (Multi) is selected in the Multi-Factor App Enrollment section in the Post Authentication tab (step 6b below); otherwise, no mapping is necessary

The OATH Tokens Property can be stored as Plain Binary, JSON, or JSON Encrypted format, and has distinct requirements for the LDAP directory attribute mapped to the Property based on the Data Format selection

For Plain Binary, map the OATH Tokens Property to a directory field that fulfills the following requirements:

      • Octet String (syntax: 2.5.5.10)
      • Multi-valued
      • Upper Range of at least 4096

For JSON or JSON Encrypted, map the OATH Tokens Property to a directory field that fulfills the following requirements:

      • DirectoryString (syntax: 2.5.5.12)
      • Multi-valued
      • Upper Range of at least 4096

For typical Active Directory integrations, the Data Format is Plain Binary and the registeredAddress field is used

The Push Notification Tokens Property is required to enable the use of Push Notifications; otherwise, no mapping is necessary

The Push Notification Tokens Property can be stored as Plain Binary or in JSON format, and has distinct requirements for the LDAP directory attribute mapped to the Property based on the Data Format selection

For Plain Binary, these requirements must be met for the directory field that contains the Push Notification Token:

        • Length: 4096 minimum
        • Data Type: Octet string (bytes)
        • Multi-valued

For JSON, these requirements must be met for the directory field that contains the Push Notification Token:

        • Length: 4096 minimum
        • Data Type: DirectoryString
        • Multi-valued

For typical Active Directory integrations, the Data Format is Plain Binary and the jpegPhoto field is used

NOTE: For SQL, ASP.net, and Oracle data stores, only the Plain Binary Data Format is supported for the OATH Tokens and Push Notification Tokens Properties (configured in the Data tab); and for ODBC data stores, the two Properties are not supported

Refer to LDAP Attributes / SecureAuth IdP Profile Properties Data Mapping for the full list of requirements

Click Save once the configurations have been completed and before leaving the Data page to avoid losing changes

Post Authentication

 

3. In the Post Authentication section, select OATH Provisioning from the Authenticated User Redirect dropdown

4. An unalterable URL is auto-populated in the Redirect To field, which appends to the domain name and realm number in the address bar (Authorized/OATHProvision.aspx)

User ID Mapping

 

5. Select Authenticated User ID from the User ID Mapping dropdown (default)

OATH

6a. Select OATH Seed (Single) from the Provision dropdown to provision user devices to utilize a single seed across multiple devices to generate the OATH OTPs

For the Chrome Browser OTP Extension and for the Credential Provider, this is the only provisioning option available

7a. Select the amount of digits of which the OTP is composed from the OATH Length dropdown

8a. Set the OATH Interval to the amount of seconds during which an OATH OTP is valid

9a. Select False from the Show OATH Seed dropdown, unless it is required

10a. Select True - Generate new seed from the One Time Provisioning to restrict the use of OATH OTPs on one device at a time (each newly provisioned device will have a new seed that disables the use of the old seed); or select False - Reuse same seed to enable the use of multiple devices (each newly provisioned device will reuse the same seed)

11a. In the Desktop / Mobile App section, select True from the Require OATH PIN if a PIN code is required to unlock the app; select False if it is not required

12a. Set the number of attempts allowed before the provisioned data is deleted from the application in the Wipe Provisioned Data after field

13a. Set the number of seconds allowed for the application to remain idle before requiring the PIN in the Show PIN screen after field

6b. Select OATH Token (Multi) from the Provision dropdown to provision user mobile devices to utilize multiple tokens (that each contain a distinct OATH seed) on a single device

7b. Select the amount of digits the OTP will be from the OATH Length dropdown

8b. Set the OATH Interval to the amount of seconds during which an OATH OTP is valid

9b. Select False from the Show OATH Seed dropdown, unless it is required

10b. Select False from the Wipe OATH Seed dropdown to enable the continued use of already-provisioned devices (pre-SecureAuth IdP v8.1); or select True to delete the existing OATH seed and to enable only the use of OATH Tokens

11b. Set the maximum amount of devices (tokens) allowed per user account in the Number of devices allowed field

Set to -1 if there is no max amount

12b. Select Allow to replace from the When exceeding number of devices dropdown if users can replace existing provisioned devices with new ones after the maximum is met

13b. Select Created Time from the Replace in order by dropdown to replace the oldest OATH Token with the new one; or select Last Access Time to replace the least frequently used OATH Token with the new one

14b. In the Desktop / Mobile App section, select True from the Require OATH PIN dropdown if a PIN code is required to unlock the app; select False if it is not required

15b. Set the number of attempts allowed before the provisioned data is deleted from the application in the Wipe Provisioned Data after field

16b. Set the number of seconds allowed for the application to remain idle before requiring the PIN in the Show PIN screen after field

Click Save once the configurations have been completed and before leaving the Post Authentication page to avoid losing changes

Forms Auth / SSO Token

 

17. Click View and Configure Forms Auth Keys / SSO Token to configure this realm's token / cookie properties

These are optional configurations

 To configure this realm's token / cookie settings, follow these steps:
Forms Authentication

 

1. If SSL is required to view the token, then select True from the Require SSL dropdown

2. Choose whether SecureAuth IdP will deliver the token in a cookie to the user's browser or device:

  • UseCookies enables SecureAuth IdP to always deliver a cookie
  • UseUri disables SecureAuth IdP to deliver a cookie, and instead deliver the token in a query string
  • AutoDetect enables SecureAuth IdP to deliver a cookie if the user's settings allow it
  • UseDeviceProfile enables SecureAuth IdP to deliver a cookie if the browser's settings allow it, no matter the user's settings

3. Set the Sliding Expiration to True if the cookie remains valid as long as the user is interacting with the page

4. Set the Timeout length to determine for how many minutes a cookie is valid

No configuration is required for the Name, Login URL, or Domain fields

Machine Key

 

5. No changes are required in the Validation field, unless the default value does not match the company's requirement

If a different value is required, then select it from the dropdown

6. No changes are required in the Decryption field, unless the default value does not match the company's requirement

If a different value is required, then select it from the dropdown

No configuration is required for the Validation Key or Decryption Key fields

Authentication Cookies

 

7. Enable the cookie to be Persistent by selecting True - Expires after Timeout from the dropdown

Selecting False - Session Cookie enables the cookie to be valid as long as the session is open, and will expire once the browser is closed or the session expires

No configuration is required for the Pre-Auth CookiePost-Auth Cookie, or the Clean Up Pre-Auth Cookie fields

Click Save once the configurations are completed and before leaving the Forms Auth / SSO Token page to avoid losing changes

  • No labels