Overview

Migrate from your legacy password hashes to SAP Customer Data Cloud.

A huge part of ensuring a smooth transition from your legacy system to SAP Customer Data Cloud is making sure that your users will be able to login seamlessly with their existing credentials after go live. This article aims to walk you through everything you need to know to be able to migrate your legacy hashes into SAP Customer Data Cloud solutions.

This article is part of a wider series on SAP Customer Data Cloud migrations. See  Migrating to SAP Customer Data Cloud  for the full list.

Table of Contents

Understanding How SAP Customer Data Cloud Stores Users' Legacy Passwords and Hash Information

The first thing to understand is that the hashing algorithm information is not stored at the repository level or as some kind of global setting, but rather it is stored at the user level alongside the hashed password.

What this means is that you have no theoretical limits in how many different hashing algorithms are being migrated into the same user repository, which really comes in handy when you have a multi-source data migration with systems using all kinds of different hashing algorithms.

Let's take a look at the password object in one of its simplest form;

{
   "hashedPassword":"Ftek/KdELdo62TyacmWX5A==",
   "hashSettings":{
      "algorithm":"md5"
   }
}

We simply have the hashed version of the clear text password, and within the hash settings we specify which algorithm is being used to generate that hash. In this case a simple md5 hash of "test1234".

Out of the box, SAP Customer Data Platform supports the following hashes; "md5", "sha1", "sha1_hashbytes", "sha256", "sha512", "sha512Hexa", "md5_double_salted", "md5_crypt", "bcrypt", "pbkdf2", "pbkdf2_sha256", "drupal" and "symphony2", allowing for multiple variations based on number of hashing rounds, salt and salt placement, the details of which are documented for the "password" parameter of the accounts.importFullAccount API

Now it could happen that your hashing algorithm is very custom, maybe a combination of multiple hashes, or some other format which cannot be clearly configured using our out of the box parameters. In this case, SAP Customer Data Cloud has the ability to defer the hashing to an external endpoint under your control. In this case, the password object will look something like this (here with a base64 encoded salt and a specified number of hashing rounds)

{
   "hashedPassword":"Ftek/KdELdo62TyacmWX5A==",
   "hashSettings":{
      "algorithm":"custom",
      "url":"https://my-custom-hashing-endpoint.com"
      "salt": "WFhYWFg="
      "rounds": 50
   }
}

Here you are telling SAP Customer Data Cloud that the algorithm is a custom one, and indicating the URL of the service to be used to receive the hashed version of the password during the login process.

First Login and Re-Hash Process

Speaking of login process, it is important to note that SAP Customer Data Cloud only needs your legacy hashing algorithm once; during the migrated user's first login, once the hash has been validated, SAP Customer Data Cloud immediately re-hashes the password using its algorithm of the day (pbkdf2 with specific hashing round settings).

The 2 sequence diagrams below detail step by step what happens during this first login, both in the case of supported and custom hashes.

Supported Hashes

Custom Hashes

Creating a Custom Hashing Endpoint

Creating an external custom hashing endpoint is a fairly straight forward process, most customer who need to do so typically opt to create an AWS Lambda or Azure function, and effectively the process is as detailed in the sequence diagram above;

• The first time a user logs in, SAP Customer Data Cloud will call the custom hashing endpoint via a GET request with the clear text password (and the salt associated with the account and hashing rounds if applicable):

ex: https://my-custom-endpoint.com/?password=test1234&pwHashSalt=WFhYWFg&pwHashRounds=50

• The hashing endpoint will hash the clear text password (with the salt if applicable) using your custom logic and return it to SAP Customer Data Cloud.
• SAP Customer Data Cloud will then compare the hash returned from the endpoint against the one stored in the user account.
  
  • If they differ, the authentication has failed and the user is denied login.
  • If they match, the authentication process has succeeded and the user is logged in. Additionally, SAP Customer Data Cloud will hash the clear text password with the  pbkdf2_sha256 algorithm and store it in the user's account, so that on subsequent logins, the password submitted by the user will only be compared to the one stored in the SAP Customer Data Cloud account.

This pseudo code can be used as a template;

module.exports.hashing = (req, res) => {
    const {password, pwHashSalt, pwHashRounds} = req.body.query;
    const hashed = custom_hashing_logic(password, pwHashSalt, pwHashRounds);
    res.send({hashedPassword: Buffer.from(hashed, 'base64')});
}

Password Hashing Algorithm Validation Process

Now that you're sure you fully master the format of the password object, and you've put in place a custom hashing endpoint if needed, the time has come to validate that everything works as expected.

The simplest and fastest way to validate that SAP Customer Data Cloud supports your password hashing algorithm is to import a few test users for whom you have both the hashed password and it's clear text equivalent, then attempt a login with them. Typically testing successfully around 5 distinct passwords gives a good enough degree of confidence that the login will work for users.

For convenience sake, we've attached this Postman Collection to this article containing all of the API calls you'll need to make this validation.

This collection should allow you to quickly test whether your legacy database hashed password will work once imported into SAP Customer Data Cloud.

You have a few variables you'll need to set in this collection in order for the calls to work;

• "DC" - Data Center. This can be either one of the following values depending on which data center your API Key is hosted:

• apiKey - Your SAP Customer Data Cloud API Key which can be found in the SAP Customer Data Cloud Console.
• applicationKey & applicationSecret - The credentials used for API calls. We're using a secret for simplicity sake rather than the best practice asymmetric key. More info on getting your application credentials here.

The API calls used are:

Conclusion

Congratulations, you've successfully migrated passwords from your legacy system to SAP Customer Data Cloud. It is a psychological milestone not to be underestimated; why don't you try asking a key business stakeholder to test out his legacy username and password on a quickly spun up screen-set after having migrated his credentials to SAP Customer Data Cloud? Migrating legacy hashes and validating them successfully is a key step forward in your migration project, enjoy a quick victory lap and be sure to check out the rest of the articles on this series.

Also, check out the other articles in the series for a deeper dive in this highly important topic:  Migrating to SAP Customer Data Cloud.