Troubleshooting

The following sections address common questions or issues relating to DigitalPersona software, and how to troubleshoot and resolve them.

Configure the Ports used by DigitalPersona for Firewall

Issue

The DigitalPersona client console fails to open. This may be due to interrupted communication between the DigitalPersona Server and the client through the firewall due to dynamically assigned ports.

Resolution

DigitalPersona uses Microsoft’s DCOM for calls between our server and clients. By default, DCOM assigns ports dynamically from the TCP port range of 1024 through 65535. You can open all the specified ports, or you can configure the range by using Component Services.

Before following the steps below, you should familiarize yourself with the following topics:

• Using Distributed COM with Firewalls

• How to configure RPC dynamic port allocation to work with firewalls

To configure the range of ports used by DigitalPersona:

1. In the registry on each DigitalPersona Server, navigate to the following key.

   HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\Internet

2. Under the Internet key, add the values:

   • "Ports" (MULTI_SZ)

   • "PortsInternetAvailable" (REG_SZ)

   • "UseInternetPorts" (REG_SZ)

3. Set the value of Ports to the range that you want to open for DCOM communication.

4. Set PortsInternetAvailable to Y.

5. Set UseInternetPorts to Y.

   For example, the new registry key appears as follows:

   Ports: REG_MULTI_SZ: 5000-6000

   PortsInternetAvailable: REG_SZ: Y

   UseInternetPorts: REG_SZ: Y

6. Restart the server.

Troubleshoot a Fingerprint Reader Operation

Issue

An officially supported fingerprint reader is not working with a properly installed DigitalPersona client.

Resolution

Troubleshooting steps will vary depending on several factors, as outlined below.

Resolving Unavailable Server or Domain Issues

Issue

The following two errors may indicate that either DNS cannot resolve the _srv_dpproent records which the client is looking for to resolve and start the process, or the client is unable to contact the DigitalPersona LDS Server.

• There are currently no logon servers to process the request (0x8007501)

• An error occurred. We can't sign you in with this credential because your domain isn't available

Changing Password Manager Data Storage Limits

Issue

• For DigitalPersona version 2.1 and later - If you receive the following error message, Cannot save logon due to attribute size limitation. Contact your administrator, then the storage space allotted in Active Directory for storing Password Manager data may have been exceeded.

• For older versions - When it appears that logon data is not being saved (for instance, if changes are reverting to previously entered information), this may indicate that the Password Manager storage space allotment has been exceeded.

Resolution 1 - Clear dp-Password-Manager-Data rangeUpper value by script

Requirements

• PowerShell with Active Directory module installed on a domain controller

• User with Schema Master role assigned

Procedure

1. Copy 'dpPasswordManagerData_rangeUppe.ps1' to a local directory.

2. Sign the provided script, or temporarily allow running unsigned scripts using Set-ExecutionPolicy Unrestricted in the PowerShell console.

3. Right-click the file and select Run in PowerShell.

4. When prompted to confirm the action, enter Y.

5. You may run the script again to verify that the value was cleared, or check the value through ADSI Edit.

Resolution 2 - Change Password Manager Data values manually

Requirements

• User with Schema Master role assigned

• ADSI Edit (part of the Windows Server Support Tools)

Procedure

1. Make the following change on the domain controller where your DigitalPersona Server is installed.

2. Navigate to %Program Files%\Support Tools, and then double-click adsiedit.msc.

3. Expand the Schema, and then click CN=Schema,CN=Configuration,DC=domain_name,DC=com

4. In the Details pane, right-click CN=dp-Password-Manager-Data, and then click Properties.

5. Double-click rangeUpper.

6. Type a new appropriate upper range for the attribute. If a significant number of logons are being created or modified on a regular basis, you may want to consider doubling the current value.

7. Click OK.

8. Repeat steps 4 through 6 with dp-User-Private-Data.

9. Click OK again.

FIDO2 Token AppIDs

When a FIDO2 Key credential is enrolled through the User Console of the DigitalPersona Workstation, no FIDO2 Token AppID is saved on the DigitalPersona Server.

FIDO2 tokens register their keys (AppIDs) for a specific application, which is usually a URL. FIDO2 clients must verify that the AppID belongs to the requesting application ,and that the keys are issued for the claimed AppID, which is added to the set of the signed data the token creates.

However, it is possible that an application may be represented by a real app on an Android or iOS gadget, in which case the URL does not apply. Also, it may be possible that a Web app uses multiple URLs, or one Relying Part uses multiple apps on different systems, etc. All the above cases are supported by FIDO2 by using the concept of TrustedFacets.

The official description of Trusted Facets can be found here:

https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-appid-and-facets-v1.2-ps-20170411.html

In short, AppID can represent a URL from which a JSON – encoded list of trusted URL origins and Android/iOS applications (“FacetIDs”) can be downloaded and used by the client application to verify that the AppID is indeed trusted before passing AppID to the Fido2 Token.

There are quite strict rules as what can be placed in the list of the URLs in the “trustedFacets” which are documented in the link above.

For Android and iOS apps, the “FacetID” is basically constructed by obtaining the signature of the application package. This is out of scope for this documentation, but it seems it can be easily added when we have Android and iOS applications using the same AppID as the web applications.

For other OS’s (i.e. Windows) the document does not specify any scheme, but it mentions that something similar can be used.

Restrictions on the Web FacetIDs within TrustedFacets are the following:

• Only URLs with matching public DNS suffixes plus one extra label are trusted.

• A public DNS suffix can be received from the official list at https://publicsuffix.org/list/public_suffix_list.dat.

