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.

Direct Webmail Login Link

Some customers may wish to provide a link that directly logs their users into webmail via their own portal without them having to explicitly login to webmail. In this case they can provide a link for the user to use that can drop the user directly into their INBOX. While not a true SSO solution, it can at least give the impression of SSO to the end user (i.e. they do not have to enter their login details again to login to webmail).

Prerequisites:

  1. For this to be possible the system creating the link will need to have access to the user's email address and password

Authentication

First up you will need to authenticate the user with atmail apiserver using their stored username and password. This is a two stage process covered in steps 1 and 2. We are specifically after the stage 2 response.

Sample auth stage 2 response:

{"username":"user@atmail.ms","versions":[0.1],"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.noop":[1],"com.atmail.nothreadupdates":[1],"com.atmail.partcommit":[1],"com.atmail.task":[1]},"accessToken":"eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2R0NNIn0.OkHNsZnA4gLhXXYk82-7hRI2Idq1ZKMlJgASsJ9KGZRYp3zWg1plMQ.BtM862uCO-bdn3IV.FGPS8eLbGVz2ZD1v5qz97XC3qUR3uXvIuYuSVpPKE79zrE8YuE5RMWaJZnYTuklfbiJC8ynCV6d1F5lpEw0uSyfiGs91B4Oqid8hWZ7y3FbytxrrkFGXWLpujWbohf9Y22o3jjrLvZ-GkVSMrM1xxiM4dYbZ5_xPk25hSLNmVlrel-BQtgFPQVaFLsDHbMQgljE4W6YI20lVKS2wggH3Tq_X0gk4d8MmUcDR18_ycK5N5__CbvK4WMtiUQesAozVMtP7-wfvY8T1j9ONB7AE2BnwV5iEN92PGl9qlQ2o5VjmnS9uMh7IETMpU0kAIcYp15oznTLIqAyNRG-ijN6FAtYBaFxI2E9PynqF7qDaGBC4fFLKeLt_lhxxhr21QAblQChgCAjimHey8WuHamtmOq48zc2IUZ5lGfVVGsXcO5H1ruMLYNi9B638p6yRNphK2_fvmEsh9Rj7fjR2JyVTTA.ZoWYMUCn0uG9iLYI0Zhtfg","apiUrl":"http://atmail.ms/api/jmap","eventSourceUrl":"http://atmail.ms/event","uploadUrl":"http://atmail.ms/api/upload","downloadUrl":"http://atmail.ms/api/download?blobId={blobId}&name={name}&accountId={accountId}","registerUrl":"http://atmail.ms/api/register","mustChangePassword":false}"

Token creation

Once you have the response from apiserver auth stage 2 you will need to base64 encode the JSON string that was returned. This will be used as a login token by webmail.

Sample token (base64 encoded auth stage 2 JSON response):

