How can we help?




Follow

Authentication to apiserver

Stewart -

PROBLEM

How do I login to the apiserver and obtain tokens to redirect the browser to the UI to properly integrate a login form in their portal.

ENVIRONMENT

  • atmail suite - API server

CAUSE

Requirement to build custom login via client website.

RESOLUTION

Apiserver performs two steps authentication. The first step is to get an continuation token. The second step is to get an access token. The access token can then be used for other api requests.

Step 1: Get Continuation Token

curl -k -H 'Accept: application/json' \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"username":"example@domain.com","clientName":"webmail","clientVersion":"8.6.0","deviceName":"Chromium"}' \
    https://yourdomain/api/auth'
              

apiserver response:

{ 
"continuationToken": "CiAQO/+gh1s15emX4whw3b4imjSPZqQosrEPT38IEREDqRKYAkJycHY1UVVYMFpxcElZVmVxSlNTdzBIQjUrOHd2Q3FUUEI0ZU5nOW5uZVZFaHprM2VPSzFObTIrcFJaY05nbG0zd3lXSXpzRnoyQnlwaFdwTHd1ZHN3dEh3ZVg0RDQ3RWFWRmlIRlQ4NlVHR0YwRnhvUWJubG1TdEdHSzBoVFFLRS92OVFIK0hPZTE1TEtHQjNMN0tQWlpVSDhrR2hWSUMyZisrc1h1YmkyRzZUMXIwaHBJSVdQZ2gveW9NbzdSNXVJNkRmb2YveGhGNGNYU0xJUDNock50ZmwzeDRacllXTXJ3SDZKeUdHWFBsVG5Icm1FdlNaOUtoM3IzbnNZMFdnUHV5MFZIQ2duR3NVZjNqZEFDZjlnPT0=", "methods": [
...
],
"prompt": null
}

 

Step 2: Get Access Token

curl -k \
-H 'Accept: application/json' \
-H 'X-JMAP-Extensions: com.atmail.accounts:1' \
-H 'Content-Type: application/json' \
-d '{"method":"password","server":"","password":"changeme","token":"<continuation>"}' \
'https://yourdomain/api/auth'                

apiserver response:

{
  ...
  "accessToken": "CiD8i9EG/74lDR/ndSjw+n16zeANAnwf5tzNd8v+IMx7AxKAAzE5WHVIcTNBdSs2RGN1bFVqbVIvQW1VMjlFYTBGamtJa2JJRmtXeW5KaDBXQU5WT252ODlLVXE3RmU4Q2pjYUhDUXFQMTJNeVN5ckpxZlViNG1ZRXY0R3FrYWxRNlpkSXhOa0M3Q3RjOURiQWl3THJka2lwTlpPZ3Jva1ZaVkRqWVMrLzJOeGpGdnhIbk8yakdyT0M1MlIwQmM4YmVxbGVYejZrNVd0ZGZvQVgvMWp1RG5tMUlGQ3NyeFZsTTZrRHdmeFlOSEpZSzM4bFowQys0RVVpd2ZJdkJUaUk1MndGRUM4VkE3c0tKY25IK0k3NkwxRnN3V0dRK1lEZVRmdGx0YXFjR21xNEZBQWFnZ2hsVlAxTnFTRzMvazdqWnhsdzFsOXRmUnN0UElseXhtbkNrdnlPam5GaUVvWWYyNnRHR2ZHTVhzb3NremIrTFI5MTcwVGRMK1BicHdrdGRiL0I2N2dCbnNVN29pK1FPTWRKUUNCSTJ2ZFY4THdrZFdtSA==",
  ...
}
The access token then can be used for further api authentication.

Usage Example

Here is an usage example query users settings

curl \
-H 'Accept: application/json,' \
-H 'Authorization: Bearer <access token> \ -H 'X-JMAP-Extensions: com.atmail.accounts:1,com.atmail.calendar:1,com.atmail.calendaracl:1,com.atmail.filestore:1,com.atmail.gal:1,com.atmail.ics:1,com.atmail.license:1,com.atmail.mailboxupdate:1,com.atmail.messagecopy:1,com.atmail.nothreadupdates:1,com.atmail.task:1' \ -H 'Content-Type: application/json' -d '[["getSettings",{"accountId":"2"},"1556768515485"]]' \ 'http://atmail.ru:3000/jmap'
apiserver response:
[
[ "settings", { "accountId": "2", "settings": { "mail": { "markAsReadDelay": 2000 }, notifications": { "events": true, "mail": true } } }, "1556768515485" ] ]

Please Note:
The continuation token only valid for a very short period ( about 1 second by default).
 

Step 3: Re Get Continuation Token (Only needed in Transient Mode)

curl -k -H ‘Accept: application/json’ \
-H ‘Content-Type: application/json;charset=UTF-8’ \
-d ‘{“username”:“example@domain.com”,“clientName”:“webmail”,“clientVersion”:“8.6.0",“deviceName”:“Chromium”}’ \
’https://yourdomain/api/auth'
          

apiserver will response:

{
“continuationToken”: “CiAQO/+gh1s15emX4whw3b4imjSPZqQosrEPT38IEREDqRKYAkJycHY1UVVYMFpxcElZVmVxSlNTdzBIQjUrOHd2Q3FUUEI0ZU5nOW5uZVZFaHprM2VPSzFObTIrcFJaY05nbG0zd3lXSXpzRnoyQnlwaFdwTHd1ZHN3dEh3ZVg0RDQ3RWFWRmlIRlQ4NlVHR0YwRnhvUWJubG1TdEdHSzBoVFFLRS92OVFIK0hPZTE1TEtHQjNMN0tQWlpVSDhrR2hWSUMyZisrc1h1YmkyRzZUMXIwaHBJSVdQZ2gveW9NbzdSNXVJNkRmb2YveGhGNGNYU0xJUDNock50ZmwzeDRacllXTXJ3SDZKeUdHWFBsVG5Icm1FdlNaOUtoM3IzbnNZMFdnUHV5MFZIQ2duR3NVZjNqZEFDZjlnPT0=“,
“methods”: [ ... ], “prompt”: null }

Step 4: Set credentials claims in token (Only needed in Transient Mode)

curl -k -H ‘Accept: application/json’ \
-H ‘Content-Type: application/json;charset=UTF-8’ \
-d ‘{
“accessToken”: “<access_token_received_in_step_2",
“method”: “legacy”,
“token”: “<continuation_token_received_in_step_3>“,
“claims”: [
{
“claimtype”: “mail”,
“claimusername”: “example@domain.com”,
“claimpassword”: “changeme”
},
{
“claimtype”: “contact”,
“claimusername”: “test@domain.com”,
“claimpassword”: “changeme”
},
{
“claimtype”: “calendar”,
“claimusername”: “example@domain.com”,
“claimpassword”: “changeme”
},
{
“claimtype”: “smtp”,
“claimusername”: “example@domain.com”,
“claimpassword”: “changeme”
}
]
}’ \
’https://yourdomain/api/auth'

apiserver will response:

{
“username”: “example@domain.com”,
“extensions”: {...  },
“accessToken”: “new_token_in_transient_mode”,
...
}

Methods supported in step 4

Step 4 supports 2 methods, legacy and redirect. They both accept the same parameters and response in same format. The differences are redirect method will return a shorter version of access token while legacy will return the full length token. Due to some browser URL length limitation (IE has about 2k limit ), redirect method can be used to get a shorter version, which may be used for SSO redirect from portal.

Have more questions? Submit a request

Comments


Contact our support team


+61 (7) 5357 6605       support@atmail.com