Leverage Authentication Plugins To Migrate Data

The Migrations API in Drupal 8 is a Swiss Army knife. While migrating one of our clients’ sites to Drupal 8, we encountered an interesting scenario. Being a large organization with a high volume of content production, they were not able to provide direct database access for the migration. Instead, they suggested using their existing JSON API to fetch the data for the migration source.

As the client’s data end-points were secured using the API, we had to use API keys to access these endpoints.

Since the entire migration API is built using a plugin-based architecture, we were able to leverage the migrate_plus module’s authentication plugins. You can see other migration plugins here. We’ve shared similar posts around migration plugins in the past, like this one about creating id_map plugins.

About Authentication Plugins 

Authentication plugins from the migrate_plus module allow us to leverage various authentication approaches in the source plugin. So when our migration source is protected with a key, we can pass various attributes like headers, key-value, etc, for authentication purposes. We leveraged the authentication plugins to send authenticated requests. We also used a key module to store the keys for best practices.

We will implement this in two steps. The first is to create the authentication plugin, and
the second is to use the plugin in the migration template.

First, let’s go through the plugin implementation. For the authentication plugin, we use Plugin\migrate_plus\authentication namespace. Let’s say our module name is “custom_key_auth.” In our module, we’ll need to create our plugin class at the following path:

custom_key_auth/src/Plugin/migrate_plus/authentication/CustomApiKey.php

I’ve added a trimmed down version of the class here for reference; you can find the full example in this GitHub repository: https://github.com/mohit-rocks/custom_key_auth

Let’s go through the implementation for the CustomApiKey.php plugin class.

As Drupal’s plugin system works based on annotations, we have defined “@Authentication” to declare that this is going to be an authentication plugin.

After that, in the “getAuthenticationOptions()” method, we’ll check if we are using a key module as a key storage mechanism. If we are using a key module, then we’ll fetch the key from the configuration and fetch its value using the keyRepository service.

Now, as we have the plugin ready, we are ready to use it in our migration template files. I’ve created a sample migration template file here (on GitHub). Let’s see a small snippet from the migration’s source plugin data.

Here, in the “authentication” key in the source plugin’s configuration, we’ve specified the authentication plugin’s information. The plugin key tells the plugin manager which plugin to target, and we’re also passing other data attributes, like keyname and header name, which will help to build authentication requests.

Based on the value of the “keyname” attribute, our plugin will fetch the key value by using the “key.repository” service and return the proper data.

As we have seen in the example above, the Migration API is pretty robust and we can leverage it for various use cases. The out-of-box Migrate module and Migration API provide various Source, Process, Destination, ID-Map, Authentication, Data Fetcher, and Data Parser plugins that you can leverage for your use cases. 

Apart from the core Migrate API, key modules like migrate_plus, migrate_tools, migrate_source_csv, migrate_source_json are really helpful in various migration use cases.