If you need to save the settings for the individual installation of an addon, you can use the OAuth server to identify the e-shop’s admins.
By using this user authentication mechanism, you will be sure that the user is the actual administrator of the e-shop and you do not need to address its access credentials and authorization to edit the settings of your addon.
This is only a verification mechanism and does not allow you to save data (typically addon settings) – you must save the data yourself in your data structure.
The procedure assumes that you have an e-shop number stored in your API access token database. In other words, you can use the correct API access token
from the e-shop number shopId
.
The first step to identify a user and their e-shop is to determine the hostname OAuth server, against which you will validate the user’s identity.
Enter “Link to external addon settings” in the description of the addon.
If you enter #SHOP_ID#
into the URL, this will be replaced by the actual e-shop id.
For example https://www.my-server.cz/shoptet/addons/my-addon/settings?eshopId=#SHOP_ID#
will be replaced by https://www.my-server.cz/shoptet/addons/my-addon/settings?eshopId=12345
If you enter #LANGUAGE#
into the URL, this will be replaced by the actual e-shop language.
For example https://www.my-server.cz/shoptet/addons/my-addon/settings?language=#LANGUAGE#
will be replaced by https://www.my-server.cz/shoptet/addons/my-addon/setting?language=cs
From the eshopId
you receive, you will find the corresponding API access token
in your database and call the endpoint Eshop info. In the response, check array data.urls[]
and look for object with ident
having value oauth
and use the value of url
field as an OAuth server address of the user, who was logged in.
<?php
// your function to get the url from the reply of the endpoint (eshop info)
$baseOAuthUrl = getOAuthUrl($response);
$_SESSION['base_oauth_url'] = $baseOAuthUrl;
Save URL to current user (e.g. into session) – the value will be needed in the next step.
Assemble url to redirect the user to.
// $_SESSION['base_oauth_url'] contains the ending slash
$url = $_SESSION['base_oauth_url'] . 'authorize';
Add GET parameters to url:
// Your client id in OAuth server
// This is an example only, the specific value can be found in
// the e-shop administration -> Link -> API partner -> Access to API
$param['client_id'] = 'wae54...slekn';
// authorization group in OAuth server, enter 'basic_eshop'
$param['scope'] = 'basic_eshop';
To increase the security, add state
parameter.
$state = uniqid();
$_SESSION["state"] = $state;
$param['state'] = $state;
The state parameter is not mandatory, it is used as protection against XSRF attacks. the state
value must be generated and saved to the user. When you add state
to the request to the OAuth server, then the parameter and its value will be added to the reply from authorization server. For check, see below.
Then you add response_type
and redirect_uri
parameters.
// response_type is always 'code'
$param['response_type'] = 'code';
// returning url (to your server), to which the OAuth server redirects the user after sucessful verification
// redirect_uri must be entered in addon settins as "URL for user authorization".
// The OAuth server inspects whether the addresses are matching;
// if the address entered in administration does not match with address sent,
// the OAuth server responds with error
$param['redirect_uri'] = 'https://www.mujserver.cz/shoptet/doplnky/muj-doplnek/code';
// Then create the url and redirect the user to OAuth server
$url = $url . "?" . http_build_query($param);
header("Location: " . $url);
Next step is to get the OAuth access token, which will provide you with the identity of the user or e-shop.
ATTENTION: This OAuth access token is different from the OAuth access token you get when you install the addon.
After redirection in step 2. The OAuth server authenticates the user and redirects it to your redirect_uri
.
In GET parameters, you get the value code
and optionally also the state
.
$code = $_GET['code'];
$state = $_GET['state'];
// Check state parameters. When the values are different, someone other than you
// initiated the request and your code should not continue.
if ($state != $_SESSION['state]) {
die('State parameters do not macth');
}
We will compile a request parameter for the OAuth access token. The request is sent in the background, without the user’s knowledge.
$data = [
// $code is the value from the GET parameter
'code' => $code,
// grant_type is always 'authorization_code'
'grant_type' => 'authorization_code',
// Your client id in OAuth server
// This is an example only, the specific value can be found in
// e-shop administration -> Link -> API partner -> Access to API
'client_id' => '{$partnerProject->oauthClientId|escape}',
// Your secret string for communication with OAuth server.
// The specific value can be found in e-shop administration -> Link -> API partner -> Access to API.
// Contact Shoptet, if client_secret is not available (for older API partners, it was not generated automatically)
'client_secret' => '123l4kjl12k3j4ce098kjh34acghkyp4jsj1h324',
// redirect_uri must be entered in addon settings as "URL for user authorization".
// The OAuth server inspects whether the addresses are matching;
// if the address entered in administration does not match with address sent, the OAuth server responds with error
'redirect_uri' => 'https://www.mujserver.cz/shoptet/doplnky/muj-doplnek/code',
// Enter 'basic_eshop'
'scope' => 'basic_eshop'
];
$url = $_SESSION['base_oauth_url'] . 'token';
Send POST request:
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_POST, TRUE);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
die("CURL Error: " . $err);
}
The reply will contain the access_token
in JSON format:
{"access_token":"90r3azmxy6dbxzpjfxj237cjt8rp0f4hq6uygone78i4n4zk47xb649pls1097fc0xs501hjhpv9tlj2k9hc6xhutymtthet8dzx0sm1ih7r6ml6gf6hc4dixqn48l0r5qk1ynqp0fvojief30b2f70rnedfcy2zyqhkin326ynvdv404hn1xw8nqct6rkn9h4xm9za2i53pbb8hqkmz37qdpol5yr3dciftn0vl04jfvpxg4l36lnw9vsqdyke","expires_in":43200,"token_type":"bearer","scope":"basic_eshop"}
$response = json_decode($response, TRUE);
$accessToken = $response['access_token'];
The e-shop’s identity is obtained from the OAuth server response.
Submit a request to the OAuth server with an authorization header having the OAuth access token value.
Assemble the url you will be sending the request to:
$url = $_SESSION['base_oauth_url'] . 'resource?method=getBasicEshop';
The OAuth access token is sent in the request header:
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $accessToken]);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
$response = curl_exec($curl);
curl_close($curl);
If the request is processed OK, it contains $response
key success
with value true
.
{"success":true,"data":{"user":{"email":"novak@fenix.myshoptet.com","name":"Jan Novak"}, "project": {"id":159834,"url":"https:\/\/fenix.myshoptet.com\/","name":"F\u00e9nix"}}}
In $response
in the data object is theid
and url
, which identifies the e-shop.
$response = json_decode($response, TRUE);
$_SESSION['project_id'] = $response['data']['project']['id'];
Getting the project_id
gives you the linked current user of your pages with the e-shop administrator.
Error identification
If the error occurs, in the $response
key, there is an error
and error_description
{"error":"You must use `client_secret`. Please contact us to obtain one.","error_description":null}