Access and Authentication for the Rest Api - Documentation for Ar System 22.1

Authentication workflow:

The following video (4:23) gives an overview of token-based authentication for every API call.

This video was recorded using the earlier version of  AR System but is valid for  AR System 9.1 and later versions.

Application credential requirements

The client must create a POST call and pass the user name, password, and authString in the Request headers using the /x-www-form-urlencoded content type.

The  AR System server then performs the normal authentication mechanisms to validate the credentials. If the credentials are valid, the  AR System server generates a JSON Web Token (JWT).

You can attempt a REST API call if you have a token. A single JWT token is valid for one hour. You can use a single token across multiple  AR System server that are in the same server group.

If the user provides a blank password, the AR System server does not attempt to cross-reference the password.

The JWT is a signed and base64 encoded string, and is sent back as a response body to the HTTP request. 

The client receives the token and uses it in all subsequent REST API calls through the Authorization header using the AR-JWT schema.

For more information, see Overview of the REST API.

Connections by HTTP and HTTPS

By default, access to the REST API is over HTTPS only and HTTP access is not permitted. An attempt to access any of the API endpoints (with the exception of /api/about and /api/version) over HTTP will result in a 403 Forbidden error.

curl -i 
 
HTTP/1.1 403 Forbidden
{
    "message"   : "Access forbidden",
    "code"      : 403,
    "transient" : false
}

On a new server, you must configure HTTPS before attempting to access the API (including submitting requests by using the Swagger UI).

On the HTTPS configuration page, you can enable API access over HTTP, but this is not recommended in production and should only be used for testing purposes. API requests contain your Authentication token in an HTTP header, and this is passed in plain text when you use HTTP.

For the same reason, if the appliance is configured to redirect HTTP requests to HTTPS, API access over HTTP cannot be enabled. This is to avoid the illusion of security, where the initial request to the API is transmitted in plain text and contains either your API token or contains a username and password combination.

Authentication scheme

This API follows the OAuth 2.0 specification with API tokens. An authentication token is an opaque string. A token is associated with one  AR System user, which could be a local or LDAP user. Some tokens include an expiry time, after which they are no longer valid, while others are permanent and never expire. In both cases, the token should be protected as securely as a password.

For information about how to authenticate the  AR System REST API, see Using the REST API with Swagger.