User authentication

Relativity uses several industry-standard technologies, enabling versatile authentication options. It supports local (such as password related) or external (such as smart cards, or external identification providers) authentication methods. You can add and enable each type individually, as well as assigning at least one, and in some instances multiple methods, for each user.

Note: Update your IIS settings by changing the Web API to Anonymous Authentication rather than Windows Authentication. You must update this setting in order to publish documents to a workspace or process data to Data Grid.

This page contains the following sections:

See these related pages:

Authentication mechanisms

Relativity supports the following authentication mechanisms.

  • Password – a method that includes a username (the user's email address) and a password.
  • RSA – a method using an RSA SecurID token, a third party security solution, and validates credentials from an RSA server.
  • Active Directory – a method using an email address and the user's Active Directory password.
  • Integrated Authentication – (previously called Windows authentication) a method using a directory service, such as Kerberos or NTLM (NT LAN Manager). The authentication attempt automatically initiates if the user logs in from a specific IP address range.
  • Client Certificate – (previously called Smart card authentication) an external method requiring a smart card and PIN, and validates from an IIS server.
  • OpenID Connect – a protocol for an external identity provider, authenticating against an external identity provider using the OpenID Connect protocol. OpenID Connect is a modern authentication protocol that connects to providers such as Azure Active Directory. See the external web site OpenID Connect for more information.
  • SAML 2.0 – a method that authenticates against an external identity provider using the SAML 2.0 protocol. SAML 2.0 is an older authentication protocol that is still in widespread use. See the external web site SAML 2.0 for more information.

In addition to the above protocols, Relativity has the following additional authentication features:

  • Two-factor Authentication: When logging in with the Password method, you can require the user to pass an additional two-factor check based on an email or message sent to the user's phone (through a mobile email gateway).
  • Trusted IP Range: You can limit access to the Relativity application based on the user's source IP address.

    Note: Trusted IP Range can be set as a property on the User object. For more information, see User DTO and User REST documentation.

Changes from prior versions

If you are upgrading from a prior version of Relativity, there are some important differences. Overall, the new authentication system is more flexible than the previous system.

However, there are also some workflow changes as well as breaking changes to the Relativity API in order to support the new workflows.

The AuthenticationData Field Has Been Replaced. Authentication options used to configure each user through the AuthenticationData field by a single string value with slashes and colons. We replaced this error-prone system with a rich object model that provides improved safety and flexibility when configuring authentication.

Individual Provider Types Can be Enabled / Disabled. You can selectively turn off authentication protocols that you never intend to use. This improves security and prevents another system admin from trying to configure an authentication method that should not be used.

This includes the Password Provider Type. In previous versions of Relativity required every user to have a password in the database. Now, you can completely remove Password authentication from your instance and exclusively use another login approach such as OpenID Connect or RSA.

Built-in Support for SAML and OpenID Connect. Relativity now has built-in support for the OpenID and SAML protocols, which allows you to connect your instance to an external identity provider. If your environment has a custom solution for external authentication, you are strongly encouraged to use the built-in functionality instead.

A New Password Workflow. The new password workflow significantly changes the ways users interact with authentication. This change improves the security of the Relativity instance. See the Password workflow changes for more details.

Schema / API Changes.Due to the significant changes to authentication, both the User table and the User API in REST has changed. Any integrations that are directly querying the User database table may need to be changed. The REST APIs have the same fields on the User object, but the behavior for some of those fields has changed. You can find out more information about the schema updates from Database schema updates for Relativity.

Password workflow changes

The new workflow changes how users interact with passwords. Although this introduces some necessary changes to how Relativity users are managed in an environment, the goal is to improve the overall security of the Relativity instance by following industry best practices.

Two major changes have been made to the Password workflow.

Passwords are not sent through email to users or administrators. Email is an inherently insecure method for sharing passwords. Many email systems use unencrypted communication, and there are security implications with storing a password unencrypted in an email system. Because of the security limitations of using email, Relativity no longer supports sending the user's password through email.

Administrators can no longer set passwords for users. In order to protect a user's account, only that user should know their password. By default Relativity no longer allows administrators to set passwords when creating the user. Instead, Relativity expects the end user to manage their own password (according to the complexity rules defined by the system administrator).

Of course, users still need a secure way to set their password and log in to Relativity for the first time. There is a new feature called the Invitation Workflow that can be used to send users a link through email to set up their password for the first time. See Invitation workflow for more information.

You may have a developer or test environment that is not connected up to an SMTP server. For these non-production environments there is an Instance Setting that you can use to restore the ability to set passwords for individual users.

Authentication object model

Relativity provides four tabs or object types that are used to configure authentication. By combining these four object types, the system admin is able to control the Relativity login page and authentication options for the users in the environment.

Authentication Provider Type. Each authentication protocol is represented by an Authentication Provider Type object. You can navigate to the Authentication Provider Type tab in Home mode to see all of the environment's protocols and whether they are enabled or not. Relativity allows you to disable specific Provider Types that you do not intend to use in your environment. As a best practice you should disable any Provider Types that will not be used.

Authentication Provider. Authentication Providers allow you to configure the specific settings for a login protocol. For example, you can add the Password Provider to your environment that allows you to set minimum and maximum password length, password history settings, and more. Some protocols have multiple configuration options, while others have very few. You can have one instance of a Provider in the environment for Password, Integrated Authentication, Active Directory, RSA, and Client Certificate.

Providers are also used to add OpenID Connect and SAML 2.0 external identity providers. Unlike the previous five protocols, you can have as many of these Providers as you wish in an environment.

Login Method. The Login Method list replaces the Authentication Data field on the User page. Users can have one or more Login method objects that binds that user to a particular Authentication Provider. For example, if you have a Password Authentication Provider in the environment, then the Password Login Method contains the specific password for a given user. If you have Azure Active Directory configured as a Provider, then each user's AAD subject identifier would be stored in an associated Login method.

User. The User object still holds the TrustedIPs setting. By setting a TrustedIP for a user, that user will only be able to authenticate with Relativity from that IP range. All other authentication-related fields have been moved from the User object to the Provider and Method objects.