Creating Access Tokens Using a Custom Integration
Creating Access Tokens for DataTrails
Non-interactive access to the DataTrails platform is managed by creating Integrations
with either a Custom Integration or one of the built-in Integrations. This is done using either the Settings
Menu in the DataTrails UI or by using the App Registrations API directly.
Note: App Registration is the previous name for an Integration.
Integrations
have a CLIENT_ID
and SECRET
used to authenticate with DataTrails IAM endpoints using
JSON Web Tokens (JWT).
DataTrails authentication uses the industry-standard OIDC Client Credentials Flow.
Creating a Custom Integration
If you have already saved a CLIENT_ID
and SECRET
, with
permissions applied, skip to
Getting a Token With the Custom Integration
Note: Creating App Registrations requires Administrator privileges.
IfSettings
does not appear in the navigation, see your DataTrails Administrator for access.
Using the DataTrails App to Create an Integration (First-Time Setup)
- As an Administrator, open the DataTrails App
- Navigate to
Settings
on the sidebar - Navigate to the
Integrations
tabNavigate to Settings, then Integration - Click the
Custom
box to create a Custom Integration - Enter any
Display Name
you’d likeCompleted Web Registration Optionally add anyCustom claims
at this step by clicking the+ Add
button. Ensure theName
does not start withjit_
(DataTrails reserved names) or use any other well-known reserved claims. - Once complete, click
Confirm
to complete the custom integration - You will then be presented with the
CLIENT_ID
andSECRET
required by the archivist token endpointRecord your Client ID and Secret Caution: Save theCLIENT_ID
andSECRET
to a password manager or secret management service as theSECRET
can not be viewed again. A newSECRET
can be regenerated by editing the Integration, invalidating the previousSECRET
.
Grant Permissions to Custom Integration
Integrations are secured by default, with no permissions within DataTrails. Create and assign an Access Policy to create and read DataTrails information.
- Navigate to
Access Policies
on the sidebarAccess Policies - Click
CREATE POLICY
, setting theName
andAsset Types
=*
for all typesAsset types can be filtered as needed. List existingAsset Types
by typing at least two characters of a known typeCreate Access Policy Form - Click
Permissions
to set a scope for the policy - Set Actors to the
USER_ID
of the Custom IntegrationUser
Subject Identifier
- Paste the
CLIENT_ID
from the previous stepFilter on User by Subject Identifier using the CLIENT_ID
- Set Attribute Access and Event Visibility to
All
Each policy can be configured with multiple access rightsSet Attribute Access and Event Visibility - Click the
ADD PERMISSION GROUP
for this policy - Click the
CREATE POLICY
to complete the creation of this policy
Getting a Token With the Custom Integration
Having completed the steps at
Creating a Custom Integration, and having taken note of the CLIENT_ID
and the SECRET
, a token can be obtained with the following command.
Save the
CLIENT_ID
andSECRET
saved from above, to local variablesYou can regenerate the secret, which will invalidate any previous usageCLIENT_ID=your_id SECRET=your_secret
Generate a token using your pre-existing
Custom Integration
details, saving to aRESPONSE
variableRESPONSE=$(curl https://app.datatrails.ai/archivist/iam/v1/appidp/token \ --data-urlencode "grant_type=client_credentials" \ --data-urlencode "client_id=${CLIENT_ID}" \ --data-urlencode "client_secret=${SECRET}") echo $RESPONSE
Save the base64 encoded
JWT
usingjq
to find.access_token
(See ./jq for more info)TOKEN=$(echo -n $RESPONSE | jq -r .access_token) echo $TOKEN
Create a Bearer Token file for reference by
curl
commands, in an./datatrails/
directorymkdir -p $HOME/.datatrails chmod 0700 $HOME/.datatrails echo Authorization: Bearer $TOKEN > $HOME/.datatrails/bearer-token.txt cat $HOME/.datatrails/bearer-token.txt
Testing Token Creation
You can test access to the DataTrails API using any of the standard API calls. GETing Assets
is a simple test.
If successful, you will see a list of the assets the Integration has access to in the tenancy.
Note this may be an empty response if no assets are being shared with the user; this is an expected secure by default behavior.
Otherwise, check the Assets OpenAPI Reference for more detailed information on the response codes you may expect if authentication fails and what they mean.
View Existing Assets
To test the creation of the Custom integration and the configuration of the bearer token file (bearer-token.txt
), query the assets API
curl -X GET -H "@$HOME/.datatrails/bearer-token.txt" \
https://app.datatrails.ai/archivist/v2/assets | jq
If you have existing assets, the output will be similar to:
{
"assets": [
{
"identity": "assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"behaviours": [
"AssetCreator",
"RecordEvidence",
"Builtin"
],
"attributes": {
"length": "40'",
"weight": "20000-lbs",
"width": "8'",
"arc_description": "A shipping container being tracked",
"arc_display_name": "New Shipping Container #1",
"arc_display_type": "Shipping Container",
"arc_home_location_identity": "locations/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"height": "8'"
},
"confirmation_status": "CONFIRMED",
"tracked": "TRACKED",
"owner": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"at_time": "2023-09-22T03:39:46Z",
"storage_integrity": "TENANT_STORAGE",
"proof_mechanism": "SIMPLE_HASH",
"chain_id": "8275868384",
"public": false,
"tenant_identity": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
],
"next_page_token": ""
}
If the output is an empty structure, you may either not have any assets, or misconfigured the Access Policy.
{
"assets": [],
"next_page_token": ""
}
In the DataTrails App, Navigate to Assets
confirm existing assets. If assets exist, confirm the CLIENT_ID
, SECRET
and Access Policy
are configured and referenced properly.
Troubleshooting Token Generation
The header and payload of the TOKEN
may be examined with the following commands. This is useful when investigating if tokens contain the correct custom claims or tokens that may appear malformed.
Warning: Decoding tokens with an online service exposes details about your DataTrails until you delete the test secret.
View the Header
echo -n $TOKEN | cut -d '.' -f 1 | base64 -d | jq
Generates output similar to:
{ "alg": "RS256", "typ": "at+jwt", "kid": "devidp" }
View the Payload
echo -n $TOKEN | cut -d '.' -f 2 | base64 -d | jq
Generates output similar to:
{ "jit_tenant_id": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name": "my-token", "jit_tier": "FREE", "jti": "CCIH_QsZsM6FKzwBR6L5Z", "sub": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "iat": 1695254038, "exp": 1695257698, "client_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "iss": "https://app.datatrails.ai/appidpv1", "aud": "https://app.datatrails.ai/archivist" }