Getting Access Tokens using App Registrations
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 manageApp 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 to create an App Registration (First-Time Setup)
- As a Root User open the
Manage RKVST
Interface
- Navigate to the
APP REGISTRATIONS
tab
- Click
CREATE APP REGISTRATION
and the following form should appear:
- 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 withjit_
or use of the well-known reserved claims.
- You will then be presented with the
CLIENT_ID
andSECRET
required by the archivist token endpoint.
Caution: You must take note of theSECRET
at this point - it can not be viewed again later.
- 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.
You can add an App Registration as a Root User using the
Manage RKVST
screen, where the issuer will behttps://app.rkvst.io/appidpv1
and the subject will be your App Registration’sCLIENT_ID
.
Using the App Registrations API to create an App Registration
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.
- 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"
}
}
- 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.
- 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 theSECRET
at this point - it can not be viewed again later.
- You should now have a newly configured App Registration and have recorded its
CLIENT_ID
and itsSECRET
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.