OpenRMF® Professional External API Integration
OpenRMF® Professional has an external API for integration with other applications, scripts, and processes. This API is managed from within the OpenRMF® Professional application under the Application menu. From there you create the main API account for the user or system that is connecting to OpenRMF® Professional. And you can generate or regenerate the access token used when calling the API for security purposes.
Application API Accounts set up with OpenRMF® Professional are used from outside the application to perform functions in the same way as using the user interface. Things such as uploading SCAP scans, uploading checklist files, and uploading .nessus scan files can be automated and set up external to physically logging into OpenRMF® Professional using the API interface. The API accounts stored in this area use an API key and token to call the API endpoints. The token matches the username and password combination stored with the API key to “log in” to OpenRMF® Professional internally. And the roles and permissions for that username and password combination allow certain actions to happen within the OpenRMF® Professional framework.
For the actual API calls with examples please see the OpenRMF® Professional Developer’s Guide. Each API call requires the API path to call, the System Package key or Team Subpackage key, the Application Key from the Application API accounts, and the generated token produced from this screen. There is also a public GitHub repository at https://github.com/SoteriaSoftwareLLC/openrmfpro-automation with same data and scripts to use the API as well as a swagger.json for stubbing out code calls.
Listing the API accounts
Choose the Administration –> External API Integration menu to load the External Applications and API accounts created. Each entry is listed with the application name, key, and description. You also can click the green arrow to show more information such as the username this API account is associated with. The username corresponds to the user/password combination used to perform the API actions.
This username must have the proper roles and group permissions to perform the action or the response will be a 403 Bad Request or possibly 404 Unauthorized message.
Creating and Editing API Accounts
To add a new Application API account, click the Add Application button. A popup form like below shows. You can enter the Application Name, Key and Description from this window. The Key is a lowercase all alphabetic characters (no numbers or special characters) unique key to associate with this Application API account. Finally enter the username and password you wish to associate to this Application record.
The username must be set up within OpenRMF® Professional User Administration to have the valid roles and group permissions to perform the actions required within OpenRMF® Professional.
That user must have the ExternalAPI role assigned to them or the user account will not work correctly for this purpose.
To edit an existing account, you click the ... menu to the far right of the entry. You can update the application name or description here. The Application Key is not editable. If you want a new key you must delete and add a new record. If you do not want to reset the password you can leave the password alone and it will not be updated. To update the password when editing, include it before clicking the Save button.
Generating the Access Token for API Accounts
When calling the APIs a user or developer must know the Application Key and have a valid Token. The key is created when the application entry is created. The Token is generated by clicking the Generate Token button. A popup window like below is shown.
You MUST copy the token and store it safely or send it to the user or developer that needs it.
If you are running over HTTPS, you can click the “copy” button to copy it to your computer clipboard or copy the entire long string to save it.
Once you close that popup window that token is not saved anywhere else. This is by design. If a new one is needed, click the Generate button again to receive a new token. Each token lasts up to 1 year by default.
In the event a token is lost, shared by accident, left in source code or otherwise compromised the best practice is to reset the username password and regenerate a new token so your application or user can still access the API endpoints.