Skip to main content

Handling users who come back with a different UUID

  • Updated
 

There are a few scenarios where the same individual might return to your app with a different UUID:

  • The most common scenario is when a user no longer has access to any of their MFA methods. In that case, they won’t be able to sign in, and their only option currently is to delete their account and create a new one. When they create their new account, regardless of whether or not they use the same email address as before, they will be assigned a new unique UUID.
  • When a user with multiple IAL2-verified accounts attempts to access an IAL2 partner application, they will be blocked from authenticating, and will be forced to only keep one of those accounts and delete the others. If a user had previously signed into your app with one of those verified accounts that they now deleted, they will return to your app with a different UUID the next time they sign in.

Below are examples of potential solutions that partners could implement to allow users to relink their accounts on your end with their new Login.gov UUID. These are just examples. Ultimately, it’s up to you to determine how to link the new Login.gov account to the existing one on your end.

Example 1 for authentication-only applications that have some verifiable information about the user

  1. When the user signs in, if their UUID does not match an existing one on the partner side, check to see if the email matches. 
  2. If the email address matches, display a message to the user saying that their information is linked to a different Login.gov account and that it can only be linked to one Login.gov account at a time.
  3. Ask them if they want to relink their account on the partner app to the new Login.gov account, or if they want to keep using the previous Login.gov account
  4. If they choose to relink with the new Login.gov account, they will need to verify their identity by uploading documents or providing information that you have stored in your systems.
  5. Once the user is verified, their new Login.gov account can be linked, and the UUID will be updated to their new one.

Example 2 for authentication-only applications

  1. When the user signs in, if their UUID does not match an existing one on the partner side, check to see if the email matches. 
  2. If the email address matches, then send a randomly generated verification code to the user’s email address (to ensure they still have possession of that email address), and display a page where they can enter that code. 
  3. If the code matches, the user account can be linked again, and you will update your systems with the user’s new UUID.

Example 3 for applications that use Login.gov’s identity verification service

  1. When the user signs in, if their UUID does not match an existing one on the partner side, check to see if the one or more verified attributes match. 
  2. For example, if SSN, DOB, and phone are all the same as the previous UUID, then this gives you confidence that it is very likely the same user.
  3. Before linking the account, you might display a message to the user to ask them to confirm if they want to relink with their new Login.gov account.

In addition to the above guidance, you can be alerted when a user deletes their account by setting up an endpoint where you can receive various events in real time via our RISC API. In this case, you would look for the "Account Purged" event, which lets you know which UUID was deleted:

https://developers.login.gov/security-events/#account-purged

Here’s how you might use this:

  1. Let’s say you have an existing record of a user with UUID abcd-1234 and email test@example.com
  2. You receive an Account Purged event for UUID abcd-1234
  3. A user signs into your app with test@example.com and UUID xyza-5678
  4. Given that you have the email test@example.com in your systems and that you know that their previous UUID abcd-1234 no longer exists, you can be confident that the reason why this user is now coming back with the same email but a different UUID, is because they deleted their previous account.