Updated for version 1.0.0
Introduction
The One Sightsolutions ossRestApiServer module provides a way for third party applications to read and write point data, and read history data via RESTful HTTP API requests to a Niagara station. It provides an implementation of OAuth 2.0 token authentication to make this data transfer secure.
** This guide describes how to install and configure the software in Niagara. There is separate documentation that describes how to access the API from another computer here.
Requirements
It is assumed that the user is trained in the use of Niagara 4 and is familiar with the use of web APIs.
The ossRestApiServer software is only compatible with Niagara versions 4.8 or later.
You must read the End User License Agreement before using this software.
Installation
Niagara Software Module Installation
Before the ossRestApiServer software can be used, the Niagara software modules must be installed on the user’s PC and the target host.
The following files supplied by One Sight Solutions must be installed on the host using the Niagara platform software manager.
• ossRestApiServer-rt.jar
• ossRestApiServer-wb.jar
These software files must also be installed in the appropriate Niagara modules directory of any PC on which you intend to access the ossRestApiServer software.
Niagara Software Licensing
The host running the ossRestApiServer software must be licensed by One Sight Solutions before it will operate correctly.
The following information is required to generate the ossRestApiServer license:
• Niagara host identifier (e.g. Qnx-TITAN-0000-XXXX-XXXX).
• Niagara host serial number.
Please send this information to One Sight Solutions: info@onesight.solutions
It is recommended that the license is installed on the Niagara host using the platform license manager import capability to download the license directly from the Niagara license server over the internet.
If it is not possible for the host to download the license from the internet then One Sight Solutions can supply the required license files which can then be installed manually.
Ensure that the One Sight Solutions certificate is also installed, so the Niagara platform license manager should show both of the following files:
• OneSightSolutions.license
• OneSightSolutions.certificate
The host should reboot during the license installation process.
Overview of API Operation
It is useful for the person configuring the ossRestApiServer software to have a high-level
understanding of how the API functions so they can make the correct choice of configuration values.
While it is not necessary to know the full technical details of the requests and responses involved in the use of the API, understanding the fundamental elements and interactions will help.
A simple overview of the API interaction is shown in Figure 1.
For each API client the ossRestApiServer will generate a set of client credentials.
These pieces of information are transferred to the client application manually (e.g. cut and paste).
The client application will then use those credentials when making a token request to the API, the ossRestApiServer software will then generate an access token and a refresh token and send them back to the client.
The client may then request data from the API using the access token for authorisation.
The access token is only valid for a limited period of time, when this time expires the client may use the refresh token to obtain a new access token and then continue making data requests using the new access token.
Most installations will only allow the client application credentials to be used once to generate the access tokens. Then only the tokens can be used and must be refreshed when they expire.
Setting up ossRestApiServer
Install API Service
First the OssRestApiService must be installed in the station.
This component can be found in the ossRestApiServer palette, as shown in Figure 2.
Drag the OssRestApiService component from the palette into the station services folder.
Resource Selection
There are license restrictions on the number of points and histories that can be accessed using the API service.
The point and history resources that will be available must be selected in advance using the Api Resource Manager. Double click on the ‘Resources’ section of the OssRestApiService to access the Api Resource Manager.
At the bottom of the resource discovery window there are a set of buttons, as shown in Figure 3.
To add points to the list of allocated available resources click the ‘Find Points’ button.
You will then be prompted to select an item from the station hierarchy which will define the base location from where the points will be searched. If you just click OK then all points on the station will be listed.
To add histories to the list of allocated available resources click the ‘Find Histories’ button.
Once a list of discovered points or histories has appeared you can add them to the allocated resource list using the usual Niagara methods (double click, drag or using the add button).
Note that duplicate entries will not be created, so if you attempt to add a resource that already exists in the allocated resource list then it will be ignored.
If the resource licence limit is exceeded any additional resources added will show a fault and will not be available for use by the API. All resources in the allocation list that are not in fault will continue to work with the API.
Note that if you exceed the licence limit and then delete some previously allocated resources you can use the ‘Refresh’ action on the ‘Resources’ components to reallocate the remaining resources.
The point paths and history identifiers will not update if the source resources are renamed or moved in the station, so you must manually re-discover the resources if they are modified.
Install API Client Application
Many different clients may access the API, each with different credentials and access rights.
Each client must have its own client application installed and configured.
For each client, drag an OssApiClientApplication component from the ossRestApiServer palette and drop it in the OssRestApiService component, as shown in Figure 4.
Generate Client Credentials
Once the OssApiClientApplication is installed in the OssRestApiService the access credentials can be generated.
Enter a client name in the ‘Application Name’ property of the OssApiClientApplication component.
This name can contain spaces and is only used to identify the client application.
Then view the ‘Client Credentials’ property (which has a special ‘Generate Client Credentials View’ by default).
Click on the ‘Generate Credentials’ button at the bottom of the view, as shown in Figure 5.
You will see a warning window indicating that the credentials that are about to be generated will only be temporarily visible and should be copied before continuing, shown in Figure 6.
Click OK on this window.
Text values will now be available in the ‘OAuth Client Id’ and ‘OAuth Client Secret’ properties, as shown in Figure 7.
These two values should be copied for use by the external client application that will access the API.
As indicated by the warning window, once the user navigates away from this credentials view the client secret value will no longer be available and will have to be regenerated.
It is important to make sure that the client ID and client secret values are kept private to the ossRestApiServer administrator and the client application that will be accessing the API.
Any transmission or storage of these values should be secure.
For additional security the client credentials have a validity period and if they are not used within that period they become invalid and have to be re-generated. The default period is 1 week (168 hours) but can be changed with the ‘Valid Time’ property.
Once the client credentials have been created a new ‘AuthGrant’ component will be created inside the client application with additional status and configuration properties.
Resource Access Permissions
Niagara station points and histories will only be accessible if the application is configured correctly with the correct permissions.
API resource permissions are managed using the Niagara user, role and category mechanisms to assign permissions to a user to be able to read or write to resources. Please read the Niagara documentation for instructions on how to set up these permissions.
These users are then assigned to each application using the ‘Read Access User’ and ‘Write Access User’ properties. Note that different users can be created for read and write permissions, or these can both be the same.
The Niagara users created are only used for setting permissions. If not used for other purposes these users can be disabled to increase security. The users passwords are not used by ossRestApiServer. If write access is required then the ‘Write Access’ Boolean must also be set to true in the ‘Auth Grant’ subsection of the application properties.
ossApiService and Application Example
An example configuration is shown in Figure 8.
ossRestApiServer Reference
This section describes all the properties of the OssRestApiService.
ossRestApiService Enabled
If the OssRestApiService Enabled property is set to false then all API requests will be refused with a 400 HTTP status code.
Credentials or access tokens do not have to be regenerated once the service is re-enabled as long as they remain valid.
Resources
This section contains the allocated point and history resources that are allowed to be accessed via the API as defined by the license that has been obtained for the host.
These resources and the resource manager view are described in ‘Resource Selection’.
Token Expiry Time
The Auth Server Token Expiry Time determines how long the access token will be valid from the time it is generated. Once the access token has expired the refresh token must be used to obtain a new access token.
Block Repeated Failed Auth Attempts
This Auth Server property is used in conjunction with the ‘Max Failed Auth Attempts’ property to prevent brute force attacks.
If set to true then the API will refuse all authentication attempts after the maximum number of failures has been reached, even if the correct credentials are used.
If set to false then an unlimited number of failures are allowed and the API will still successfully authenticate if the correct credentials are used.
Max Failed Auth Attempts
This Auth Server property is used in conjunction with the ‘Block Repeated Failed Auth Attempts’ property to prevent brute force attacks.
The property value determines the number of failed authentication attempts that are allowed before the API refuses all further authentication attempts, (even if the correct credentials are used).
Block Credential Reuse
By default, the API will only authorise the client credentials once and after that only the access token and refresh tokens can be used to access the API.
If the Auth Server ‘Block Credential Reuse’ property is set to false then the credentials can be reused.
If the ‘Block Credential Reuse’ property is set to true then any attempts to reuse the client
credentials (after the initial authorisation) will result in an unauthorized error response (401).
This feature is mainly used when first developing an API integration solution and for security reasons should be set to true as soon as the API access is working correctly.
ossApiClientApplication Reference
This section describes all the properties of the OssApiClientApplication.
Application Name
The application name property is required, but is only used to identify the client application.
Enabled
If the OssApiClientApplication Enabled property is set to false then all API requests using the credentials or tokens for this application will be refused with a 400 HTTP status code.
Credentials or access tokens do not have to be regenerated once the service is re-enabled as long as they remain valid.
Authorized
This is a read-only property that indicates if an application in the OssRestApiService has been successfully authorised by a client and therefore has issued tokens.
Debug Enabled
This property controls whether debug information is added to API request failure responses.
This debug information is disabled by default for security reasons.
Failed Auth Attempts
This is a read-only property that indicates the number of failed authentication attempts this API application has received. This can be reset with the ‘Reset Failed Auths’ action.
This is related to the ‘Max Failed Auth Attempts’ OssRestApiService property.
Read Access User
All resources accessed by this API application must be readable by the Niagara user specified by the read access user property.
See ‘Resource Access Permissions’.
Write Access User
All resources written to by this API application must be writable by the Niagara user specified by the write access user property.
See ‘Resource Access Permissions’.
Note that to enable clients to write to points the Auth Grant ‘Write Access’ property must be set to true as well as the write user being configured correctly.
Client Credentials
The client credentials component contains the ‘Client Id’ and ‘Client Secret’ properties.
These client credentials are generated by the ossRestApiServer software using the buttons available on the default ‘Generate Client Credentials View’.
Note that once generated, if you close the view the ‘Client Secret’ property is no longer able to be viewed and cannot be recovered from the system. If the secret is lost then the only solution is to reset the client secret using the button available on the credentials view. If the secret is reset then any clients still using the old secret value will no longer be able to access the API application.
Copying Client Credentials
Note that although the client secret is displayed as a multi-line value in the credentials view, both the client identifier and client secret should be transferred as single line values. Any line breaks in these values should be removed.
Care should be taken if these values are transferred between non-windows systems as line break characters can differ between these systems and values can get corrupted.
Resetting Client Credentials
If the client credentials for an application are lost or compromised and new ones are required then they can be regenerated.
From the ‘Generate Client Credentials View’ of the Client Credentials component in the Oss API Client Application there is a ‘Reset Client Secret’ button. This button will cause the client secret to be regenerated.
Note that as before, this secret will only be available while the generation view is visible. If you close this view you will not be able to go back and access the secret again.
If the client credentials for an application are reset then any clients using the previous credentials and tokens will no longer be able to access the API.
Auth Grant
Note that the AuthGrant component is only created after the client credentials are generated.
Authorized
This is a read-only property that indicates if the API application has been successfully authorised by a client and therefore has issued tokens.
Authorization Time
This is a read-only property that indicates the last time a client was successfully authorised with the application.
Time Generated
This is a read-only property that shows the time the client credentials were last generated.
Valid Time
This property is used to set how long the client credentials will remain valid for after they are generated.
The client Id and client secret credentials must be used to generate a token within this time or they will become invalid.
Write Access
This property is used to control whether this application will allow write access.
Fault Cause
This is a read-only property that shows the current application fault cause, or blank if there is no fault.
Fault Time
This is a read-only property that shows the last application fault time.
Usage Notes
Token Storage
Whenever API tokens are generated they must be stored in the Niagara station so they persist if a station is rebooted.
Tokens are generated when authorisation requests are processed and when tokens are refreshed.
To ensure that these important security values are not lost the ossRestApiServer software will force the Niagara station to be saved whenever these tokens change. This writes the values to non-volatile storage.
It is possible that an engineer may kill the station at the same time the access token is being saved and therefore some of the station data may not be saved and the new access token may be lost. In this situation the client credentials will have to be regenerated. Note this will not happen if the station is shutdown or rebooted normally as the station will be saved correctly in these circumstances.