Documentation

Refer to Multi-Factor App Enrollment (URL) Realm Configuration Guide to enroll devices via URL login workflow

Introduction

Use this guide to configure an app enrollment realm that utilizes a QR Code workflow to provision users' mobile devices via the SecureAuth Authenticate App, which can then generate Time-based Passcodes (OATH TOTP), Push Notification One-time Passcodes (OTPs), and Push-to-Accept login requests.

The QR Code workflow can also be used to provision the Google Authenticator app to generate OTPs (no Push or Push-to-Accept)

NOTE: Google Authenticator is the only third-party app tested and officially supported by SecureAuth – only 6 digits and 30 second intervals are supported

Previously, SecureAuth required users to undergo a typical login workflow where they supply all of the necessary information to provision their devices. This method can still be employed (refer to Multi-Factor App Enrollment (URL) Realm Configuration Guide), but now users can also log into the provisioning realm via browser on any device (desktop, laptop, mobile, etc.) to generate a specific QR code that is then scanned to enroll the mobile device / app to use for Multi-Factor Authentication.

NOTE: SecureAuth IdP version 9.0.0 supports only OATH Token (Multi) enrollment option; however, SecureAuth IdP versions 9.0.1+ support both OATH Token (Multi) and OATH Seed (Single) enrollment options

Select the appropriate version in the SecureAuth IdP Configuration Steps section to ensure the correct configuration

Refer to the SecureAuth Authenticate App for Android and iOS for QR Code enrollment instructions

Prerequisites

1. Create a New Realm for the Multi-Factor App Enrollment (QR Code) page in the SecureAuth IdP Web Admin

Note that the SecureAuth998 realm is defaulted to the Multi-Factor App Enrollment (URL) configuration, and therefore can be modified to enable QR code provisioning; or the QR code provisioning configuration can be completed in a different, new realm, making available both provisioning options to users

2. Download the SecureAuth Authenticate on the mobile device to enroll

This app is currently available to Android and iOS mobile devices only, and the QR Code workflow requires a working camera on the device

3. Configure the following tabs in the Web Admin before configuring the Post Authentication tab:

  • 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 / Multi-Factor Methods – the Multi-Factor Authentication methods that will be used to access the target (if any) must be defined
SecureAuth IdP 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

The Search Attribute directory field must be the same in the Multi-Factor App Enrollment realm and all realms utilizing Time-based Passcodes for Multi-Factor Authentication

Profile Fields

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

The OATH Tokens Property is required for the QR code provisioning method

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:

      • OctetString (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 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 DirectoryString

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

The Push Notification Tokens Property is required to enable the use of Push Notifications or Push-to-Accept requests; 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: If the DirectoryString Data Type is not present, UnicodeString can be used instead, as long as other requirements for the attribute are met

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 Multi-Factor App Enrollment - QR Code 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/qrCodeProvision.aspx)

Multi-Factor App Enrollment

5. Under OATH Options, set the Max Device Count to the number of accounts / OATH Tokens that are allowed per user profile

Set to -1 if there is no limit

6. Select Replace from the When exceeding max count dropdown to enable the replacement of accounts / OATH Tokens when the Max Device Count value is reached; or select Don't replace if manual removal of accounts is required

This setting applies only if a maximum is set in step 5

7. Select Created Time from the Replace in order by dropdown to replace the oldest account / OATH Token with the newest one; or select Last Access Time to replace the least frequently used account / OATH Token with the newest one

This setting applies only if Replace is selected in step 6

8. Select the number of digits that comprise the Time-based Passcodes (6 or 8) from the Passcode Length dropdown

9. Set the Passcode Change Interval to the number of seconds during which the Time-based Passcode is valid

10. Select Yes from the Show Third Party App Support dropdown to display the Google Authenticator download link and the unique alphanumeric code that is required to provision the application on the client-side enrollment page

NOTE: This field is purely to display the information, and not to enable compatibility

Google Authenticator can be enrolled via the QR Code workflow and can be used to generate one-time passcodes for Multi-Factor Authentication based on the design architecture of Google Authenticator, and is not dependent on the selection made in this step

11. Under SecureAuth App - Security Options, select True from the Require OATH PIN to require users to provide a 4-digit PIN or biometric ID (fingerprint) to unlock the SecureAuth App; or select False if a PIN is not required

12. Select the number of failed attempts allowed before the application data is removed and re-enrollment is required from the Wipe Provisioned Data after dropdown

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

This setting applies only if True is selected in step 11 (PIN required)

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

Forms Auth / SSO Token

 

14. 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 delivers 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, 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, 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

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

The Search Attribute directory field must be the same in the Multi-Factor App Enrollment realm and all realms utilizing Time-based Passcodes 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:

    • DirectoryString (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 DirectoryString

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 5b 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:

      • OctetString (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 or Push-to-Accept requests; 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: If the DirectoryString Data Type is not present, UnicodeString can be used instead, as long as other requirements for the attribute are met

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 Multi-Factor App Enrollment - QR Code 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/qrCodeProvision.aspx)

Multi-Factor App Enrollment

5a. Under OATH Options, select OATH Seed (Single) from the OATH Seed or Token dropdown to provision user devices to utilize a single seed across multiple devices to generate the Time-based Passcodes / Push Notifications

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

7a. Select False from the Show OTP on enrollment page dropdown, unless the visibility of this information is required

8a. Select the number of digits that comprise the Time-based Passcodes (6 or 8) from the Passcode Length dropdown

9a. Set the Passcode Change Interval to the number of seconds during which the Time-based Passcode is valid

10a. Under SecureAuth App - Security Options, select True from the Require OATH PIN to require users to provide a 4-digit PIN or biometric ID (fingerprint) to unlock the SecureAuth App; or select False if a PIN is not required

11a. Select the number of failed attempts allowed before the application data is removed and re-enrollment is required from the Wipe Provisioned Data after dropdown

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

This setting applies only if True is selected in step 10 (PIN required)

(no steps 13 - 14)

5b. Under OATH Options, select OATH Token (Multi) from the OATH Seed or Token dropdown to provision user devices to utilize multiple tokens (that each contain a distinct OATH seed) on a single device

6b. 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 the OATH seed and to enable only the use of an OATH Token

7b. Set the Max Device Count to the number of accounts / OATH Tokens that are allowed per user profile

Set to -1 if there is no limit

8b. Select Replace from the When exceeding max count dropdown to enable the replacement of accounts / OATH Tokens when the Max Device Count value is reached; or select Don't replace if manual removal of accounts is required

This setting applies only if a maximum is set in step 7

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

This setting applies only if Replace is selected in step 8

10b. Select the number of digits that comprise the Time-based Passcodes (6 or 8) from the Passcode Length dropdown

11b. Set the Passcode Change Interval to the number of seconds during which the Time-based Passcode is valid

12b. Under SecureAuth App - Security Options, select True from the Require OATH PIN to require users to provide a 4-digit PIN or biometric ID (fingerprint) to unlock the SecureAuth App; or select False if a PIN is not required

13b. Select the number of failed attempts allowed before the application data is removed and re-enrollment is required from the Wipe Provisioned Data after dropdown

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

This setting applies only if True is selected in step 12 (PIN required)

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

Forms Auth / SSO Token

 

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

These are optional configurations

To change the length of time a QR code is available for scanning by a user

1. Go to the System Info tab, and in the Links section, Click to edit Web Config file.

2. On the Web Config Editor page, add an entry in the web.config file to specify the new value (default is 10 minutes). For example: 

    <add key="QRDeviceEnrollmentValidityThreshold" value="10" />

NOTE: We recommend to set this to the same value as the session timeout.

3. Save settings.