Proxies and authentication

The Kepler framework uses a proxy to handle client requests. It exposes a factory class that you can use to create the a client proxy by passing URIs to the required services and credentials. The following sections outline this process and available authentication methods.

ServiceFactory class

Use the ServiceFactory class to create proxies for Kepler services. The T CreateProxy<T>() method is used to create the proxy, which takes and returns the following:

• Generic type T - the service contract, which is the interface defining the service.
• Proxy - a .NET object that implements the contract returned by the method.

Use the following parameters to construct a ServiceFactory object, which is available through the ServiceFactorySettings class:

• REST base URI - used to construct the full URI to Kepler services. It uses the following format:
  Copy

  1
  <scheme>://<machine name>/Relativity.Rest/api

• Credentials - see Authentication for Kepler services.

The following code sample illustrates how to create a proxy. For sample usage, see Client .NET proxy.

1
2
3
4
5
6
7
8
9
10
11
Uri relativityRestUri = new Uri(@"http://localhost/relativity.rest/api");
Credentials credentials = new UsernamePasswordCredentials("username", "password");

ServiceFactorySettings settings = new ServiceFactorySettings(relativityRestUri, credentials);

ServiceFactory factory = new ServiceFactory(settings);

// Create a proxy for a Kepler service
IExampleService proxy = factory.CreateProxy<IExampleService>();

bool serviceOkay = await proxy.PingAsync();

Client .NET proxy

Use the client .NET proxy to interact with a Kepler service as a set of .NET objects. This proxy is created using the ServiceFactory class. The proxy type is the same as the Kepler service interface, and each member method becomes a service endpoint.

When you call a member method, the proxy makes a corresponding HTTP request to the respective service endpoint, using the appropriate URL, HTTP headers, and verbs. The response from the endpoint has the return type of the proxy method that was called.

1
2
3
4
5
6
7
8
9
10
11
12
13
// ServiceFactory used to create a proxy object. (Omitting constructor parameters for simplicity.)
var factory = new ServiceFactory(...);

// Create client-side service proxy.
var proxy = factory.CreateProxy<IExampleService>();

// Use the proxy to exercise a Kepler service as .NET object.
bool serviceOK = await proxy.PingAsync();

// Use the service responses
if (serviceOK) {
    Console.WriteLine("Service is okay.");
}

Authentication for Kepler services

The Kepler framework uses methods that take credentials for basic and OAuth2 authentication. It also supports cookie authentication through the browser. See the following sections for more information:

• Credentials
• Cookie authentication

Credentials

The Kepler framework supports the following credential types:

Note: Using Bearer Token is recommended over using username and password.

• BearerTokenCredentials() method - takes credentials used for OAuth2 authentication. For more information, see Bearer token authentication and Client Credentials on the Oauth website.
  Copy

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  //Get Access token
  HttpClient httpClient = new HttpClient();
  ClientCredentialsTokenRequest tokenRequest = new ClientCredentialsTokenRequest() {
      Address = "https://mycompany.relativity.one/Relativity/Identity/connect/token",
      ClientId = "client_id",
      ClientSecret = "secret",
      Scope = "UserInfoAccess"
  };
  
  TokenResponse response = httpClient.RequestClientCredentialsTokenAsync(tokenRequest).ConfigureAwait(false).GetAwaiter().GetResult();
  

• UserNamePasswordCredentials() method - takes credentials used for basic authentication. For more information, see Basic authentication.
  Copy

  1
  2
  // Pass in the username and password to this method.
  Credentials credentials = new UsernamePasswordCredentials(username, password);

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. For more information, see Cookie authentication.

Note: Cookie authentication only apples to browser-based calls, such as those made through JavaScript, to Kepler services.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<script type = "text/javascript" >
    $(document).ready(function() {
        $.ajax({
                url: "http://localhost/Relativity.REST/Relativity/User",
                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");
            });
    });
</script>