Skip to content

Home

Jump to bottom
Lucas Banegas edited this page Jun 1, 2018 · 11 revisions

Requirements

The following versions of PHP are supported.

  • PHP 5.6
  • PHP 7.0
  • PHP 7.1
  • PHP 7.2
  • HHVM

Install

Via Composer

$ composer require docta/oauth2-mercadolibre

Configure

This provider has four required options and does not use any other option. Not declaring any of these options implies the throwing of an exception.

$provider = new \Docta\MercadoLibre\OAuth2\Client\Provider([
    'authSite'     => '{mercadolibre-auth-site}',
    'clientId'     => '{mercadolibre-client-id}',
    'clientSecret' => '{mercadolibre-client-secret}',
    'redirectUri'  => 'https://example.com/oauth'
]);
  • authSite corresponds to the country in which you registered your application. Depending on which country you have registered the application, it will also depend on the authorization url that this provider will use. For example, if the application was registered for Argentina, the value of authSite must be MLA; and consequently, the service provider will use the following url: https://auth.mercadolibre.com.ar 
/**
 * The keys of this array are the only values allowed by `authSite`.
 * Example: for an application registered in Argentina you must use 'MLA'
 */
$authSites = [
    'MLA' => 'https://auth.mercadolibre.com.ar', // Argentina 
    'MLB' => 'https://auth.mercadolivre.com.br', // Brasil
    'MCO' => 'https://auth.mercadolibre.com.co', // Colombia
    'MCR' => 'https://auth.mercadolibre.com.cr', // Costa Rica
    'MEC' => 'https://auth.mercadolibre.com.ec', // Ecuador
    'MLC' => 'https://auth.mercadolibre.cl',     // Chile
    'MLM' => 'https://auth.mercadolibre.com.mx', // Mexico
    'MLU' => 'https://auth.mercadolibre.com.uy', // Uruguay
    'MLV' => 'https://auth.mercadolibre.com.ve', // Venezuela
    'MPA' => 'https://auth.mercadolibre.com.pa', // Panama
    'MPE' => 'https://auth.mercadolibre.com.pe', // Peru
    'MPT' => 'https://auth.mercadolibre.com.pt', // Portugal
    'MRD' => 'https://auth.mercadolibre.com.do'  // Dominicana
];

  • clientId and clientSecret are two values that you will get when registering your application in MercadoLibre and they appear as App ID and Secret key respectively. To register your application, you must access to http://applications.mercadolibre.com

  • redirectUri is the url to which the user will be redirected after authenticating at MercadoLibre and granting the necessary permissions. In this url we will receive the code that we will then exchange for a token. Below is an example.

Usage

Usage is the same as OAuth 2.0 Client, using \Docta\MercadoLibre\OAuth2\Client\Provider as the provider.

Authorization code grant

$provider = new \Docta\MercadoLibre\OAuth2\Client\Provider([
    'authSite'     => '{mercadolibre-auth-site}',
    'clientId'     => '{mercadolibre-client-id}',
    'clientSecret' => '{mercadolibre-client-secret}',
    'redirectUri'  => 'https://example.com/oauth'
]);

/**
 * If we do not have an authorization code then get one
 */
if (!isset($_GET['code'])) {

    /**
     * Get the MercadoLibre authorization URL; return the url and also generate
     * and apply other necessary query parameters (for example: state).
     */
    $authUrl = $provider->getAuthorizationUrl();

    /**
     * Get the generated state and save in session.
     */
    $_SESSION['state'] = $provider->getState();

    /**
     * Redirect the user to the authorization URL
     */
    header('Location: '.$authUrl);
    exit;

/**
 * Check the state returned by MercadoLibre against the state
 * previously stored in session to mitigate the CSRF attack.
 */
} elseif (empty($_GET['state']) || ($_GET['state'] !== $_SESSION['state'])) {

    unset($_SESSION['state']);
    exit('Invalid state');

/**
 * If the state stored in session and the state returned
 * by MercadoLibre are the same, then continue.
 */
} else {

    try {
        /**
         * Try to exchange the code obtained by an access
         * token (using the authorization code grant).
         */
        $token = $provider->getAccessToken('authorization_code', [
            'code' => $_GET['code']
        ]);

        /**
         * Optional: Now that we have a token, we can check
         * the data of the owner of the resources.
         */
        $owner = $provider->getResourceOwner($token);

        /**
         * And from now on to be able to consult the protected resources.
         * For example, to consult our list of products, we would send a
         * request like the following:
         */
        $itemsRequest = $provider->getAuthenticatedRequest('POST', 'https://api.mercadolibre.com/items', $token);
        $itemsResponse = $provider->getParsedResponse($itemsRequest);

    /**
     * Failed to get the access token, the owner details or the items request.
     */
    } catch (\League\OAuth2\Client\Provider\Exception\IdentityProviderException $e) {

        exit($e->getMessage());

    }
}

Refresh a token

$provider = new \Docta\MercadoLibre\OAuth2\Client\Provider([
    'authSite'     => '{mercadolibre-auth-site}',
    'clientId'     => '{mercadolibre-client-id}',
    'clientSecret' => '{mercadolibre-client-secret}',
    'redirectUri'  => 'https://example.com/oauth'
]);

/**
 * Keep in mind that the function `getStoredToken` is not part of this provider,
 * but is a function that you must create and may vary in each project, since it
 * can be stored in databases, cookies, sessions, files, etc.
 */
$storedToken = getStoredToken();

/**
 * Verify if the stored token has expired.
 */
if ($storedToken->hasExpired()) {

    /**
     * If the stored token has expired, then you request a new one.
     */
    $newToken = $provider->getAccessToken('refresh_token', [
        'refresh_token' => $storedToken->getRefreshToken()
    ]);

    /**
     * From here you will have to purge the old token and store the new
     * token in the way and at the place it seems most convenient. Note that
     * the `storeToken` function is also not a function of this provider.
     */
    storeToken($newToken);
}

Server side flow

In short, the authentication process of MercadoLibre through OAuth2, is as follows:

Server-Side Flow

Other useful resources

OAuth2 provider developed by Lucas Banegas

Clone this wiki locally