Onboarding App Instances
General Overview
The onboarding workflow is needed to onboard app instances and create endpoints in the agrirouter. The result of the onboarding process has to be stored.
Before any data flow can happen, the very first command sent by the endpoint has to be the Capabilities command. |
Workflow for Farming Software and Telemetry Systems
Telemetry systems and Farming Software need to assign their own userID to the accountID of the user at the agrirouter. Therefore, a verification should be performed before onboarding.
Workflow for CUs
The CU onboarding mechanism needs less steps than the Farming Software and Telemetry software, but it does not give any information on the account before onboarding is performed. The following parts of onboarding are not required for CU onboarding:
|
Workflow for Virtual CUs
Onboarding virtual CUs through a telemetry platform is done using a command. This is described in Cloud solution commands.
From the end user’s perspective, it is mostly dependent on the telemetry platform if there is any selection mechanism or if it is done automatically.
Creating a registration code
Using the agrirouter UI
The registration code for a new CU can be created by the end user clicking "Onboard Telemetry Unit" in agrirouter’s control center. He has to select the desired CU and gets a 10-digit code consisting of letters and numbers. A CU needs an interface to input this registration code.
As result of the authorization
If the authorization process is done using parameter response_type=onboard, the result will include a regcode. This regcode is a registration code.
Telemetry Platforms
A telemetry platform has to be onboarded using the authorization process. Once it is onboarded, it can onboard virtual CUs by itself. Therefore, it can use a special command. This is described in Cloud solution commands.
Collecting and setting up relevant information
The onboarding request requires several different information:
ApplicationID and X-Agrirouter-ApplicationID
Both IDs are the same, they can be found in the agrirouter software endpoint UI of the developers account:
CertificationVersionID
The CertificationVersionID is the ID unique to this specific app certification. It can be found when clicking on the required Endpoint Software Version:
Setting up private and public key
This step is not required for CUs |
As the requests need to be signed, the public key has to be stored within the agrirouter. This can be done, calling "Edit" on the Endpoint Software Management Screen. The agrirouter UI offers the possibility to create a key pair, you can however create your own one and just store the public key on agrirouter.
External Id
The external Id - to be seen in the Body Information of the onboarding request (only called id
there) - needs to be a URN, which fits to the definitions in the general conventions.
For farming software and telemetry platforms the external Id should be directly related to a user account in your platform. For privacy purposes, it would also be ok to hash or encrypt the user id so it is not visible to agrirouter.
Examples for valid external IDs are:
urn:myfarmingsoftware:[email protected] urn:mytelemetryplatform:userid-123 urn:fancyfarming:3e9156eb-efc1-4742-b820-ca3bf0eecdf0 urn:greattelemetry:kuQn0KfwEY0s0lT1fQIAWdqlaezuUHfLV/uNC0dvqKk=
onboarding Endpoint URLs
The endpoint URL differs, depending on your desired geolocation and the Quality Assurance or Productive Environment.
The request must be a HTTP Post request to the URL found here.
Like every URL in this document, these URLs might change in the future or there might be additional ones for new Areas. |
Signing requests
For onboarding, the agrirouter must be sure that the requests actually come from an instance of the app specified in the request. Therefore, the payload must be signed with the applications private key. The corresponding public key must be maintained by the developer in agrirouter per application, see above.
A Payload encryption is not needed since all communication is encrypted with TLS
All signatures used for the onboarding and revocation process shall be created by:
-
hashing the request body (SHA256)
-
then using the private key to create an RSA signature of the hash
-
Create HEX representation of this hash
-
Add the hex string as "X-Agrirouter-Signature" to the header of the HTTP call
agrirouter will look up the public key for the app id specified and verify the signature.
Verification Request
The verification request is used to actually check if the endpoint is for the desired application and account before actually onboarding it.
General
The address for the verification request is as follows:
Method | Address |
---|---|
POST |
api/v1.0/registration/onboard/verify |
Request Information
The app instance has to send a HTTP Post request.
Header Information
For Farming Software and Telemetry Platform onboarding
The Request shall include the following header information:
Name | Type | Description |
---|---|---|
Authorization |
String |
"Bearer "+ the registration code |
Content-Type |
String |
application/json |
X-Agrirouter-ApplicationId |
String |
[Application Id] |
X-Agrirouter-Signature |
[Signature] |
see Signing requests |
Body Information
The request body includes the same parameters as the onboarding requests body:
The request body is a JSON object including the following Parameters:
# | Name | Type | Description |
---|---|---|---|
1 |
id |
String |
The unique ID of the endpoint; we advise to create a URN |
2 |
applicationId |
String |
The application ID for the application, provided in the agrirouter developer UI |
3 |
certificationVersionId |
String |
The ID of the certification software version provided in the agrirouter developer UI |
4 |
gatewayId |
String |
The desired communication protocol after onboarding 2: MQTT 3: REST Example: "2" |
5 |
certificateType |
String |
Type of the desired certificate; Possible values: PEM,P12 |
6 |
UTCTimestamp |
String |
A Timestamp like this: 2018-06-20T07:29:23.457Z |
7 |
timeZone |
String |
A TimeZone like this: "+03:00" |
EXAMPLE
{
"id": "urn:myapp:snr00003234",
"applicationId": "e0eb00ff-e2ef-4429-85f5-2559aceedd6d",
"certificationVersionId": "e0eb00ff-e2ef-4429-85f5-2559aceedd6d",
"gatewayId": "3",
"UTCTimestamp": "2018-06-04T12:00:03.000Z",
"timeZone": "+02:00"
}
Verification Result
The result is a HTTP response code with a JSON object in the Body
Result codes
There are different result HTTP Status codes indicating the result
Code | Description |
---|---|
200 |
The validation was successful |
400 |
There was an error in the request |
401 |
The request was unauthorized; the provided registration code was unknown |
Body Information
Success
For a successful result, the body will include a JSON object like this:
{
"accountId": "4823443c-fd0d-44a7-81a6-06104455945a"
}
It includes the accountId, so that an app provider can check if this accountId might already be known. For apps that can be onboarded only once (like an FMIS, where it doesn’t make any sense to have 2 of the same kind), this would mean that onboarding is not needed.
Failure
In case of Failure, an error message is provided. Possible ErrorMessages can be found here.
Onboarding Request
To onboard a new endpoint, the endpoint has to send an onboarding request providing the registration code to agrirouter.
The request is a HTTP POST request.
There is no MQTT onboarding mechanism, so onboarding always has to be done using REST. |
Request information for signed onboarding
This is the onboarding request for Farming Software and Telemetry platforms, not for CUs. |
General
The address for the onboarding request is as follows:
Method | Address |
---|---|
POST |
api/v1.0/registration/onboard/request |
Header Information
For Farming Software and Telemetry Platform onboarding
The Request shall include the following header information:
Name | Type | Description |
---|---|---|
Authorization |
String |
"Bearer "+ the registration code Remark: There is a space between bearer and registration code! |
Content-Type |
String |
application/json |
X-Agrirouter-ApplicationId |
String |
[Application Id] |
X-Agrirouter-Signature |
[Signature] |
The signature, see Signing requests |
Body Information
The request body is a JSON object including the following Parameters:
# | Name | Type | Description |
---|---|---|---|
1 |
id |
String |
The unique and persistent ID of the endpoint; we advise to create a URN |
2 |
applicationId |
String |
The application ID for the application, provided in the agrirouter developer UI |
3 |
certificationVersionId |
String |
The ID of the certification software version provided in the agrirouter developer UI |
4 |
gatewayId |
String |
The desired communication protocol after onboarding 2: MQTT 3: REST Example: "2" |
5 |
certificateType |
String |
Type of the desired certificate; Possible values: PEM,P12 |
6 |
UTCTimestamp |
String |
A Timestamp like this: 2018-06-20T07:29:23.457Z |
7 |
timeZone |
String |
A TimeZone like this: "+03:00" |
{
"id": "mydeviceid",
"applicationId": "e0eb00ff-e2ef-4429-85f5-2559aceedd6d",
"certificationVersionId": "e0eb00ff-e2ef-4429-85f5-2559aceedd6d",
"gatewayId": "3",
"UTCTimestamp": "2018-06-04T12:00:03.000Z",
"timeZone": "+02:00"
}
Request information for CU onboarding
This is the onboarding request for CUs. |
General
The address for the onboarding request is as follows:
Method | Address |
---|---|
POST |
api/v1.0/registration/onboard |
Header Information
The Request shall include the following header information:
Name | Type | Description |
---|---|---|
Authorization |
String |
"Bearer "+ the registration code |
Content-Type |
String |
application/json |
Body Information
The request body is a JSON object including the following Parameters:
# | Name | Type | Description |
---|---|---|---|
1 |
id |
String |
The unique and persistent ID of the endpoint; we advise to create a URN |
2 |
applicationId |
String |
The application ID for the application, provided in the agrirouter developer UI |
3 |
certificationVersionId |
String |
The ID of the certification software version provided in the agrirouter developer UI |
4 |
gatewayId |
String |
The desired communication protocol after onboarding 2: MQTT 3: REST Example: "2" |
5 |
certificateType |
String |
Type of the desired certificate; Possible values: PEM,P12 |
Example:
{
"id": "mydeviceid",
"applicationId": "e0eb00ff-e2ef-4429-85f5-2559aceedd6d",
"certificationVersionId": "e0eb00ff-e2ef-4429-85f5-2559aceedd6d",
"gatewayId": "3",
}
Response
Response code
The request has several possible response codes indicating Success or Failure:
Code | Possible problem |
---|---|
201 |
Success; Analyse onboarding result to get started |
400 |
The Request was invalid |
401 |
Unauthorized; meaning that one of the given header parameters is wrong. Refer to the error message |
Success
On success, the HTTP response code will be 201.
The result is a json object including the information required for onboarding.
# | Name | Type | Description |
---|---|---|---|
1 |
authentication |
Object |
Includes all authentication information |
1.1 |
certificate |
String |
The certificate required for communication; Public AND Private Key |
1.2 |
secret |
String |
The passkey for the certificate |
1.3 |
type |
String |
Type of Certificate; PEM or P12 (short for PKCS#12) |
2 |
capabilityAlternateId |
String |
A value that just has to be saved and sent in several scenarios |
3 |
connectionCriteria |
Object |
Includes all information required for further communication |
3.1 |
gatewayId |
String |
Assigned gateway; 2= MQTT, 3=REST |
3.2 |
host |
String |
MQTT only: The broker address |
3.3 |
port |
Integer |
MQTT only: The broker port |
3.4 |
measures |
String |
Endpoint URL of the inbox or Topic, when using MQTT |
3.5 |
commands |
String |
Endpoint URL of the outbox or Topic, when using MQTT |
3.6 |
clientId |
String |
MQTT only: The ClientID of the endpoint |
4 |
deviceAlternateId |
String |
The device ID used to mark the source of a message from this device and as endpointId |
5 |
sensorAlternateId |
String |
The deviceID used to mark the source of the communication from this device |
Example for onboarding an REST endpoint:
{
"authentication": {
"certificate": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n...\n-----END ENCRYPTED PRIVATE KEY-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
"secret": "77R8cjOGi9yTCBt2",
"type": "PEM"
},
"capabilityAlternateId": "7bc8ab05-a0de-40db-a259-7deefb1265e9",
"connectionCriteria": {
"gatewayId": "3",
"measures": "https://dke-qa.eu10.cp.iot.sap/iot/gateway/rest/measures/c067272a-d3a7-4dcf-ab58-5c45ba66ad60",
"commands": "https://dke-qa.eu10.cp.iot.sap/iot/gateway/rest/commands/c067272a-d3a7-4dcf-ab58-5c45ba66ad60"
},
"deviceAlternateId": "c067272a-d3a7-4dcf-ab58-5c45ba66ad60",
"sensorAlternateId": "5564ce96-385f-448a-9502-9ea3c940a259"
}
Example for onboarding an MQTT Endpoint
{
"deviceAlternateId": "341cb230-83a7-45a1-a023-34cc1f1d58f5",
"capabilityAlternateId": "bb8e66c9-e8e1-4a06-959e-f3a1940a68e0",
"sensorAlternateId": "19e90568-9275-4023-879d-432c379081fe",
"connectionCriteria": {
"gatewayId": "2",
"measures": "measures/341cb230-83a7-45a1-a023-34cc1f1d58f5",
"commands": "commands/341cb230-83a7-45a1-a023-34cc1f1d58f5",
"host": "dke-qa.eu10.cp.iot.sap",
"port": "8883",
"clientId": "341cb230-83a7-45a1-a023-34cc1f1d58f5"
},
"authentication": {
"type": "PEM",
"secret": "xC6zMirxXHDsXDXFR4gE42qq79l7AheIvqiW",
"certificate": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n...-----END CERTIFICATE-----\n"
}
}
Save all those information, you’ll need them for communication with the agrirouter. |
Failure
On Failure, a JSON object including an error message is received, e.g.:
{
"error": {
"code": "0110",
"message": "Signing header is invalid, the request has timedout, or UTCTimestamp is not provided",
"target": "",
"details": []
}
}
Possible Error codes can be found in the error list
Handling Signature Issues
If you experience problems with an invalid signature, (Code 107), try the following:
-
make sure you encoded the whole body
-
compare the signature with the result of the node server tool delivered with the postman collection
-
check the timestamp. If your local time is ahead of or too far behind agrirouter servers time, it will not recognize the signature as valid. The agrirouter HTTP answer includes a timestamp reporting agrirouter’s server time.