• For practical reasons, any subdomain of the company domain may be trusted if we host the AppID JSON file one level below the company domain, such as https://fido.mydomain.com/AppID or https://www.mydomain.com/fido/AppID.

• HTTPS is mandatory, the path beyond the server address is irrelevant.

The following are examples from the Trusted facets document mentioned above.

{
  "trustedFacets" : [{
    "version": { "major": 1, "minor" : 0 },
    "ids": [
       "https://register.example.com", // VALID, shares "example.com" label
       "https://fido.example.com",     // VALID, shares "example.com" label
       "http://www.example.com",       // DISCARD, scheme is not https:
       "http://www.example-test.com",  // DISCARD, "example-test.com" does not match
       "https://www.example.com:444"   // VALID, port is not significant
    ]
  }]
}

For this policy, "https://www.example.com" and "https://register.example.com" would have access to the keys registered for this AppID, and "https://user1.example.com" would not.

{
  "trustedFacets" : [{
    "version": { "major": 1, "minor" : 0 },
    "ids": [
        "https://register.example.com",              // DISCARD, does not share  "companyA.hosting.example.com" label
        "https://fido.companyA.hosting.example.com", // VALID, shares "companyA.hosting.example.com" label
        "https://xyz.companyA.hosting.example.com",  // VALID, shares "companyA.hosting.example.com" label
        "https://companyB.hosting.example.com"       // DISCARD, "companyB.hosting.example.com" does not match
     ]
  }]
}

For this policy, "https://fido.companyA.hosting.example.com" would have access to the keys registered for this AppID, and "https://register.example.com" and "https://companyB.hosting.example.com" would not as a public-suffix exists between these DNS names and the AppID's.

When Web Management Components are installed first or along with a DigitalPersona client

At the end of the Web Management Components Configuration Wizard, a file named app-id.json is created at a location similar to this: https://fido.company-domain-name.com/fido/app-id.json.

The URL is recorded in the DigitalPersona Server store under the name "FidoAppID", and this AppID is used by each web server and desktop client during FIDO2 enrollment and authentication.

The default content of this file is similar to the following, where company-domain-name.com will be replaced with the actual company domain name.

{
  "trustedFacets" : [{
    "version": { "major": 1, "minor" : 0 },
    "ids": [
        "https://sts.company-domain-name.com",
        "https://webenrollment.company-domain-name.com",
        "dpca:<?AD/LDS domain/installation guid?>"
    ]
  }]
}

HTTPS call to get the JSON file

When only a DigitalPersona desktop client is installed

If a DigitalPersona desktop client is installed without the Web Management Components, no FIDO2 Token AppID is saved in the DigitalPersona Server store and a default hard-coded AppID is used for all FIDO2 token enrollments. Re-enrollment will be needed if the DigitalPersona Web Management Components are later installed.

Manually adding an AppID value to the server store

You can add an AppID (URL of a future app-id.json file) in the DigitalPersona Server store, and it should work fine even if the actual file is not found at that URL.

1. Modify Web Management Components Configuration Wizard to do the following:

   1. Update the file "C:\Program Files\DigitalPersona\Web Management Components\DP Web SDK\app-id.json" with the list of configured host names.

      Copy

      Configuration sample - app-id.json in Advanced Configuration

      {
        "trustedFacets": [
          {
            "version": {
              "major": 1,
              "minor": 0
            },
            "ids": [
              "https://webenroll.virgo.com",
              "https://sts.virgo.com"
            ]
          }
        ]
      }

   2. Ensure in the Configuration Wizard that all URLs used for STS and HID DigitalPersona Enrollment share "public DNS suffixes plus one extra label."

   3. Add a FIDO2 application under the Default Web Site and point it to c:\Program Files\DigitalPersona\Web Management Components\DP Web SDK\app-id.json

      Note: The FIDO2 AppId will be <Web Management Components Host>\Fido\app-id.json - (that is, if the Web Components were installed on win-erepv5i4qub.ldsdemo.com) then AppId for both Basic and Advanced configuration will be https:\\win-erepv5i4qub.ldsdemo.com\Fido\app-id.json

   4. Store the FIDO2 AppId into the DigitalPersona server Web*Settings interface under name the name "U2F\AppId".

      You may pass null in the jwt parameter of WebSetSettingsEx if you want DPCA to use the Windows Interactive user token for authentication.

      Copy

      HRESULT WebSetSettingsEx(
          [in] BSTR JWT,            // Caller credentials
          [in] int Type,            // Settings type
          [in] BSTR Settings);    // List of settings to be set

   5. Store the FIDO2 AppId under the U2F\AppId name in the <appSettings> section of the following files:

      c:\Program Files\DigitalPersona\Web Management Components\DP STS\DPPassiveSTS\web.config

      c:\Program Files\DigitalPersona\Web Management Components\DP STS\DPActiveSTS\web.config

      c:\Program Files\DigitalPersona\Web Management Components\DP Web Enroll\DPEnrollment\Web.config

2. Modify the Enrollment page of the HID DigitalPersona Enrollment app to get the FIDO2 AppId from its U2F\AppId setting on the server.

3. Modify the Authentication page in the STS web server to get the FIDO2 AppId from the base64url encoded handshake data returned by the Continues authentication call.

4. Modify the Authentication page in Enrollment to get the FIDO2 AppId from the base64url encoded handshake data returned by Continues authentication call.

5. Modify the desktop FIDO authentication token to get the Fido2 AppID from the WebGetSettings interface and use it in enrollment and authentication.