API Authentication

Authenticating API requests.

Last updated: 01 March 2022Author: Jillur Quddus

Please note that the OntoPop backend open-source software project, which includes the event-driven data pipelines and APIs, is undergoing extensive redesign and refactoring as part of OntoPop Community 3.x in order to improve performance, security, extensibility and maintainability. As a result, the documentation on this page will be significantly updated. Please refer to the OntoPop Roadmap for further information.

API Keys

OntoPop provides native out-of-the-box support for authenticating applications accessing the OntoPop APIs via API Keys. To use OntoPop's native API Key-based API authentication mechanism, it must be explicitly enabled via the application context configuration, specifically in the security.authentication.api namespace.

OntoPop Community 2.x only supports the management of API Keys using the secrets engine configured in the security.secrets configuration namespace (for example HashiCorp Vault, AWS Secrets Manager or Azure Key Vault).

Note that API Keys alone are not considered best-practice in terms of securing APIs given their propensity to appear in query string parameters and log files. If you are deploying OntoPop to a production environment, it is strongly recommended that you implement additional security measures to secure the OntoPop APIs, including but not limited to OAuth and JSON Web Tokens (JWT).

Schema

OntoPop manages API Keys using the following schema:

Property	Description	Example
`key`	The API Key itself that client applications must include in the X-API-Key request header.	ABCDEFGHIJKLMNOP12356789
`issueDate`	The date and time (UTC) that the API Key was issued, in `yyyy-MM-dd'T'HH:mm:ss` format.	2022-03-01T10:32:19
`expirationDate`	The date and time (UTC) that the API Key will expire, in `yyyy-MM-dd'T'HH:mm:ss` format.	2022-05-30T10:32:19
`issuer`	The name of the API Key issuer.	HyperLearning AI
`client`	The name of the client application.	Test App
`enabled`	Whether this API Key is enabled.	true
`roles`	A set of roles associated with this API Key for the purposes of authorization. Please see API Authorization for further details.	["ROLE_ONTOPOP_MANAGEMENT_API", "ROLE_ONTOPOP_TRIPLESTORE_API"]

Example API Key

Provided below is an example API Key that is issued to a client application:

{
  "key": "ABCDEFGHIJKLMNOP12356789",
  "issueDate": "2022-03-01T10:32:19",
  "expirationDate": "2022-05-30T10:32:19",
  "issuer": "HyperLearning AI",
  "client": "Test App",
  "enabled": true,
  "roles": [
    "ROLE_ONTOPOP_MANAGEMENT_API",
    "ROLE_ONTOPOP_TRIPLESTORE_API",
    "ROLE_ONTOPOP_SEARCH_API",
    "ROLE_ONTOPOP_GRAPH_API", 
    "ROLE_ONTOPOP_MAPPING_API"
  ]
}

Request Headers

If OntoPop's native API Key-based API authentication is enabled, then client applications must include the API Key that they have been issued in the X-API-Key request header.

Authentication Flow

Assuming that an API Key has been included in the X-API-Key request header, OntoPop will perform the following ordered actions to authenticate the client application:

Check whether the provided API Key exists in the configured secrets engine. OntoPop will look for a secret that has the same name as the API Key key property prefixed with APIKEY_ for example APIKEY_ABCDEFGHIJKLMNOP12356789.
If it does not exist, then a HTTP 401 Unauthorized response status will be returned to the client application.
If it does exist, then check whether the API Key is enabled, and that its expiration date has not passed. If either of these checks fail, then a HTTP 401 Unauthorized response status will be returned to the client. If both of these checks pass, then OntoPop will examine the roles that are associated with the API Key to authorize the request. Please see API Authorization for further details.