Authentication

Samdock Microservices Authentication details.

Samdock Microservices uses JWT (JSON Web Token) to authenticate a user in order to access the endpoints. A client application must send a JSON Web Token (JWT) in the authorization header of the HTTP request to our Microservices. The authentication gateway validates the token, and processes the query as per the request if the user is successfully authenticated.

Retrieving JWT

Each user having an access to Samdock Portal can retrieve the JWT that can be used to access our Microservices. There are multiple ways to retrieve the JWT as shown below.

POST Request to Auth

A usual way for a developer to retrieve the JWT is by posting a request to the below endpoint with relevant credentials to retrieve the JWT.

curl --location --request POST 'https://auth-dev.samdock.app/login' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode '[email protected]' \
--data-urlencode 'password=password'
var client = new RestClient("https://auth-dev.samdock.app/login");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("email", "[email protected]");
request.AddParameter("password", "password");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var settings = {
  "url": "https://auth-dev.samdock.app/login",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  "data": {
    "email": "[email protected]",
    "password": "password"
  }
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
#import <Foundation/Foundation.h>

dispatch_semaphore_t sema = dispatch_semaphore_create(0);

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://auth-dev.samdock.app/login"]
  cachePolicy:NSURLRequestUseProtocolCachePolicy
  timeoutInterval:10.0];
NSDictionary *headers = @{
  @"Content-Type": @"application/x-www-form-urlencoded"
};

[request setAllHTTPHeaderFields:headers];
NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"[email protected]" dataUsingEncoding:NSUTF8StringEncoding]];
[postData appendData:[@"&password=password" dataUsingEncoding:NSUTF8StringEncoding]];
[request setHTTPBody:postData];

[request setHTTPMethod:@"POST"];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
  if (error) {
    NSLog(@"%@", error);
    dispatch_semaphore_signal(sema);
  } else {
    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
    NSError *parseError = nil;
    NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:data options:0 error:&parseError];
    NSLog(@"%@",responseDictionary);
    dispatch_semaphore_signal(sema);
  }
}];
[dataTask resume];
dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://auth-dev.samdock.app/login');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/x-www-form-urlencoded'
));
$request->addPostParameter(array(
  'email' => '[email protected]',
  'password' => 'password'
));
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}
import http.client

conn = http.client.HTTPSConnection("auth-dev.samdock.app")
payload = 'email=email%40email.com&password=password'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}
conn.request("POST", "/login", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Content-Type", "application/x-www-form-urlencoded")

$body = "email=email%40email.com&password=password"

$response = Invoke-RestMethod 'https://auth-dev.samdock.app/login' -Method 'POST' -Headers $headers -Body $body
$response | ConvertTo-Json

This request yields a response containing accessToken and a refreshToken.

{
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiJydTRienpqY2UzMGJCa1E4NkNaUDEiLCJfdGVuYW50SUQiOiJTUEdQc1UteWh5LTdaMzVUTGFEci0iLCJmaXJzdE5hbWUiOiJPbWVyIiwibGFzdE5hbWUiOiJGYXJvb3EiLCJlbWFpbCI6Im96ZmFyb29xQGdtYWlsLmNvbSIsImlzQWRtaW4iOnRydWUsInRyaWFsRXhwaXJhdGlvblRpbWVzdGFtcCI6bnVsbCwibGFuZ3VhZ2UiOiJicm93c2VyIiwic3Vic2NyaXB0aW9uQWN0aXZlIjp0cnVlLCJpc0VtYWlsVmVyaWZpZWQiOnRydWUsInRlbmFudE5hbWUiOiJPWkZBUk9PUSIsImlhdCI6MTYzMDM1MTQzOSwiZXhwIjoxNjMwMzUxNzM5LCJpc3MiOiJodHRwczovL2F1dGguc2FtZG9jay5hcHAiLCJzdWIiOiJvemZhcm9vcUBnbWFpbC5jb20ifQ.T6qOlxBedcnn3YM9rSNex0E6DoHO8Jhk8PrfbAV0FvufMqcy_AoV_Eoduo-NZbjIFhrfRKobi8OTVh6L5_DSL8e70lggaVQ1R55LpceqvMvRy1OoMCf_cvuqxTivfvC6wwAMOCBAmcW8Bp8U7VLS4MMT8VwfKd49Gm7nUQDqhrfVfHEmBc4OHWFGJmUU6giazt9BLYZ7TleQVI3JTfOzb8k-2cMgVjGo-27F-U9iRL2aB1ENVHj-TvTXFez880p6gSExKPy0jb2VJ5F2FvkoWslohhYj2qIdwBwNiTyCTGaSW3RSctZ7TopnvFz8X5pS5AVl4-V32p83fVMoldUZQ0K5CnTGkIQc71WlIeOnSqYr9fa6JpNlNZTSHEQV8DBTfpI2VPvj-h9ZnS2cE7rio4Z2yhno8bPhDesnYC5J3IHjKgXyMFyFveXomF23EMX8Lu--vHalmxeaec_v3AI5tivR4Dokm9myZ7fPv9dhLzdJptc1m6aslBB68Xssl8v0HbYA-Sd33_sPbJq-Sc6_EmGWR02QswebUN6hF_Vty5KfavmyRZuGn8bPu6WLtUHBv8CFiNME_Pkry_bIKJBn1vJBPFRHoKtyMzjJm9rdglIe1o_QcapCE69HY-MpMW8LEd7zS9bn4WJM2wvb88kGvqKKc8J6mbHrdkDKPJDjNoY",
    "refreshToken": "pmgxt3qFFwMiOaBUPBlzQbvqeC2l0d8GHN5uDMFA5hvoeYE7QolJc11YkiLTAZSw"
}

accessToken consists of 3 sections which is a standard JWT approach i.e. Header, Payload, and Verification Signature. Here is how a typical payload looks like within the generated access token.

724

JWT Payload

📘

Token Expiry & Refresh

  • Default token expiry is currently set to 5 minutes.
  • refreshTokenand accessToken is used to refresh the JWT once it is expired.

Token Refresh

Once a token is expired, the developer has an option to refresh the token by using the accessToken and a refreshToken retrieved during the JWT retrieval operation as follows.

https://auth-dev.samdock.app/token/refresh

curl --location --request POST 'https://auth-dev.samdock.app/token/refresh' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'accessToken=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiJydTRienpqY2UzMGJCa1E4NkNaUDEiLCJfdGVuYW50SUQiOiJTUEdQc1UteWh5LTdaMzVUTGFEci0iLCJmaXJzdE5hbWUiOiJPbWVyIiwibGFzdE5hbWUiOiJGYXJvb3EiLCJlbWFpbCI6Im96ZmFyb29xQGdtYWlsLmNvbSIsImlzQWRtaW4iOnRydWUsInRyaWFsRXhwaXJhdGlvblRpbWVzdGFtcCI6bnVsbCwibGFuZ3VhZ2UiOiJicm93c2VyIiwic3Vic2NyaXB0aW9uQWN0aXZlIjp0cnVlLCJpc0VtYWlsVmVyaWZpZWQiOnRydWUsInRlbmFudE5hbWUiOiJPWkZBUk9PUSIsImlhdCI6MTYzMDM1MTQzOSwiZXhwIjoxNjMwMzUxNzM5LCJpc3MiOiJodHRwczovL2F1dGguc2FtZG9jay5hcHAiLCJzdWIiOiJvemZhcm9vcUBnbWFpbC5jb20ifQ.T6qOlxBedcnn3YM9rSNex0E6DoHO8Jhk8PrfbAV0FvufMqcy_AoV_Eoduo-NZbjIFhrfRKobi8OTVh6L5_DSL8e70lggaVQ1R55LpceqvMvRy1OoMCf_cvuqxTivfvC6wwAMOCBAmcW8Bp8U7VLS4MMT8VwfKd49Gm7nUQDqhrfVfHEmBc4OHWFGJmUU6giazt9BLYZ7TleQVI3JTfOzb8k-2cMgVjGo-27F-U9iRL2aB1ENVHj-TvTXFez880p6gSExKPy0jb2VJ5F2FvkoWslohhYj2qIdwBwNiTyCTGaSW3RSctZ7TopnvFz8X5pS5AVl4-V32p83fVMoldUZQ0K5CnTGkIQc71WlIeOnSqYr9fa6JpNlNZTSHEQV8DBTfpI2VPvj-h9ZnS2cE7rio4Z2yhno8bPhDesnYC5J3IHjKgXyMFyFveXomF23EMX8Lu--vHalmxeaec_v3AI5tivR4Dokm9myZ7fPv9dhLzdJptc1m6aslBB68Xssl8v0HbYA-Sd33_sPbJq-Sc6_EmGWR02QswebUN6hF_Vty5KfavmyRZuGn8bPu6WLtUHBv8CFiNME_Pkry_bIKJBn1vJBPFRHoKtyMzjJm9rdglIe1o_QcapCE69HY-MpMW8LEd7zS9bn4WJM2wvb88kGvqKKc8J6mbHrdkDKPJDjNoY' \
--data-urlencode 'refreshToken=pmgxt3qFFwMiOaBUPBlzQbvqeC2l0d8GHN5uDMFA5hvoeYE7QolJc11YkiLTAZSw'

This will provide a new accessToken and a refreshToken against the same user which was used to retrieve the original access token.

Auth Header

A non-conventional way to retrieve the JWT is by logging into the Samdock developer portal and access the accessToken through the Browser Developer Tool Interface (F12).

1920

Browser Developer Tool Interface (F12)

🚧

Recomendatation for Token

It is always recommended to retrieve the JWT through POST Request always. As this can be programtically handled within the Web Application, and refreshing token gets much convenient .

Using JWT for Microservices

Once JWT is retrieved, any endpoints within the Microservices can be consumed by just passing it within the Header.

curl --location --request POST 'https://dev.samdock.app/api/attachments/upload' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiJlNzE5NThmYi1hNWZmLTRiYTktYjM1YS02ZGQ3ZWFhM2VkYTEiLCJmaXJzdE5hbWUiOiJEbWl0cnlzc2EiLCJsYXN0TmFtZSI6Ilpob3JvdiIsIl90ZW5hbnRJRCI6ImQ4ODU0YjRhLThhMzEtNGNhMi1iNzI5LTYzOGMwYTgwYTlmMyIsImVtYWlsIjoib2JzbnJkQGdtYWlsLmNvbSIsImlzQWRtaW4iOnRydWUsInRyaWFsRXhwaXJhdGlvblRpbWVzdGFtcCI6MTY0MDkwNTIwMDAwMCwic3Vic2NyaXB0aW9uQWN0aXZlIjpmYWxzZSwibGFuZ3VhZ2UiOiJlbiIsImF2YXRhciI6bnVsbCwidGVuYW50TmFtZSI6IlRlc3QgQ28iLCJpc0VtYWlsVmVyaWZpZWQiOnRydWUsImlzU2lnbnVwVXNlciI6dHJ1ZSwiaWF0IjoxNjI5ODA0NDY5LCJleHAiOjE2Mjk4MDQ3NjksImlzcyI6Imh0dHBzOi8vYXV0aC5zYW1kb2NrLmFwcCIsInN1YiI6Im9ic25yZEBnbWFpbC5jb20ifQ.BW8V5g7JQyiUvQCLXxrzchMiST46wNSDs-vxArcevSGMnOTRLK5F1ka54utxJBRK8wsIlZ2WTzuoyQq4nvkFewYFC6qo4QY3zvdr9-FPPBfTjYrhetMN_Djrfn3ovkPZv6A-8McEZvLj8a0NiLrXK-IGDFP--CCBQZVvoAJNxCC7SMMGjawFn3ebCeEBTcOhgyDIo8cyxIw1Q8qSWgEoC9lKFk7HDPAFBXFWiYmQHDmiXSdvS_mc1TZcsuD2e2bkY2xNDbdf5CcMslqPuBBWmz21DpXCDA4H2HF0o34Ee2IzdB_sO6L6mG-Wxo34RNxB9kHySersoafriLXBJSKk2QMfTMZ-wWcqcSlzUXLrZsXmTT3R9AqC2gMwRZmH27TnByyev_jvT-ETaRHmZzYCVQTTAzwqoRWix_2WVHk-fgOFIVYAtpbusQFe4AXDMjuq0YkhrBqA3w3wMX0WanNCthhJ60IkqJ7kfwgNitxOtV6FE87am6c5osw3Z6RPPIm6ufXTUmcPESNk4hBDKwWKAufuQ55BmbKI9HytgK52zAnTYxzPcN9FFw4Xpuht81BSGBDrLgFSHZfhyY2hMZeS5XNmbdBFD7zkBhN3IrydLvShk2T0IOaFxmEcw2AERN0HRlmgKoCMmjtZH44_SeN_IbaIyohXNWzDk0RJlsCibT0' \
--form 'attachments=@"/Users/xagrh/Downloads/undo.svg"'