Configuring App Registrations for Non-Interactive Use

Creating App Registrations for RKVST

Non-interactive access to the RKVST platform is managed by creating Applications with App Registrations, using either the Manage RKVST Menu in the UI or by using the App Registrations API directly.

Applications have a CLIENT_ID and SECRET that can then be used to authenticate to RKVST IAM Endpoints to issue a token (JWT) for accessing the rest of the RKVST API.

This authentication flow uses the industry-standard OIDC ‘Client Credentials’ Flow.

Creating an App Registration

Warning: You may only create and manage App Registrations with a Root User.

When enabling non-interactive access to RKVST, you must create your first App Registration in the RKVST UI.

Using the RKVST UI (Required for First-Time Setup)

  1. As a Root User open the Manage RKVST Interface
Manage RKVST
  1. Navigate to the APP REGISTRATIONS tab
Navigate to APP REGISTRATIONS
  1. Click CREATE APP REGISTRATION and the following form should appear:
App Registration Webform
  1. Enter any display name you like and then click CREATE APP REGISTRATION.
You can optionally add any Custom Claims at this step, you must ensure they do not start with jit_ or use of the well-known reserved claims.
Completed Web Registration
  1. You will then be presented with the CLIENT_ID and SECRET required by the archivist token endpoint.
Caution: You must take note of the SECRET at this point - it can not be viewed again later.
Record your Client ID and Secret
  1. Now you have created your App Registration, follow the steps further below to test generating a token and ensure you can access the RKVST API.
Note: By default, newly created Applications will always have a Non-Root User permission to the API, you must add the Application as a Root User to elevate it’s permissions.

Using the App Registrations API

The following assumes you have at least one App Registration that has already been configured with Root User permissions and that you are comfortable generating tokens and using the RKVST API.

If you do not yet have an App Registration configured please follow the first-time setup guide to get started.

  1. Define your new Application JSON and save it to a file locally. e.g.
{
    "display_name": "TrafficLight101",
    "custom_claims": {
      "serial_number": "TL1000000101",
      "has_cyclist_light": "true"
    }
}
  1. Generate a token using your pre-existing App Registration details
curl https://app.rkvst.io/archivist/iam/v1/appidp/token \
    --data-urlencode "grant_type=client_credentials" \
    --data-urlencode "client_id=${CLIENT_ID}" \
    --data-urlencode "client_secret=${SECRET}"

The token is found in the .access_token field and it is a base64 encoded JSON Web Token.

A common method to extract the token is to use jq, where $RESPONSE is the output your curl command:

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

You should then save the token to a local bearer_token file with 0600 permissions in the following format:

Authorization: Bearer $TOKEN

Where $TOKEN is the extracted token value.

  1. Submit your new Application JSON to the App Registration API Endpoint
curl -X POST \
     -H "@BEARER_TOKEN_FILE" \
     -H "Content-Type: application/json" \
     -d "@/path/to/jsonfile" \
     https://app.rkvst.io/archivist/iam/v1/applications

You should see a response with details about the App Registration’s CLIENT_ID and SECRET:

{
    "identity": "applications/d1fb6c87-faa9-4d56-b2fd-a5b70a9af065",
    "display_name": "TrafficLight101",
    "client_id": "d1fb6c87-faa9-4d56-b2fd-a5b70a9af065",
    "tenant_id": "tenant/53e6bed7-6f4c-4a37-8c4f-cf889f2b1aa6",
    "credentials": [
        {
            "secret":"a0c09972b6ac912a4d67815fef88093c81a99b49977d35ecf6d162631aa29173",
            "valid_from": "2021-09-21T16:43:19Z",
            "valid_until": "2022-09-21T16:43:19Z"
        }
    ],
    "custom_claims": {
        "serial_number": "TL1000000101",
        "has_cyclist_light": "true"
    }
}
Caution: You must take note of the SECRET at this point - it can not be viewed again later.
  1. You should now have a newly configured App Registration and have recorded its CLIENT_ID and its SECRET so that it can be used to generate a token and access the RKVST API.

For further details on using this API check out our App Registrations API Reference which not only contains more detailed usage examples but also has the full OpenAPI Reference.

Getting a Token With Your App Registration

Having completed the steps at Creating an App Registration, and having taken note of the CLIENT_ID and the SECRET, a token can be obtained with the following command.

Replace ${CLIENT_ID} with the application id, and ${SECRET} with your secret from the application registration.

curl https://app.rkvst.io/archivist/iam/v1/appidp/token \
    --data-urlencode "grant_type=client_credentials" \
    --data-urlencode "client_id=${CLIENT_ID}" \
    --data-urlencode "client_secret=${SECRET}"

The token is found in the .access_token field and it is a base64 encoded JSON Web Token.

A common method to extract the token is to use jq, where $RESPONSE is the output returned from your curl command:

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

You should then save the token to a local bearer_token file with 0600 permissions in the following format:

Authorization: Bearer $TOKEN

Where $TOKEN is the extracted token value.

Testing Your Access

You can test access to the RKVST API using any of our standard calls, doing a GET Assets is a very simple test.

For example:

curl -v -X GET \
     -H "@$BEARER_TOKEN_FILE" \
     https://app.rkvst.io/archivist/v2/assets

If successful you should then see a list of the assets your Application has access to in the tenancy, note this may be an empty response if no assets are being shared with that user, this is an expected behaviour.

Otherwise, check the Assets OpenAPI Reference for more detailed information on the response codes you may expect if authentication fails and what they mean.

Troubleshooting Token Generation

The header and payload of the TOKEN may be examined with the following commands:

# Header
echo -n $TOKEN | cut -d '.' -f 1 | base64 -D

# Payload
echo -n $TOKEN | cut -d '.' -f 2 | base64 -D

This is useful when investigating tokens contain the correct custom claims or tokens that may appear malformed.

Note: Decoding tokens with an online service exposes details about your RKVST until you delete the test secret.

Edit this page on GitHub