Access and authentication for the REST API
Authentication workflow:
Task | Action | Reference |
|---|---|---|
1 | Create a POST call for issuing and sending token | |
2 | Create a token for authentication | |
3 | Release the token |
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 send 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 servers that are in the same server group.
If a 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. It 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 by 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 (except for /api/about and /api/version) over HTTP will result in a 403 Forbidden error.
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.
To generate a token from the /jwt/login endpoint
All REST requests must be authenticated. REST uses token-based authentication.
Description | Creates a new token. | ||||||
URL qualifier | /api/jwt/login | ||||||
Method | POST | ||||||
Headers |
| ||||||
Body |
| ||||||
Returns | An encoded string in the response body referred to as TOKEN. |
Here is an example to create a token:
Request URL
Request headers
Content-Type: application/x-www-form-urlencoded
username=Allen&password=password
Response body
Date: Wed, 03 Dec 2014 23:39:41 GMT
Content-Type: text/plain
Server: Jetty(8.1.15.v20140411)
eyJhbGciOiJIUzI1NiJ9.
eyJleHAiOjE0MTc2NTM1ODgsInN1YiI6IkFsbGVuIiwibmJmIjoxNDE3NjQ5ODY4LCJpc3MiOi
JXLUNTRUlFUk9FLTI5LmFkcHJvZC5ibWMuY29tIiwianRpIjoiSURHQUFCRFVDMllHSUFONkJGUTJBQUFFUEZBNVFXIiwiX2NhY2hlSWQiOjQ3LCJpYXQiOjE0MTc2NDk5ODh9.
V4LGLcEdwD8V_I4rzoWYYSZmEMA82LBB_lEfz4Xnz9Y
Here is a sample code snippet for creating the token:
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.HttpEntity;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;
public class Login {
public static void main(String[] args) throws Exception {
// start HTTP POST to get a token
CloseableHttpClient httpClient = HttpClients.createDefault();
HttpPost httpPost = new HttpPost("http://localhost:8008/api/jwt/login");
// send the username and password
List<NameValuePair> nvps = new ArrayList<>();
nvps.add(new BasicNameValuePair("username", "Allen"));
nvps.add(new BasicNameValuePair("password", "password"));
httpPost.setEntity(new UrlEncodedFormEntity(nvps));
// make the call and print the token
try (CloseableHttpResponse response = httpClient.execute(httpPost)) {
HttpEntity entity = response.getEntity();
String token = EntityUtils.toString(entity, StandardCharsets.UTF_8);
System.out.println(token);
}
}
}
To release a token from the /jwt/logout endpoint
Description | Releases the token. | ||||
URL qualifier | /api/jwt/logout | ||||
Method | POST | ||||
Headers |
|
Here is an example to release a token:
Request URL
Request header
eyJleHAiOjE0MTc2NTM1ODgsInN1YiI6IkFsbGVuIiwibmJmIjoxNDE3NjQ5ODY4LCJpc3MiOi
JXLUNTRUlFUk9FLTI5LmFkcHJvZC5ibWMuY29tIiwianRpI
joiSURHQUFCRFVDMllHSUFONkJGUTJBQUFFUEZBNVFXIiwiX2NhY2hlSWQiOjQ3LCJpYXQiOjE0MTc2NDk5ODh9.
V4LGLcEdwD8V_I4rzoWYYSZmEMA82LBB_lEfz4Xnz9Y
Response body
Date: Wed, 03 Dec 2014 23:46:03 GMT
Server: Jetty(8.1.15.v20140411)
Here is a sample code snippet for releasing the token.
import org.apache.http.StatusLine;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
public class Logout {
public static void main(String[] args) throws Exception {
String token = args[0];
// start HTTP POST to logout and invalidate the token
CloseableHttpClient httpClient = HttpClients.createDefault();
HttpPost httpPost = new HttpPost("http://localhost:8008/api/jwt/logout");
// add the token to the header
httpPost.addHeader("Authorization", "AR-JWT " + token);
// make the call and print the status
try (CloseableHttpResponse response = httpClient.execute(httpPost)) {
StatusLine status = response.getStatusLine();
System.out.println(status);
}
}
}
If you log in with your credentials on one computer and you try to log in from a different computer with the same credentials, you will get a 9093 error. For more information about a 9093 error, see Error-messages-8900-to-9100.
Required and optional headers
The required and optional headers for REST APIs are as follows:
Header | Value |
|---|---|
Authorization | Token |
(Optional) X-AR-Client-Type | Client Type ID |
(Optional) X-AR-RPC-Queue | RPC queue to which the client calls are routed |
(Optional) X-AR-Timeout | Timeout (in seconds) for a REST request The default value is 120 seconds. |
(Optional) X-AR-TR-Core-Id | The core ID in a trace ID |
(Optional) X-AR-TR-Counter | The counter in a trace ID |
(Optional) X-AR-Trace-Id | The complete trace ID |
(Optional) X-AR-TR-Is-Counter-Locked | The lock counter |
(Optional) X-AR-Impersonated-User | (Base64 format only) Name of the impersonated user |