Authentication and permissions in the REST API
All REST API calls must be authenticated. Instead of passing the full credentials on every REST API call, REST uses a token. The token is valid for a configurable amount of time and acts like a temporary password.
Watch the video on You Tube 
https://www.youtube.com/embed/xue9Gx-dbEA for information on Token based authentication.
This video is recorded using the earlier version of BMC Remedy AR System and is valid for BMC Remedy AR System 9.1 and later versions.
Refer to the following table to understand the authentication workflow:
| Task | Action | Reference |
|---|---|---|
| 1 | Create a POST call for issuing and sending token | To issue and send a token |
| 2 | Create a token for authentication | To create a token |
| 3 | Release the token | To release a token |
To issue and send a token
The client creates a POST call and passes the user name, password, and authString in the Request headers using the /x-www-form-urlencoded content type.
POST /api/jwt/login HTTP/1.1 host: www.example.com username=SomeUser&password=mysecret&authString=authenticationstringThe AR System server performs the normal authentication mechanisms to validate the credentials. If the credentials are valid, the AR 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 an hour. You can use a single token across multiple AR servers that are in the same server group.// comments not actually included, added for clarity { // the username "sub" : "SomeUser", // the Server-Connect-Name of the AR Server who issued the token "iss" : "www.example.com", // the UNIX time when the token was issued "iat" : 1408774310, // 2 minutes before "iat", to account for clock skew between servers "nbf" : 1408777790, // the UNIX time when the token expires, the duration being a configurable value (probably between 1 minute and 12 hours) "exp" : 1408777910, // a custom claim, the cache ID "_cacheId" : 13 }Note
If the user provides a blank password, the AR System server does not attempt to cross-reference the password.
The JWT is signed and base64 encoded string, and is sent back as a response body to the HTTP request.
HTTP/1.1 200 OK eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXkThe client receives the token and uses it in all subsequent REST API calls through the Authorization header using the AR-JWT schema.
GET /api/arsys/v1/entry/SomeForm HTTP/1.1 Authorization: AR-JWT eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
To create a token
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 as TOKEN. |
This example provides information to create a token.
Request URL
POST http://localhost:8008/api/jwt/loginRequest headers
Content-Length: 32
Content-Type: application/x-www-form-urlencoded
username=Allen&password=password
Response body
HTTP/1.1 200 OK
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
The following is a sample code snippet for creating the token.
package com.example;
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
| Description | Releases the token. | ||||
| URL qualifier | /api/jwt/logout | ||||
| Method | POST | ||||
| Headers |
|
This example provides information to release a token.
Request URL
POST http://localhost:8008/api/jwt/logoutRequest header
Authorization: AR-JWT eyJhbGciOiJIUzI1NiJ9.
eyJleHAiOjE0MTc2NTM1ODgsInN1YiI6IkFsbGVuIiwibmJmIjoxNDE3NjQ5ODY4LCJpc3MiOi
JXLUNTRUlFUk9FLTI5LmFkcHJvZC5ibWMuY29tIiwianRpI
joiSURHQUFCRFVDMllHSUFONkJGUTJBQUFFUEZBNVFXIiwiX2NhY2hlSWQiOjQ3LCJpYXQiOjE0MTc2NDk5ODh9.
V4LGLcEdwD8V_I4rzoWYYSZmEMA82LBB_lEfz4Xnz9YResponse body
HTTP/1.1 204 No Content
Date: Wed, 03 Dec 2014 23:46:03 GMT
Server: Jetty(8.1.15.v20140411)
The following is a sample code snippet for releasing the token.
package com.example;
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 get 9093 error. For more information about a 9093 error, see Error messages 8900 to 9100.
Related topics
Integrating AR System forms with a third-party application by using REST API
Comments
Can we call the authentication REST API by sending a encoded password or does it has to be provided as clear password?
Log in or register to comment.