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
Region | Production | IdP Endpoint |
---|---|---|
TEST | No | https://tst.id-au.telematics.com |
QA | No | https://qa.id-au.telematics.com |
STAGING | No | https://stg.id-au.telematics.com |
AU | Yes | https://id-au.telematics.com |
NZ | Yes | https://id-nz.telematics.com |
US | Yes | https://id-us.telematics.com |
UK | Yes | https://id-uk.telematics.com |
MX | Yes | https://id-mx.telematics.com |
LATAM | Yes | https://id-latam.telematics.com |
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
Info
These 2 steps are required until we transition our underlying API infrastructure to natively support the OpenID Connect JWT token, which is a work in progress.