Federated instances

Federated instances provide a way for reviewers to easily switch to other Relativity environments. In the Relativity UI, links to federated instances appear in the User dropdown. You can use federated instances in combination with OAuth2 clients and authentication providers to enable single sign-on for multiple environments in your Relativity ecosystem.

The IFederatedInstanceManager interface allows you to programmatically interact with federated instances. You can also use the Federated Instance Manager REST service for cross-platform and browser-based applications.

• Federated instance fundamentals
• Create a federated instance
• Read a federated instance
• Read all federated instances
• Update a federated instance
• Delete a federated instance
• Example
• Federated Instance Manager REST service

See these related pages:

• User authentication
• Authentication API overview
• Authentication provider type
• Authentication profile
• Login profile
• OAuth2 clients

Federated instance fundamentals

Before programmatically interacting with federated instances, familiarize yourself with the Relativity federated instance user interface and review the information in the Relativity Documentation site. Note there is a strong correlation between the API operations and object properties and the user interface elements.

Use these guidelines when working with federated instances:

• To access the IFederatedInstanceManager interface, add the Relativity.Services.Interfaces.dll reference to your Visual Studio project. The file can be found in the Relativity SDK. For more information, see Set up your development environment.
• The Relativity user accessing the API must have the permissions required for working with federated instance objects.

Create a federated instance

To create a federated instance:

1. Like with other Services API interfaces, begin by accessing the IFederatedInstanceManager interface through a client proxy to the Services API and instantiating a FederatedInstance object. How you build the client proxy depends on how you plan to use it. If you plan to use it in a custom page, event handler, or agent, you can use API Helpers:

   Relativity.Services.Security.IFederatedInstanceManager FederatedInstance = this.Helper.GetServicesManager().CreateProxy<Relativity.Services.Security.IFederatedInstanceManager>(ExecutionIdentity.System);

   Otherwise, you can instantiate the clientManager object using the ServiceFactory class:

   1 2 3 4 5 6 7 8

   Uri restUri = new Uri("https://mycompany.com/Relativity.REST/api"); UsernamePasswordCredentials credentials = new UsernamePasswordCredentials("jsmith@relativity.com", "YourPasswordGoesHere123!");   ServiceFactorySettings settings = new ServiceFactorySettings(restUri, credentials); ServiceFactory serviceFactory = new ServiceFactory(settings);   using (IFederatedInstanceManager fedInstanceManager = serviceFactory.CreateProxy<IFederatedInstanceManager>()) { ...

   For more information about creating proxies, see Connect to the Services API.

2. Instantiate the FederatedInstance object.

   1 2 3 4 5

   FederatedInstance fedInstance = new FederatedInstance() {     Name = "Off Site Federated Instance",     InstanceUrl = "http://myRelativity.com/Relativity" };

   Notes:
   • A federated instance name must be unique. The name can only contain alphanumeric characters and spaces.
   • The URL must include the http or https protocol prefix.
3. Call the CreateAsync() method of the IFederatedInstanceManager interface and pass it the FederatedInstance object:

   await fedInstanceManager.CreateAsync(fedInstance);

You have created the federated instance and can now update it, for example, to add the HRD URL parameter for single sign-on redirect.

Read a federated instance

To read a single federated instance, call the ReadAsync() method of the IFederatedInstanceManager interface and pass the name of the federated instance:

Read all federated instances

To read all federated instances defined for a Relativity instance, call the ReadAllAsync() method of the IFederatedInstanceManager interface:

Update a federated instance

To update a federated instance:

1. Update the InstanceUrl property on the FederatedInstance object. In this example, we add the HRD URL parameter to redirect the user to a Integrated Authentication provider:

   fedInstance.InstanceUrl = "http://myRelativity.com/Relativity?HRD=integrated"

   Note: You can't update the name of an existing federated instance.

2. Call the UpdateAsync() method of the IFederatedInstanceManager interface and pass it the updated object:

   await fedInstanceManager.UpdateAsync(fedInstance);

Delete a federated instance

To delete a federated instance, call the ReadAsync() method of the IFederatedInstanceManager interface and pass the name of the federated instance:

Example

This example demonstrates how to create a federated instance, update it to add the HRD redirect to the URL, and then delete it:

Federated Instance Manager REST service

The Federated Instance Manager service allows you to interact with federated instances from browser-based and cross-platform applications. The service provides the same set of operations as the IFederatedInstanceManager .NET interface:

• CreateAsync
• ReadAsync
• ReadAllAsync
• SaveAsync
• DeleteAsync

Create a federated instance with REST

To create a federated instance from a RESTful application, send a POST request to this federated instance Manager service URL:

The request payload must include valid JSON representations of the workspace and index objects:

The response does not contain any data. Success or failure is indicated by the HTTP status code. For more information, see HTTP status codes.

Update a federated instance with REST

To update a federated instance, send a POST request to this federated instance Manager service URL:

The request payload must include valid JSON representations of the federated instance object with updated values:

The response does not contain any data. Success or failure is indicated by the HTTP status code. For more information, see HTTP status codes.

Read a federated instance with REST

To read a single federated instance, send a POST request to this federated instance Manager service URL:

The request payload must include the federated instance name:

The response returns the federated instance object:

Read all federated instances with REST

To read all federated instances in a Relativity instance, send a POST request to this federated instance Manager service URL:

The response returns a collection of federated instance objects:

Delete a federated instance with REST

To create a federated instance from a RESTful application, send a POST request to this federated instance Manager service URL:

The request payload must include the federated instance name:

The response does not contain any data. Success or failure is indicated by the HTTP status code. For more information, see HTTP status codes.