Relativity REST API authentication

The Relativity REST APIs support multiple authentication methods so that you can choose the best one for your environment and application requirements. To provide secure communication between a client and a Relativity endpoint, it supports basic authentication over HTTPS and Active Directory authentication.

An authentication header is required for all calls to the REST endpoint.

The Authorization field in the HTTP header is used to pass user credentials. When authentication fails, the error code 401 (Unauthorized) is returned with additional information in the WWW-Authenticate header of the response.

If a request doesn't include an authentication header, the error code 401 is returned with the header: Bearer realm="Relativity.REST". If you set DeveloperMode instance setting is set to True, this error isn't returned. For more information, see Basic authentication.

See the following related page:

• Identity (authentication and user accounts)

Basic authentication

When using basic authentication over HTTPS, you should send authentication credentials with every REST request, since the service doesn't include an explicit login method or track a session token.

To include credentials in the HTTP header, you must supply a username and password that are concatenated into a string, using the format username:password. You must also compute the Base64 encoding for this string. The following code sample illustrates this process:

1
2
3
4
5
6
public void SetAuthorizationHeader(string username, string password, HttpClient request)
{
     string usernamePassword = string.Format("{0}:{1}", username, password);
     string base64usernamePassword = Convert.ToBase64String(Encoding.ASCII.GetBytes(usernamePassword));
     request.DefaultRequestHeaders.Add("Authorization", "Basic " + base64usernamePassword);
}

A request includes the basic authentication header with the Authorization field followed by the word Basic (indicating the type of authentication), and the encoded user credentials:

Authorization: Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE=

When an invalid basic authentication header is supplied on the request, a error code of 401 is returned with the following header:

Authorization: Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE=

For more information about header fields, see HTTP headers.

Cookie authentication

When a user logs into Relativity, the RelAuth cookie is issued to the browser. This encrypted cookie contains the information that validates the user. This cookie can be passed to REST service call instead of an HTTP authorization header. If the encrypted cookie is valid, the call will be authenticated under the credentials of the user who logged in via the web.

Applications that use custom pages often call REST services: a typical example can be a custom page that makes AJAX calls to a REST endpoint. The RelAuth cookie is automatically added to any AJAX calls from the browser. This enables most custom page applications to simply make their AJAX calls to the REST service and "piggy-back” on top of the browser’s authentication that is automatically handled by Relativity. For more information about custom pages, see Customize the UI.

Cookie authentication from JavaScript

You don't need to include an additional Authorization header when using cookie authentication from JavaScript within Relativity. The browser performs the authentication. See the following code sample:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<script type = "text/javascript" >
  $(document).ready(function() {
  $.ajax({
    url: "http://localhost/Relativity.REST/Relativity-Identity/v1/workspaces/-1/users",
    type: "GET",
    contentType: "application/json"
  })
    .done(function(data) {
    alert("success");

    var userCount = data.ResultCount;
    var retVal = "userCount: " + userCount;
    $("#result").text(retVal);
  })
    .fail(function(xhr, status, error) {
    alert("Status: " + status);
    alert("Error: " + error);
    alert("ResponseText: " + xhr.responseText);
  })
    .always(function() {
    alert("complete");
  });
});

Bearer token authentication

Bearer Token Authentication

You can connect to the REST services using bearer token authentication. When using bearer token authentication, clients access the service with an access token issued by the Relativity identity service based on a consumer key and secret obtained through an OAuth2 client..

When multiple web servers are hosted behind a load balanced route, you can't programmatically retrieve an authentication token. You must use a direct route to one of the web servers to retrieve the authentication token.

To create, obtain and use a bearer access token:

1. Create a Relativity OAuth2 Client (for more information see OAuth2 clients on the RelativityOne Documentation site):
   • Click Home > Authentication > OAuth2 Client Manager.
   • Click New OAuth2 Client to create a new client, or click Edit to modify an existing client.
   • Complete the fields on the form,  fields in orange are required:  
     • Name- enter a unique name for the OAuth2 client.
     • Enabled- indicate whether the client will have access to Relativity.
     • Flow Grant Type- select Client Credentials.
     • Context User- select a user who is a member of the Relativity Administrators group.
     • Access Token Lifetime- set the duration (in minutes) for which access tokens are valid. The recommended value is 60 minutes.
   • Click Save to create the OAuth2 client. For more information, see OAuth2 clients on the RelativityOne Documentation site.
2. Obtain a Bearer Token by sending a POST request to the token endpoint with your credentials.
   Copy

   curl -X POST "<host>/Relativity/Identity/connect/token" \
        -H "Content-Type: application/x-www-form-urlencoded" \
        -d "grant_type=client_credentials" \
        -d "scope=SystemUserInfo"
        -d "client_id=<your_client_id>" \
        -d "client_secret=<your_client_secret>" \

3. Use the Bearer Token by including the token in the Authorization header of your API requests.
Copy

curl -X GET "<host>/api/<servicename>/<versionnumber>/<endpoint>" \
     -H "Authorization: Bearer <your_access_token>"

Bearer Access tokens in PowerShell

You can use the following sample script to authenticate and retrieve an access token with PowerShell

# Set Variables (replace with appropriate values from your environment)
$relativityHost = "<host>"
$clientId = "XXX"
$clientSecret = "XXX"

# Define headers, Uri and body for authentication
$tokenHeaders = @{
    'Content-Type' = 'application/x-www-form-urlencoded'
}
$tokenUri = "$relativityHost/Relativity/Identity/connect/token"
$tokenBody = "grant_type=client_credentials&client_id=$clientId&client_secret=$clientSecret&scope=SystemUserInfo"

# Request Access Token
$accessToken = Invoke-RestMethod -Uri $tokenUri -Headers $tokenHeaders -Body $tokenBody -Method POST

# Extract the token (only the access token, not the full response)
$token = $accessToken.access_token

You can then use the token in a request, see the example below (replacing the placeholders with the values of the service you are interacting with)

$requestHeadersToUse = @{
  Authorization = "Bearer $token"
  'Content-Type' = "application/json"
}

# set the endpoint and method type
$requestUri = "$relativityHost/api/<servicename>/<version>/<endpoint>"
$methodType = "GET"

# send the request and get the reponse 
$response = Invoke-RestMethod -Uri $requestUri -Method $methodType -Headers $requestHeadersToUse

# do something with the response
$response | ConvertTo-Json