eyJ1c2VybmFtZSI6ImR1ZGUyQGF0bWFpbC5tcyIsInZlcnNpb25zIjpbMC4xXSwiZXh0ZW5zaW9ucyI6eyJjb20uYXRtYWlsLmFjY291bnRzIjpbMV0sImNvbS5hdG1haWwuY2FsZW5kYXIiOlsxXSwiY29tLmF0bWFpbC5jYWxlbmRhcmFjbCI6WzFdLCJjb20uYXRtYWlsLmZpbGVzdG9yZSI6WzFdLCJjb20uYXRtYWlsLmdhbCI6WzFdLCJjb20uYXRtYWlsLmljcyI6WzFdLCJjb20uYXRtYWlsLmxpY2Vuc2UiOlsxXSwiY29tLmF0bWFpbC5tYWlsYm94dXBkYXRlIjpbMV0sImNvbS5hdG1haWwubWVzc2FnZWNvcHkiOlsxXSwiY29tLmF0bWFpbC5ub29wIjpbMV0sImNvbS5hdG1haWwubm90aHJlYWR1cGRhdGVzIjpbMV0sImNvbS5hdG1haWwucGFydGNvbW1pdCI6WzFdLCJjb20uYXRtYWlsLnRhc2siOlsxXX0sImFjY2Vzc1Rva2VuIjoiZXlKaGJHY2lPaUpCTWpVMlMxY2lMQ0psYm1NaU9pSkJNalUyUjBOTkluMC5Pa0hOc1puQTRnTGhYWFlrODItN2hSSTJJZHExWktNbEpnQVNzSjlLR1pSWXAzeldnMXBsTVEuQnRNODYydUNPLWJkbjNJVi5GR1BTOGVMYkdWejJaRDF2NXF6OTdYQzNxVVIzdVh2SXVZdVNWcFBLRTc5enJFOFl1RTVSTVdhSlpuWVR1a2xmYmlKQzh5bkNWNmQxRjVscEV3MHVTeWZpR3M5MUI0T3FpZDhoV1o3eTNGYnl0eHJya0ZHWFdMcHVqV2JvaGY5WTIybzNqanJMdlotR2tWU01yTTF4eGlNNGRZYlo1X3hQazI1aFNMTm1WbHJlbC1CUXRnRlBRVmFGTHNESGJNUWdsakU0VzZZSTIwbFZLUzJ3Z2dIM1RxX1gwZ2s0ZDhNbVVjRFIxOF95Y0s1TjVfX0Nidks0V010aVVRZXNBb3pWTXRQNy13ZnZZOFQxajlPTkI3QUUyQm53VjVpRU45MlBHbDlxbFEybzVWam1uUzl1TWg3SUVUTXBVMGtBSWNZcDE1b3puVExJcUF5TlJHLWlqTjZGQXRZQmFGeEkyRTlQeW5xRjdxRGFHQkM0ZkZMS2VMdF9saHh4aHIyMVFBYmxRQ2hnQ0FqaW1IZXk4V3VIYW10bU9xNDh6YzJJVVo1bEdmVlZHc1hjTzVIMXJ1TUxZTmk5QjYzOHA2eVJOcGhLMl9mdm1Fc2g5Umo3ZmpSMkp5VlRUQS5ab1dZTVVDbjB1RzlpTFlJMFpodGZnIiwiYXBpVXJsIjoiaHR0cDovL2F0bWFpbC5tcy9hcGkvam1hcCIsImV2ZW50U291cmNlVXJsIjoiaHR0cDovL2F0bWFpbC5tcy9ldmVudCIsInVwbG9hZFVybCI6Imh0dHA6Ly9hdG1haWwubXMvYXBpL3VwbG9hZCIsImRvd25sb2FkVXJsIjoiaHR0cDovL2F0bWFpbC5tcy9hcGkvZG93bmxvYWQ/YmxvYklkPXtibG9iSWR9Jm5hbWU9e25hbWV9JmFjY291bnRJZD17YWNjb3VudElkfSIsInJlZ2lzdGVyVXJsIjoiaHR0cDovL2F0bWFpbC5tcy9hcGkvcmVnaXN0ZXIiLCJtdXN0Q2hhbmdlUGFzc3dvcmQiOmZhbHNlfQ==

Redirect

Using the base64 encoded “token” created above, you can now redirect the user to a URL that will log them into webmail automatically:

https://webmail.example.com/login?redirectTo=/app/mail&lt=[token]

Where [token] is the base64 encoded token that was created from the apiserver auth stage 2 response.

Sample URL:

