Magento 2: Understanding Integration API Users

This one’s a follow up to my Magento 2: Understanding the Web API Architecture post. In that post I gloss over Magento’s oAuth implementation, and what I did say got several details wrong. This article aims to fix that.

To understand Magento’s oAuth features, you need to understand the (related) integrations feature. To understand integrations, you need to understand the problem integrations want to solve.

Magento 2 Integrations

There are many third party services that want to integration with Magento. Analytics trackers, order processing system, etc. Put another way, many of these third party services would like to integrate with the Magento API.

In Magento 1, this meant a store owner had to

1. Create a set of Web Services credentials in the back end
2. Create and assign appropriate ACL role(s) for those credentials
3. Give those credentials to the third party service.
4. Or, the service extension needed to get into the grey hat area of creating their own credentials on the system

The problem of API credentials is an old one for all web services, and one a set of token based authentication methods known as oAuth tries to solve. oAuth is – not great, but it’s what The Industry™ uses, and so its what Magento 2 uses.

With Magento 2, if you run a third party application that wants to use the Magento API, and you don’t want to ask the folks who run the Magento instance to create a user account for you, you need to

1. Create an integration object in Magento’s back end
2. Create oAuth URL endpoints what will “activate” the integration object
3. Use the tokens you create during an integration activation process to request an oAuth access token

This oAuth access token is similar to the username and password tokens we discussed last time, as it will allow you to make API requests to Magento API end points in a specific Magento system. These tokens replace the tokens normally requested via the V1/integration/customer/token or V1/integration/admin/token endpoints. However, these tokens work differently than Magento’s native tokens, which we’ll discuss later.

Magento 2 Integration Objects

An integration object contains

1. A list of ACL roles that define the specific API methods a third party application may access
2. Information about the integration’s oAuth endpoints

You can create integration objects manually at

System -> Integrations

However, cryptic comments on the developer documentation site make it sound like integrations will be a special section of Magento Marketplace (the replacement for Magento Connect)

You can register Integration through Magento Connect. After successful registration, Magento Connect generates a configuration file. If you choose not to register the Integration through Magento Connect, you can manually create the configuration file and make it available to merchants.

This implies a merchant will be able to go on to Marketplace and add an integration that a third party developer has registered there.

It’s also possible for third parties to offer an extension that uses Magento’s installer schema feature to create the integration objects when the extension is first installed.

Your main takeaway here should be, although its possible to manually create an integration, it will be far more common for the information in System -> Integrations to be automatically populated.

Another takeaway: Unlike Magento 1, a third party application (via an integration) can define the ACL permissions they’ll need access to. This changes the burden from Magento 1 where a store owner had to figure out what permissions to assign to a user.

Magento 2 oAuth Overview

Once an integration is added to the system, a merchant must manually activate it.

From the perspective of a merchant, activating an integration means

1. Reviewing the ACL permissions the integration requests, and deciding if the third party service should be granted access
2. Logging into the third party service successfully

Clicking the Activate button will open a pop-up window where the merchant can log into the third party service. Be sure you’ve turned off your browser’s popup blocker!

On the other hand, a third party service owner (the owner of the analytics extension, the order processing service, etc) must

1. Implement an oAuth login page
2. Implement an oAuth token processing page to generate an oAuth request and access token
3. Store the generated oAuth access token, and store the relationship between the logged in user (the merchant/system owner) and the access token

The oAuth login page is the Identity link URL field of an integration object. It’s the page Magento opens when a merchant clicks the Activate button.

The oAuth token processing page is the Callback URL field of an integration object. When a merchant clicks the Activate button, Magento will POST several oAuth fields to the Callback URL. There is no visible UI for this step.

Magento 2 oAuth: Login/Identity Page

The purpose of the login/identity page is to identify the merchant activating an integration and to make sure this merchant has an account on the third party system. Notice that oAuth is biased towards assuming these third party system are user/identity based.

When Magento opens the oAuth login page, Magento sends two GET parameters along with the URL – an oauth_consumer_key and a success_call_back key.

Array
(
    [oauth_consumer_key] => e0e0665e24297959445...etc
    [success_call_back] => http://magento-2-0-4.dev/admin/admin/integration/loginSuccessCallback/key/edcc8c26242e281e96.......d41e5a253ae0e0665e2429795944568f0385307/
)

Important: Up until March 15th, the above functionality was broken. If you’re seeing consumer_id instead of oauth_consumer_key – you need to upgrade to a newer version of Magento. As of this writing, that newer version doesn’t exist, but some little elves told me it will be Magento in 2.1.

The third party service owner must implement a login page for their service. If a user logs in successfully with their third party service credentials, the third party service should

1. Write down the oauth_consumer_key, (and maybe the success_call_back, just to be complete) into storage (i.e. a database table)
2. Write down the relationship between the logged in user and the oauth_consumer_key
3. Redirect the user to the success_call_back URL

When you redirect back to Magento with the success_call_back URL, Magento will automatically close the pop-up window it opened.

The success_call_back URL also serves another purpose – it identifies the specific Magento system that we’re trying to get access to. This may be relevant to your service, which is why you might want to write this information down.

Magento 2 oAuth: Token Processing Page

The token processing page is a second URL Magento will make an HTTP request to when activating a server. Remember, this is the callback URL field in an integration object. This page is also hosted on the third party service’s servers (or a server they have access to). This page will receive a POST request with the following parameters

Called Array
(
    [oauth_consumer_key] => 2unvs7ccym............77kvlxx1rp
    [oauth_consumer_secret] => 1skp6............yy842a49xrjkaqb
    [store_base_url] => http://magento-2-0-4.dev/
    [oauth_verifier] => ku8wjnqxuxj98x0ruwf............4
)

The oauth_consumer_key will allow you to tie this request back to the request made to the identity/login page above. This will, in turn, allow you tie this request back to a specific user in your third party system. (this is why you wrote down the the relationship between the oauth_consumer_key and the logged in user above). You will not be able to make this relationship is real time, as the Identity/Login page and the token processing page/callback URL

You will use the above information to fetch a temporary request token from the Magento system by posting to /oauth/token/request. There’s more information on the specifics of this on the dev docs site.

Once you have this temporary request token, your job isn’t done. You use the request token to fetch a long lived access token from /oauth/token/access. Again, the dev docs site has the specifics on this request.

Once you have this access token, you write it down in your database – again, associating it with the user id that you previously wrote down.

When your token request is complete, Magento will consider the integration activated.

As the third party application developer, you now have an access token that you can use to make requests into a specific Magento system, with a specific set of ACL permissions, whenever you need to use the API on that users behalf. Be sure to read the dev docs site for information on using an oAuth token to access an API endpoint. The headers are different from a normal Magento API request.

Again, the above information may be incomplete/incorrect. If you have a correction please find me and let me know. These are strange new days for all of us.