Authentication

In order to access the Vessel Insight (VI) APIs the requests must be authenticated. VI APIs uses OpenID Connect and OAuth 2.0 protocols for authentication. Users must obtain access token from the authentication server and attach it as HTTP header when making requests to an API. In case of missing or invalid access token the server issues response with HTTP code 401 (Unauthorized).

Authentication servers

VI supports any standard OpenID Connect authentication server, Azure Active Directory (AAD) is one of them.

In this case VI APIs relies on each customer having its own Azure AD with registered users and application registrations (clients).

Grant types

The VI APIs uses the standard OAuth 2.0 grant types (authentication flows) as well as one custom flow. Here are the most common use cases:  

Client credentials (https://tools.ietf.org/html/rfc6749#section-4.4) - used for API->API communication; in this case the "calling" API acts as "client", obtains access token using its client ID and secret and makes requests to other APIs using the access token.

Client credentials grant flow diagram

Sample HTTP POST Request:

curl -X POST -d "grant_type=client_credentials&client_id=[APP_ID]&client_secret=[APP_SECRET]&resource=[RESOURCEID]"URL-> https://login.microsoftonline.com/<Tenant_id>/oauth2/token

Service-to-service access token request contains the following parameters:

Parameter                         Description

grant_type          required      Specifies the requested response type. 
                                  In a Client Credentials Grant flow, the value must be client_credentials.

client_id           required      Specifies the Azure AD client id of the calling web service. To find the calling application's 
                                  client ID, in the Azure portal, click Azure Active Director, click App registrations, click the 
                                  application. The client_id is the Application ID

client_secret       required      Enter a key registered for the calling web service or daemon application in Azure AD. To create a key,
                                  in the Azure portal, click Azure Active Directory, click App registrations, click the application,
                                  click Settings, click Keys, and add a Key. URL-encode this secret when providing it.

resource            required      Enter the App ID URI of the receiving web service. To find the App ID URI, in the Azure portal, 
                                  click Azure Active Directory, click App registrations, click the service application, and then
                                  click Settings and Properties.

Example of Request

curl -X POST -d "grant_type=client_credentials&client_id=[APP_ID]&client_secret=[APP_SECRET]&resource=[RESOURCEID]"https://login.microsoftonline.com/<Tenant_id>/oauth2/token

Example of Response

{
   "token_type": "Bearer",
   "expires_in": "3199",
   "ext_expires_in": "3599",
   "expires_on": "1581664717",
   "not_before": "1581661217",
   "resource": "be441a98-a4k3-497b-de69-0sbc60dr31b4",
   "access_token": "eyJ0eXGiOiJKV1QiLCpekAx8Wf.."         
}