The user profile
Most interactions with GuestHouse services are done through the mobile phone. As such, the primary identifier for user credentials is the phone number.
Before the user profile is created, their phone number is verified using tru.ID SubscriberCheck.
GuestHouse will optionally capture the user email for marketing and account recovery capabilities, but also for handling authentication failover, when mobile number authentication is not available.
The authentication flow
In this example, we illustrate the case where verification of the phone number leads to an authenticated user. As mentioned previously, the user starts the authentication experience by scanning a QR code with their phone, when arriving at the property.
This takes the user to a sign-in page where it will ask them to present their phone number. Since GuestHouse uses the phone number as the primary identifier for user credentials, the system will try to verify the phone number with tru.ID SubscriberCheck.
Once the verification is complete, the system will:
- check if the result is a match — meaning the user is in possession of the provided number
- check if the SIM associated with the number has not changed in the last 7 days
For an existing user, this means they will be authenticated if both those previous assertions are true.
The edge cases
Handling mobile coverage
tru.ID provides a global service over many different geographies. However, GuestHouse wants to be able to authenticate their users when one of the following scenarios occur:
- tru.ID does not support the user’s mobile provider yet
- the user is trying to access the service without having mobile data (turned off, out of allowance etc.)
GuestHouse uses tru.ID Coverage API to understand if the potential user is using mobile data (thus not on a WiFi connection), or if the input phone number is not covered by tru.ID.
In case one of the previous assertions is true, the system can fail-over the authentication step, by relying on the user’s email address. GuestHouse has chosen to send an email to the user with magic link, which will log them in once the user clicks on it.
SIM swap prevention
When GuestHouse users change their phones, they might often get a new SIM card. While the phone number stays the same, the actual SIM card will be different.
The user might change mobile providers altogether, and the existing number gets allocated to someone else (and again, the SIM card will be different).
When a user’s SIM card resolves to an expected phone number, but the SIM appears to have been newly generated, it is not possible to identity who is in possession of the SIM. This could be an indicator of attempted SIM swap fraud. For this, one must either:
- Assess if this is a low level-of-assurance scenario where access may be granted regardless (for instance read-only authorisation is requested by a client),
- For high level-of-assurance scenarios, either:
- Use an alternate form of identity for verification
- Prompt the user for additional challenges, for instance presenting knowledge factors by calling up customer support.
tru.ID SIMCheck API provides information on when a SIM card associated with a mobile phone
number has last changed. By default, the SIMCheck API tells you if the SIM has changed in the last 7 days — but you can control the time period relevant to your business (e.g. last 14, 30, or 90 days).
To check if the SIM of a given phone number has changed, you could:
- perform and validate the SIMCheck result,
- store the date of this check,
- repeat it every `date of the last check + ~7 days`
In order to prevent the scenario where someone signs in with the wrong user profile, GuestHouse keeps track of the last SIM change date by using a combination of:
- active checks as part of the authentication flow using the tru.ID SubscriberCheck
- silent background checks using tru.ID SIMCheck API, triggered periodically within 7 days since the last active check
The idea is to keep an updated rolling window of the last SIM change date associated with a user profile.
If that date changes, GuestHouse considers the existing profile inactive. Any subsequent authentication attempts using that phone number will be considered a completely new user.
The old profile might not be completely lost. Provided an email is present, GuestHouse could email the user, notifying them of the profile inactivation and how they could get their profile back.
We hope this blog post has helped you understand how to use tru.ID in your authentication flows — and how to handle some common edge cases you might encounter while doing so.
You can find the GuestHouse example application in this GitHub repository.