Migrating users

Last updated on
21 January 2018

The migrate destination plugin entity:user lets you migrate users into Drupal 8.

Migrating users from a source with MD5 hashed passwords

If the passwords are MD5 hashed in the source, the users can be migrated so that the original passwords are preserved. This can be done by using the md5_passwords: true configuration option. Drupal 6 and earlier stored the passwords as MD5 hashes like many other CMS systems.

destination:
  plugin: entity:user
  md5_passwords: true

The passwords are salted and re-hashed before they are saved into the Drupal 8 database. 

The example below uses EmptySource source plugin for the sake of simplicity. The MD5 hash in the example is a hash of 'password'.  

id: custom_user_migration
label: Custom user migration
source:
  plugin: empty
  constants:
    name: johnsmith
    mail: johnsmith@example.com
    pass: '5f4dcc3b5aa765d61d8327deb882cf99'
    status: 1
process:
  name: constants/name
  mail: constants/mail
  pass: constants/pass
  status: constants/status
destination:
  plugin: entity:user
  md5_passwords: true

Migrating users from a source with plain text passwords

If the passwords are plain text in the source, you can migrate the users without the md5_passwords: true configuration option. This will populate the plain text passwords to the users_field_data database table. The users can not log in with their original passwords because Drupal normally saves the salted password hash in this table and compares the hashes during authentication. This means that the users need to reset their passwords using the normal 'Reset your password' functionality and one-time logins will be emailed to their email addresses.

Another option is write a small custom module that implements hook_migrate_prepare_row().

  • Your source provides a plain text property, plaintext.
  • Your hook implementation will hash this using MD5 and set this as a new source property called md5hash.
  • You can then map the destination property pass from the md5hash source property and use the md5_passwords: true configuration option as above. 
id: custom_user_migration
label: Custom user migration
source:
  plugin: empty
  constants:
    name: johnsmith
    mail: johnsmith@example.com
    plaintext: super-secret-pw
    status: 1
process:
  name: constants/name
  mail: constants/mail
  pass: md5hash
  status: constants/status
destination:
  plugin: entity:user
  md5_passwords: true

Example hook implementation in a custom module called MYMODULE. This takes the source plaintext property, calculates the MD5 hash for it and then sets that value to a new source property md5hash that can be used in the migration process as illustrated above.

function mymodule_migrate_prepare_row(Row $row, MigrateSourceInterface $source, MigrationInterface $migration) {
  if ($migration->id() == 'custom_user_migration') {
    $plaintext = $row->getSourceProperty('plaintext');
    $md5hash = md5($plaintext);
    $row->setSourceProperty('md5hash', $md5hash);
  }
}

List of user properties

In addition to the 'name', 'mail', 'pass' and 'status' properties used in the examples, the following properties are available on the user entity.

  • uid, leave this out if you want Drupal to generate the unique user IDs for the migrated users
  • langcode
  • preferred_langcode
  • preferred_admin_langcode
  • timezone, see http://php.net/manual/en/timezones.php
  • created, timestamp on when the user account was created
  • changed, timestamp on when the user account was changed
  • access, timestamp on when the user last accessed the site
  • login, timestamp on when the user last logged in
  • init, the initial email address used when the user account was created 

Executing the migrations

Read more on Executing migrations documentation page.

Other source plugins

The examples on this page use the EmptySource source plugin for the sake of simplicity. You can modify the example and use other source plugins: