At its core, this is an authorization issue, and Login.gov recommends the following ways in which partners can identify the user accessing their systems:
Best Option: UUID
Whenever possible, we recommend identifying users based on their unique Login.gov UUID. Given that users can change the email address(es) associated with their Login.gov account, as long as the UUID hasn’t changed, you know it’s the same Login.gov account.
The very first time a user accesses your service via Login.gov, in order to link their Login.gov account with a pre-existing account on your end, it makes sense to ask the user to sign in with the same email address that you have on record.
Once that link has been established, we recommend storing the unique UUID for that user that we pass along to you, and the next time they sign in, you would look them up based on their UUID, which lets you avoid the email-related issues discussed in the options below.
This option works best when the user can only have one account at a time in your system.
Option 2: For single applications that expect the user to sign in with the same email address each time
This option is recommended for applications that must rely on the user’s email address to grant access, and cannot rely on the UUID only.
In this case, all your app needs to check is if the expected email is returned in the Login.gov response. It doesn't matter which email they actually signed in with. If the expected email is returned in the response, that means that email is still associated with that user's Login.gov account.
There are two ways you can verify that the expected email is returned in the response:
- Request the all_emails attribute, which will return all the emails associated with the user's Login.gov account, and you can then check if the email that your app expects is included in the list of all_emails. This assumes you are able to consume the all_emails attribute and make access decisions based on it.
- If you are not able to take advantage of the all_emails attribute, then you should make sure to only request the singular email attribute, which will allow users to set their preferred email for your app, as explained below.
Login.gov allows users who have multiple email addresses associated with their account to set a preferred email address for a particular Service Provider, as described in this Help Center article in the section labeled “How do I choose which email gets shared with a partner agency I connected with?”
When this feature is turned on, and the user has set a preferred email address, regardless of the email address the user last signed in with (by entering it along with their Login.gov password on the sign-in screen), the singular email attribute that we share with your app will always be their preferred email address.
In order for a user to be able to set a preferred email address for your app, you must not request the all_emails attribute. If you request the all_emails attribute, the preferred email address feature gets disabled, and the singular email attribute will then always be the last email the user signed in with, which might not necessarily be the one your app expects.
Option 3: For single applications that allow the user to have multiple accounts or roles at a time on the agency side, each with a different email address
Note that the multiple accounts referred to here are the accounts within the agency’s systems, not multiple Login.gov accounts.
In this scenario, for the best user experience, we highly recommend disabling the preferred email address feature by requesting the all_emails attribute, even if you can’t make use of it. (Read Option 2 for an explanation of the Login.gov preferred email address feature.)
By requesting all_emails, it will disable the preferred email address feature, and will allow users to sign in with the specific email they need, and allow them to access the corresponding account on your end.
Otherwise, if you don’t request all_emails, the user might set a preferred email address by mistake, or without understanding the implications, which will lead to confusion. In other words, if they set Email A as their preferred email address for your application, even if they sign in with Email B, Email A is the one that will always be shared with the partner application, which will cause the user to access the wrong account on your end.
Option 4: For broker integrations linked to multiple applications that might expect different email addresses for the same user
If the entity that is integrated with Login.gov is a broker app/portal through which the user can access multiple different applications, then it's possible different applications might require a different email address for the same user. For example, one app might require the user's personal email, while another app might require their work email.
In that case, the user should not be able to set a preferred email because otherwise, they would have to change the preferred email each time they need to sign in with a different email.
Therefore, for broker integrations, we highly recommend requesting the all_emails attribute to disable the preferred email feature. We also recommend instructing your users to sign in with the expected email address so that the correct email address can be passed from the broker to the end user application via the singular email attribute.
When they sign in, they should do so by entering the expected email address and their Login.gov password. They should not sign in directly with their PIV to avoid having the "wrong" email being shared in the email attribute. When signing in directly with a PIV, the singular email attribute will contain the last email the user signed in with via entering their email and password on the sign in screen, which might not be the “correct” email address.