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.
If Settings does not appear in the navigation, see your DataTrails Administrator for access.

Using the DataTrails App to Create an Integration (First-Time Setup)#

1. As an Administrator, open the DataTrails App
2. Navigate to Settings on the sidebar
3. Navigate to the Integrations tab
   
4. Click the Custom box to create a Custom Integration
5. Enter any Display Name you’d like
   

   Optionally add any Custom claims at this step by clicking the + Add button. Ensure the Name does not start with jit_ (DataTrails reserved names) or use any other well-known reserved claims.

6. Once complete, click Confirm to complete the custom integration
7. You will then be presented with the CLIENT_ID and SECRET required by the archivist token endpoint
   

   Caution: Save the CLIENT_ID and SECRET to a password manager or secret management service as the SECRET can not be viewed again. A new SECRET can be regenerated by editing the Integration, invalidating the previous SECRET.

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.

1. Navigate to Access Policies on the sidebar
   
2. Click CREATE POLICY, setting the Name and Asset Types=* for all types

   Asset types can be filtered as needed. List existing Asset Types by typing at least two characters of a known type

   
3. Click Permissions to set a scope for the policy
4. Set Actors to the USER_ID of the Custom Integration
   • User
   • Subject Identifier
   • Paste the CLIENT_ID from the previous step
     
5. Set Attribute Access and Event Visibility to All

   Each policy can be configured with multiple access rights

   
6. Click the ADD PERMISSION GROUP for this policy
7. 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.

1. Save the CLIENT_ID and SECRET saved from above, to local variables

   You can regenerate the secret, which will invalidate any previous usage

   CLIENT_ID=your_id
   SECRET=your_secret
   

2. Generate a token using your pre-existing Custom Integration details, saving to a RESPONSE variable

   RESPONSE=$(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
   

3. Save the base64 encoded JWT using jq to find .access_token (See ./jq for more info)

   TOKEN=$(echo -n $RESPONSE | jq -r .access_token)
   echo $TOKEN
   

4. Create a Bearer Token file for reference by curl commands, in an ./datatrails/ directory

   mkdir -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.

1. View the Header

   echo -n $TOKEN | cut -d '.' -f 1 | base64 -d | jq
   

   Generates output similar to:

   {
     "alg": "RS256",
     "typ": "at+jwt",
     "kid": "devidp"
   }
   

2. 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"
   }