API Authentication/Authorization

The Xponent Graph API endpoints can be secured so that only known users or servers can call the API. This is important if any sensitive information is to be passed back by the Xponent Graph API. The Xponent Graph API uses Transport Layer Security (TLS) to ensure that all information is encrypted in flight between the server and the client. The approaches below can be used to add additional security to the endpoint. 

Basic Authentication

Basic Authentication means a user is given a username and password which allows for the use of the username and password (hashed or encrypted in some way) to be used as authentication for a web service. For example, the following credentials could be encoded with Base64 encoding and then passed in the headers as authentication:

Username: Test

Password: Pass1234!

Combine these together separated by a colon to create:
Test:Pass1234!

then Base64 encode this to get:
VGVzdDpQYXNzMTIzNCE=

which can then be passed as a header:
Authorization: Basic VGVzdDpQYXNzMTIzNCE=

To do this within your own KW API, this can be included as part of the graph by decoding it within a JavaScript node and then comparing it to a list of usernames and passwords (which can be stored in application parameters) who are eligible to use the API service. This way these usernames and passwords can easily be revoked or added as needed without interruption to the deployment of the API. 

(see https://tools.ietf.org/html/rfc7617 for more)

Open Authorization (OAuth)

Open Authorization means a user is given a username and password which they then use to call a login endpoint which then gives them back a token. This token can then be used as authentication for a web service. This token can have a limited time period of use (for example 24 hours) before it needs to be refreshed using the username and password again. 

This is normally done by calling a 'login' function or something similar with the username/password in order to receive a token. For example, given a username of 'Test' and a password of 'Pass1234!' the following endpoint could be hit:
https://api.endpoint.com/login

which would return a token of '688EF4CB68-686DC-4483-dH68F2-680265DC45dH0E'. This token is then included in the headers or body of any request as long as this token is valid for. Once the token expires it can be refreshed by calling the login endpoint again. 

(see https://tools.ietf.org/html/rfc6750 for more)

API Key (Shared Secret)

API Key or Shared Secret is when a token is shared with a user and the user can use that token as authentication to use a web service. This means the user receives a token, or is assigned a token, which they use for all calls to the web service. This token has no expiry time and can be used until the token is revoked. 

Adding a header value “x-auth-token” is a simple process for a user to enable shared secrets in the Journey hub. To validate an API request a get node can be used to check the value of "x-auth-token" and authenticate users that way. The cURL request might look something like this:

curl --location --request POST 'https://api-us.kitewheel.com/api/v1/listener/kitewheel_endpoint' \
--header 'x-auth-token: abc123' \
--header 'Content-Type: application/json' \
--data-raw '{"message":"hi"}'

A simple get node will now check if this API request comes from an authenticated user:

The value of "abc123" does not have to be hard coded as shown above. The value can be stored in application parameters or a database table with expiration times. This method can be used as a building block for a OAuth process as well.

IP Allowlisting 

IP Whitelisting can be used to limit who is allowed to call a web service to a specific list of IP addresses. This can be done as the only form of authorization, or can be used in tandem with any of the previously listed forms of authentication, in order to limit who can connect to or call a web service. This is useful for use cases where the user calling the web service will always be at the same IP address. For example, if a system calls a Xponent API endpoint for a recommendation for user who has logged into the system, that system could always call the Xponent API from a single IP address. This allows for more security around an API by limiting where people are when they call it, any calls, even with proper authentication credentials, that are not from the right IP address will be rejected.