Auth0: User profile enrichment with the Pipl API
Pipl is an information services company with the world’s largest people search engine. Its proprietary identity resolution technology connects publicly available online and offline information from millions of sources. You can leverage its API within Auth0, the Auth0 Rules engine in particular, to enrich user profiles. This can be especially valuable for consumer-oriented e-commerce websites or marketing departments.
Based on just an email address, name, phone number or nickname, you can fetch additional information such as:
- age
- DOB
- gender
- address(es)
- employers / jobs (history)
- phones (both mobile & landlines)
- nicknames / social media handles
- education
- and more
Data Privacy
Before looking into the technical how-to, keep in mind that data privacy matters and depending on where you’re based, you need to inform the user accordingly about what kind of information you’re processing and/or storing about him.
There are a few things to consider:
You’re passing PII (Personally Identifiablly Information) to a US-based service (whatever data point you use to make the lookup). This might be an issue if you’re in the EU (GDPR).
You need to think about whether you want to store the received data on your end, or just process it in order to, for example, calculate a certain derived value (think: credit score, customer rating, etc.).
So, whatever you do with such user data, and even though they are publicly available (therefore the “open source” in the term OSINT) somewhere across the internet, be mindful with it.
Pipl’s EU Privacy Shield Notice can be found here.
Instructions
(1)
Create an account on pipl.com. You will get a 7 days demo that allows for 30 demo queries; enough to play around with it and see its value.
In your Pipl API Dashboard, you will see 3 different API keys, “Business”, “Social” and “Contact”. We will use “Business” in our example, as it returns the most information.
(2)
In the Auth0 Dashboard, navigate to the “Rules” section. At the bottom of the page, add they key/value pairs for the Pipl API keys. I named them:
- PIPL_BUSINESS_KEY
- PIPL_SOCIAL_KEY
- PIPL_CONTACT_KEY
in order to be able to easily switch between them in my rule script.
Next, create a new rule by clicking the “+ Create Rule” button in the upper right corner.
(3)
Select the “Empty Rule” as a template.
(4)
Give the rule a name, for example “Enrich profile with Pipl” and replace the rule content with the following code. Here is also a Github gist of the same.
The rule makes a profile enrichment request against the Pipl API and passes the user’s email address as a minimum, and optionally first and last name if it’s available (which is usually the case when using federated social logins via Google or Facebook).
The more data we can provide to the Pipl API, the more accurate the results will be.
function (user, context, callback) {
const PIPL_KEY = configuration.PIPL_BUSINESS_KEY;
// change to PIPL_SOCIAL_KEY or PIPL_CONTACT_KEY as needed
// skip if Pipl metadata is already there
if (user.app_metadata && user.app_metadata.pipl) {
context.idToken['https://any-custom-namespace/pipl'] = user.app_metadata.pipl;
return callback(null, user, context);
}
var queryStrings = {
key: PIPL_KEY
};
// add email to query as a minimum
if (user.email) {
queryStrings.email = user.email;
}
// in case of passwordless authentication via SMS
if (user.phone_number) {
queryStrings.phone = user.phone_number;
}
// add name to query if available in user profile
if (user.given_name && user.family_name) {
queryStrings.first_name = user.given_name;
queryStrings.last_name = user.family_name;
}
request.get('https://api.pipl.com/search/', {
qs: queryStrings,
json: true
}, (error, response, body) => {
if (error || (response && response.statusCode !== 200)) {
// swallow Pipl api errors and just continue login
return callback(null, user, context);
}
// if we reach here, it means Pipl returned info and we'll add it to the metadata
user.app_metadata = user.app_metadata || {};
user.app_metadata.pipl = body;
auth0.users.updateAppMetadata(user.user_id, user.app_metadata);
context.idToken['https://any-custom-namespace/pipl'] = user.app_metadata.pipl;
return callback(null, user, context);
});
}
(5)
Save and enable the rule.
Result
Let’s try and authenticate in any of your Auth0 client applications, i.e. with a federated social identity provider such as Google.
The Rule in Auth0 will check if the respective user profile has already been enriched before or not, and if not, call the Pipl API accordingly.
The enrichment data is then stored in the user profile within Auth0 as well as returned as custom claim within the ID token returned to the client application.
Here you can see a typical Auth0 Quickstart application with the Pipl information as custom claim in an ID token:
Note: in my example and for demonstration purposes, I am returning the full Pipl information of this user back to the client, but you might want to limit that to certain aspects of the data that your client application is interested in.
Here you can see the Auth0 Dashboard with the Pipl enrichment information stored as app_metadata in the user profile in Auth.
When enriching my own profile, Pipl found quite a lot of information about me, even dating back a few years. The result actually contains a summary of what was found:
"available_data": {
"premium": {
"relationships": 29,
"usernames": 6,
"jobs": 40,
"addresses": 19,
"phones": 10,
"mobile_phones": 4,
"landline_phones": 6,
"educations": 5,
"languages": 7,
"user_ids": 13,
"social_profiles": 15,
"names": 11,
"dobs": 2,
"images": 14,
"genders": 7
}
},Conclusion
With a few lines of code in an Auth0 Rule and an API call to Pipl, you can gather valuable information about a user that came to your service with just an email address (or maybe just a phone number via Passwordless authentication with SMS). It shows the power and easiness of both the Auth0 platform as well as Pipl API.