https://webmail.example.com/login?redirectTo=/app/mail&lt=eyJ1c2VybmFtZSI6ImR1ZGUyQGF0bWFpbC5tcyIsInZlcnNpb25zIjpbMC4xXSwiZXh0ZW5zaW9ucyI6eyJjb20uYXRtYWlsLmFjY291bnRzIjpbMV0sImNvbS5hdG1haWwuY2FsZW5kYXIiOlsxXSwiY29tLmF0bWFpbC5jYWxlbmRhcmFjbCI6WzFdLCJjb20uYXRtYWlsLmZpbGVzdG9yZSI6WzFdLCJjb20uYXRtYWlsLmdhbCI6WzFdLCJjb20uYXRtYWlsLmljcyI6WzFdLCJjb20uYXRtYWlsLmxpY2Vuc2UiOlsxXSwiY29tLmF0bWFpbC5tYWlsYm94dXBkYXRlIjpbMV0sImNvbS5hdG1haWwubWVzc2FnZWNvcHkiOlsxXSwiY29tLmF0bWFpbC5ub29wIjpbMV0sImNvbS5hdG1haWwubm90aHJlYWR1cGRhdGVzIjpbMV0sImNvbS5hdG1haWwucGFydGNvbW1pdCI6WzFdLCJjb20uYXRtYWlsLnRhc2siOlsxXX0sImFjY2Vzc1Rva2VuIjoiZXlKaGJHY2lPaUpCTWpVMlMxY2lMQ0psYm1NaU9pSkJNalUyUjBOTkluMC5Pa0hOc1puQTRnTGhYWFlrODItN2hSSTJJZHExWktNbEpnQVNzSjlLR1pSWXAzeldnMXBsTVEuQnRNODYydUNPLWJkbjNJVi5GR1BTOGVMYkdWejJaRDF2NXF6OTdYQzNxVVIzdVh2SXVZdVNWcFBLRTc5enJFOFl1RTVSTVdhSlpuWVR1a2xmYmlKQzh5bkNWNmQxRjVscEV3MHVTeWZpR3M5MUI0T3FpZDhoV1o3eTNGYnl0eHJya0ZHWFdMcHVqV2JvaGY5WTIybzNqanJMdlotR2tWU01yTTF4eGlNNGRZYlo1X3hQazI1aFNMTm1WbHJlbC1CUXRnRlBRVmFGTHNESGJNUWdsakU0VzZZSTIwbFZLUzJ3Z2dIM1RxX1gwZ2s0ZDhNbVVjRFIxOF95Y0s1TjVfX0Nidks0V010aVVRZXNBb3pWTXRQNy13ZnZZOFQxajlPTkI3QUUyQm53VjVpRU45MlBHbDlxbFEybzVWam1uUzl1TWg3SUVUTXBVMGtBSWNZcDE1b3puVExJcUF5TlJHLWlqTjZGQXRZQmFGeEkyRTlQeW5xRjdxRGFHQkM0ZkZMS2VMdF9saHh4aHIyMVFBYmxRQ2hnQ0FqaW1IZXk4V3VIYW10bU9xNDh6YzJJVVo1bEdmVlZHc1hjTzVIMXJ1TUxZTmk5QjYzOHA2eVJOcGhLMl9mdm1Fc2g5Umo3ZmpSMkp5VlRUQS5ab1dZTVVDbjB1RzlpTFlJMFpodGZnIiwiYXBpVXJsIjoiaHR0cDovL2F0bWFpbC5tcy9hcGkvam1hcCIsImV2ZW50U291cmNlVXJsIjoiaHR0cDovL2F0bWFpbC5tcy9ldmVudCIsInVwbG9hZFVybCI6Imh0dHA6Ly9hdG1haWwubXMvYXBpL3VwbG9hZCIsImRvd25sb2FkVXJsIjoiaHR0cDovL2F0bWFpbC5tcy9hcGkvZG93bmxvYWQ/YmxvYklkPXtibG9iSWR9Jm5hbWU9e25hbWV9JmFjY291bnRJZD17YWNjb3VudElkfSIsInJlZ2lzdGVyVXJsIjoiaHR0cDovL2F0bWFpbC5tcy9hcGkvcmVnaXN0ZXIiLCJtdXN0Q2hhbmdlUGFzc3dvcmQiOmZhbHNlfQ==

Considerations

While this link could be created when the user logs into the portal and presented on the page as a static link this is not recommended as the embedded access token will expire after a time and the webmail login will fail. It is recommended that the URL is created dynamically at the time of click and then redirect the user to it so as to ensure that the embedded access token is valid when webmail is requested.

Comments


Contact our support team


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