External authentication

Handle authentication on your own website or in your own software and redirect an authenticated user to QwykPortals.

Goal

QwykPortals provides a built in landing page where you can direct users and from which they can login. However external applications can handle authentication themselves and redirect an authenticated user to QwykPortals so to provide a more fluent experience. In this guide we'll explain how to set this up.

What you'll need

1. The hostname of our production server {SERVER_ADDRESS}

2. The address at which your portal is hosted. {PORTAL_ADDRESS}

3. Your Organization ID and the Site ID you want to authenticate the user for. {ORGANIZATION_ID} {SITE_ID} (both integers, not strings)

4. The user's email address and password {EMAIL_ADDRESS} {PASSWORD}

5. A server to handle the API requests on, OR contact Qwyk about setting up Cross-Origin Resource Sharing.

All of these can be obtained by sending a message to [email protected] if you don't already have them.

Workflow

The workflow is relatively simple. We'll obtain an access token from the server by authenticating the user with their credentials. With this access token we can then redirect the user to our QwykPortals site. When we send the user to a correctly formatted URL and pass a valid token, QwykPortals will take care of authenticating them from the server and establish a session in their browser.

We strongly recommend that you execute all authentication requests from your servers and not on the client-side. Without additional configuration client-side requests will fail until CORS has been setup.

Obtain an access_token by sending an login request to the server.

Pass the user's credentials to the Qwyk API server to obtain an access_token with which the user to redirect.

HTTP

POST /api/portals/auth/login HTTP/1.1
Host: https://{SERVER_ADDRESS}
Accept: application/json
Content-Type: application/json

{
  "email": "{EMAIL_ADDRESS}",
  "password": "{PASSWORD}",
  "organization_id": {ORGANIZATION_ID},
  "site_id": {SITE_ID}
}

Bash

curl --location --request POST 'https://{SERVER_ADDRESS}/api/portals/auth/login' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
	"email": "{EMAIL_ADDRESS}",
	"password": "{PASSWORD}",
	"organization_id": {ORGANIZATION_ID},
	"site_id": {SITE_ID}
}'

NodeJs - Request

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://{SERVER_ADDRESS}/api/portals/auth/login',
  'headers': {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({"email":"{EMAIL_ADDRESS}","organization_id":{ORGANIZATION_ID},"password":"{PASSWORD}","site_id":{SITE_ID}})

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Python - Requests

import requests

url = "https://{SERVER_ADDRESS}/api/portals/auth/login"

payload = {
  "email": "{EMAIL_ADDRESS}",
  "password": "{PASSWORD}",
  "organization_id": {ORGANIZATION_ID},
  "site_id": {SITE_ID}
}

headers = {
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, json = payload)

print(response.text.encode('utf8'))

Response:

Http 200:

{
    "access_token": "[...]",
    "token_type": "bearer",
    "expires_in": 7200
}

Redirect the user to the portal with the access_token as a url query parameter.

With the response from the login request, we can then redirect the user to the Portal. In order to do this we'll format a URL and send the user there. The URL takes the following parameters.

• token (required)

• token_type defaults to bearer

• expires_in defaults to 7200

• destination defaults to /my-portal

Token, token_type and expires_in can all be copied from the response body. Destination is the path within the portal where the user will be sent after their session has successfully been established.

A correctly formatted URL follow this schema:

https://{PORTAL_ADDRESS}/auth/with-token?token={token}&token_type={token_type}&expires_in={expires_in}&destination={destination}

For example:

https://mydigitalfreight.next.qwykportals.com/auth/with-token?token=[...]&token_type=bearer&expires_in=7200&destination=/my-portal/quotations

If the request is well-formed and the token is valid, QwykPortals will establish their Session and redirect them to the specified destination.

Additional abilities

External Redirect: a home and logout redirect address can be configured in your Hub's Site settings to route the user back to the correct landing page, completely bypassing the built-in public homepage after they click the Home button within the site or when they logout.

Booking Wizard Integration: to establish an even more fluent workflow, you can start a quotation or booking workflow similar to from the built in homepage by parsing a destination formatted as follows:

"/my-portal/booking-wizard/cargo?transportMode=OCEAN&loadType=fcl&origin_type=port&origin_code=NLRTM&origin_locode=NLRTM&origin_name=Rotterdam,%20Netherlands&origin_country=NL&destination_type=port&destination_code=SGSIN&destination_locode=SGSIN&destination_name=Singapore,%20Singapore&destination_country=SG"

This will start the wizard at the cargo page with routing and product information prefilled from your own site.