Authentication

Overview

The TN360 API uses API keys to perform authentication for API access. Access controls are applied depending on the type of API key in use.

Obtaining an API key can be performed in multiple ways:

• Authenticating to the TN360 platform. The authentication response includes a User API key
• A Company API key may be provided upon request to the Integrations team. Note that this is not recommended for security reasons.
• An Integration API key generated for a nominated use case.

Typically an Integration API key is provided to service integration needs and is made available at the time of onboarding the integration partner.

If an integrator requires a User API key, then they must first authenticate as that user, and extract the User API key from the authentication response.

Authentication Flows

TN360 supports a legacy, direct (but now deprecated) authentication model via REST calls (see Authentication API). This may still be used to authenticate a user directly to the platform, but only where the TN360 platform is the user's Identity Manager.

For SSO authentication flows - where TN360 is integrated with an external, customer Identity Management Platform, you must use the OAuth/OpenID Connect authentication flow.

OAuth2.0 and OpenID Connect

OAuth 2.0 and OpenID Connect are modern standards-based authentication mechanisms to verify the identity of users.

TeletracNavman provide a regionally deployed, authentication service connected to the TN360 platform to service these authentication flows. Integration parties are encouraged to use this service when requiring the use of a TN360 user's authorisation context.

The auth flow additionally requires that the OpenID Connect token be exchanged for a TN360 user object - which will include the User API key. You will need to contact the integrations@teletracnavman.com to have a 'client_id' and 'client_secret' generated for your use with the TN360 Identity Provider.

The various regional Identity Management endpoints are listed below

Example

This example shows how to retrieve an OpenID Connect JWT token, and subsequently exchange it for a TN360 user object containing the User API key.

The default TN360 realm is TN360DB.

$ curl -d 'client_id={client_id}'  \
       -d 'client_secret={secret}' \
       -d 'username={username}'    \
       -d 'password={password}'    \
       -d 'grant_type=password'    \
    'https://tst.id-au.telematics.com/auth/realms/TN360DB/protocol/openid-connect/token'

{"access_token":"eyJhbGc...wczhg","expires_in":299,"refresh_expires_in":1800,
 "refresh_token":"eyJhbGc...ogoPRM","token_type":"Bearer","not-before-policy":0,
 "session_state":"bc4a7a40-045a-497a-bae5-2f0967ea7448","scope":"email profile"}

# now extract the 'access_token' and pass it using 'Bearer' authorization 
# to the '/v1/auth/sso' endpoint to exchange the OpenID Connect token for a 
# TN360 user object including the API key(s)

$ curl -H "Accept: application/json"             \
       -H "Authorization: Bearer eyJhbGc...KWJQ" \
       https://tst.api-au.telematics.com/v1/auth/sso
{
  "firstName": "Test",
  "lastName": "User",
  "companyId": 1,
  "id": 933,
  "isSiteAdmin": false,
  "email": "test.user@email.address.com",
  "username": "xyz123",
  "status": "E",
  "keys": [
    {
      "id": 12345,
      "label": "Test User",
      "accessToken": "c10621e3c69a4bff8e89e4af22cf0f01",
      "type": "USER"
    }
  ],
  "roles": [...user roles...],
  "timeZone": "Australia/Melbourne",
  "type": {
    "code": "USER"
  }
}

The returned user object contains the API key in the keys[].accessToken field. This key may be against the various API's - see API Reference