Authentication API overview

Relativity includes a full set of APIs allowing you to configure authentication for your instance and users. Using Relativity's APIs you can perform the same actions programmatically that you normally would perform manually through the user interface. Typical use cases for the API include provisioning new users automatically and migrating users between environments.

To familiarize yourself with the general concepts of Relativity's authentication system, see Authentication and other related pages on the Relativity Server2021 Documentation site.

This page contains the following information:

See these related pages:

General API concepts

The authentication APIs use the following concepts:

  • Authentication Provider Types. These represent the different protocols for authenticating against Relativity, for example, Password, Integrated Authentication, and OpenID Connect. Using the API you can inspect enabled protocols for a particular environment. You can also enable or disable specific protocols. Disabling an authentication provider type completely disables that login workflow for the entire Relativity instance .
  • Authentication Profile. The authentication profile is a collection of authentication settings for each protocol. For example, the authentication profile is where you configure Password settings such as min and max password length. It also is where you define external identity providers that use the OpenID Connect and SAML protocols. How you configure your authentication profile determines how the look and behavior of the Relativity login page.

    The authentication profile allows you to define up to one of each of the following: Password, Integrated Authentication, Active Directory, RSA, and Client Certificate. You can also define any number of OpenID Connect and SAML external identity providers. The API enforces validation rules such as making sure there are no logic conflicts or inconsistencies in your authentication profile.

  • Login Profile. Whereas the authentication profile applies to the environment, each user has a Login Profile that defines the user-specific options for each provider on the authentication profile. Each entry in the user's Login Profile corresponds to a matching entry in the environment's authentication profile. Each user automatically has a login profile upon creation, and you can not delete that pofile.

Working with provider types and profiles

This section outlines the steps required to configure authentication in your Relativity environment.

Step 1: Configure Authentication Provider Types

The API allows you to enable or disable authentication protocols on an environment level. As a best practice, you should only enable the protocols that you actually want to use in the environment. Relativity currently ships with all Provider Types enabled by default, and you can disable the ones you do not want to use.

See for Authentication provider type additional information and code samples.

Note: In a future release we expect to ship with all authentication provider types disabled by default except for Password. You should write your update logic to explicitly enable or disable Provider Types based on your individual requirements.

Step 2: Configure the Global Profile

The Global Profile defines the environment-wide configuration options for each Authentication Provider (that is, Password, RSA, OpenID Connect). Some Providers have many options (such as Password) whereas some have just a few. The Global Profile has properties for each of the Provider Types.

See Authentication profile for additional information and code samples.

Note: In the current implementation of the authentication API, there is a single global authentication profile. This single entity is called the Global Profile. Admins currently do not have the ability to create multiple profiles.

In a future version of Relativity we expect to support multiple authentication profiles in order to support multiple login pages within the same environment. The idea is to structure the API so that we can support a multi-tenant, self-service model in the future. This is why Provider Types are separate from the authentication profile - even though they look redundant. In a multi-tenant scenario, an infrastructure admin could globally enable the protocols they want to support, while a tenant admin could customize their individual login page and settings.

Note: If you change any OpenID Connect or SAML 2.0 Providers on the authentication profile, you must perform an IIS reset on every web server in your environment. An upcoming release will correct this so that authentication profile dynamically updates on each server.

Step 3: Configure the Login Profile

See Login profile for additional information and code samples.

Business and validation rules

The authentication API enforces several business rules when working with the Profiles. These rules enforce consistency and safety in the authentication configuration. If you violate any of the validation rules while saving an Authentication or Login profile, the API will return an error and will let you know how to correct the error.

Some of the key business rules include:

  • All of the provider names must be unique on the authentication profile.
  • You remove a Provider from the authentication profile by setting its property to null. There is no explicit 'delete' function on Providers.
  • Each user can only have one of the following Methods configured: Password, Active Directory, and RSA. The reason for this is that when a user types their e-mail address and "password" into the Relativity login form, Relativity needs to know which Provider Type the user is trying to authenticate against. Since Password, Active Directory and RSA all share the same login input fields, a user can only have one of those three Methods configured.

Note that it is perfectly valid configure some users for RSA, some for Password, and some for Active Directory. The restriction is that a specific user can only have one of those three Methods at a time. There are no user restrictions on any of the other Provider Types.

  • You remove a Method from the Login Profile by setting its property to null. There is no explicit 'delete' function on Methods.
  • If you remove a Provider from an authentication profile, all of the corresponding Methods on every user's Login Profile are automatically removed. There is no warning or undo feature for this action, so be careful when removing a Provider programmatically.