Best practices

To efficiently and effectively integrate with ID.me it is recommended to use one of the Web Access Management Software Configurations listed above in the Resources section of this document. These configurations simplify the process of generating SP metadata and ingesting IdP metadata, whereas custom SAML implementations require you to manually apply the details above during integration planning and design.

Matching

When matching attributes in the ID.me payload to user data on your side, do not rely on a single attribute. Best practice would be to match multiple attributes such as SSN/ITIN, DOB and Last Name. Matching on SSN/ITIN as the first attribute to establish uniqueness, followed by Date of Birth, Last Name, and so on will increase assurance of uniqueness. With Last Name, issues can arise for hyphenated names or legal name changes. If First Name is leveraged, consideration should be taken to allow variations such as Thomas/Tom through the use of fuzzy logic.

Upon subsequent logins from a user, the UUID from ID.me should be incorporated into the logic. Additionally, some attributes may have been updated. For example, last names may change due to marriage status or legal name changes.

Storing user attributes

Storing key attributes about the user is vital to a seamless digital identity verification experience.

It is recommended to store the returned attributes in a separate table within your database with some relation to the user record. Remember, the ID.me provided UUID will remain constant for the life of that user’s ID.me account.

When extracting User attributes from JSON it is recommended that the handle_name be used to read the attributes. Relying on attribute order is susceptible to errors and issues as the platform and policies evolve.

Using user attributes

It is recommended that the user attributes be used to pre-fill information into any additional forms requested in the workflow in the same session to improve UX.

Consider locking fields that are pre-filled with attribute data, where appropriate. For example, First Name, Last Name and Social Security Number be locked. A “Preferred Name” field can be leveraged to allow for nicknames.

Care should be taken to handle unexpected payload changes such as the addition or removal of an attribute, change in attribute ordering, or an attribute containing an unexpected special character.

Exception handling

If the user denies the access request, or if the request is invalid, the client will be informed using the parameters in the following table, appended to the AssertionConsumerService: