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.

This topic contains the following sections:

If you are upgrading from a prior version of Relativity, there are some important differences to be aware of. See the following pages for a list of those points.

See also 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 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 is automatically initiated if the user logs in from a specific IP address range.
  • Client Certificate – an external method requiring a smart card and PIN. This method validates from an IIS server. It may also be referred to as smart card authentication.
  • 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 can be used to connect to providers such as Azure Active Directory. See 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 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 – limit access to the Relativity application based on the user's source IP address.

Authentication object model

Relativity provides several tabs or object types that are used to configure authentication. By combining these 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. In Relativity you can 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.

Note: Users log in to the Relativity Desktop Client (RDC) with the same provider method as they have with Relativity. The RDC supports most Relativity authentication providers, such as password, Integrated Authentication, and OpenID Connect, by displaying the Relativity login page within the RDC as a dialog window. The only provider that doesn't work with the RDC is SAML because the Relativity’s IdP-initiated SAML doesn't display the Relativity login page directly.

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 to set minimum and maximum password length, password history settings, and more. Some protocols have multiple configuration options, while others have very few. Every instance of Relativity has Default Password, Default Integrated Authentication, Default Active Directory, Default RSA, and Default Smart Card providers. You can't have additional (non-default) providers of those types.

You can 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 AuthenticationData field on the User page has been replaced with the Login Method associated list. 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, the Password Login Method contains the specific password for a given user. If you have Azure Active Directory configured as a Provider, 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.

Authentication object permissions

These default object permissions are recommended for managing user authentication:

  • System admins only – full permissions, including view, update, delete, secure, add
    • Authentication Provider Type
    • Authentication Provider
    • Login Method
    • OAuth2 Clients
  • Anyone with the ability to view a user – view
    • Authentication Provider Type
    • Authentication Provider
    • Login Method
  • Anyone with the ability to edit a user – update, delete, add
    • Login Method

Configuring Relativity authentication

System admins must assign users at least one authentication method in order for users to log in. To create and to assign methods, follow these steps.

  1. Enable authentication provider types. Authentication Provider Types are Relativity dynamic object (RDOs) types that permit authentication processes. You can only enable or disable each provider type. See Enable authentication provider types. By default, each authentication provider type is enabled.
  2. Create authentication providers. Authentication Providers are instances of an authentication provider type. Each provider type that you plan to use requires creating an instance of that type. See Creating authentication providers.
  3. Assign a login method to individual users. You assign an authentication method to each user for them to log in with. Each user must have at least one authentication method in order for them to log in but you may assign multiple methods. See Managing user authentication methods.

Enable authentication provider types

Authentication Provider Types are Relativity dynamic object (RDOs) types that permit authentication methods for users to log in with. You can't add or delete provider types, only enable or disable them. By default, provider types are enabled. You enable methods in two places: The authentication provider type tab and the authentication providers tab. To be enabled, the method has to be enabled in both places.

To enable or disable an authentication provider type:

  1. Select Authentication Provider Type tab.
  2. Click on a provider type name. The Authentication Provider Information section appears.
  3. Click Edit.
  4. Select Enabled status Yes or No. Yes enables those methods, and No disables them throughout the Relativity instance.
  5. Click Save.

Creating authentication providers

Authentication providers are instances of authentication provider types. You create only the instances of the provider types you need. For example, if you plan to support only password methods, you only have to create an authentication provider for passwords, and not for any other provider types.

Note: Adding a new authentication provider of the same type overwrites the existing ones of the same type.

You may only have one instance of each provider type. The exceptions are for OpenID Provider and SAML 2.0 provided types. You can have multiple instances of those if they have different names.

To create an Authentication Provider:

  1. Select the Authentication Provider tab.
  2. Click the New Authentication Provider button.
  3. Enter a Name. This is the friendly name of the provider instance.
  4. Optionally select the Enabled status. By default, each authentication provider is enabled. If not enabled, then users can't log in with that method.
  5. Select a Provider Type from among the authentication provider types. You can select OpenID Connect or SAML2.
    The Authentication Provider Settings section appears.
  6. Set the Authentication Provider Settings, if any. See Authentication provider settings for the specific method.
  7. Click Save.

Authentication provider settings

Authentication providers may have associated settings that you can configure and applies to all instances of that authentication provider.

Each provider instance has at least one setting: Enabled. If set to Yes, this authentication provider is available. If No, you can't use this method to log in with. To enable an instance both this setting and the Enabled for the Authentication Provider must be set to Yes. If either one is set to No, that method isn't available for the user.

Not all authentication providers have additional settings.

Select your authentication method:

Default Integrated Authentication provider

No authentication provider settings.

Default Active Directory provider

No authentication provider settings.

Default RSA provider

No authentication provider settings.

You may need to set RSA configuration files to the web server prior to users logging in with this method. See RSA configuration for additional details.

Default Password provider

  • Minimum Password Length – sets the minimum number of characters for a password.
  • Maximum Password Length – sets the maximum number of characters for a password.
  • Maximum Password Attempts Before Reset Required – sets the maximum number of consecutive unsuccessful login attempts before being locked out. You must send the user a password reset request before they can attempt to log in again.
  • Maximum Password Age (in days) -sets the maximum number of days a password remains valid. The user will be prompted for a new password on a logon at the expiration date. If set to zero, the password does not expire.
  • Users Can Change Password Default – enables the user to change their password.
  • Allow Password Recovery via Email – enables the user to use email to recover a forgotten password. Yes displays the Forgot Password link on the user's login screen.
  • Password Recovery Request Limit – sets the maximum number of password resets before Relativity locks out the user. You must send the user a password reset request before they can attempt to log in again. This value resets to zero on each successful log in.
  • Maximum Password History – sets the maximum number of previous passwords that users can't use for a new password. The default value of zero enables any previous password.
  • Additional Work Factor – increases the number of encryption hashes. Relativity already provides several built in hash levels represented by the default zero value. Changing this value to 1, 2, or 3 adds additional encryption protection but may significantly increase login time.
  • Note: The following non-alpha-numeric characters are not allowed: \, ", <, > in passwords.

Default smart card provider

  • Display on Login Page – determines if the client certificate button displays in the logon screen.
  • Login Screen Button Text – sets the client certificate button text.

The example below illustrates the relationship between the two settings and the logon screen.

fields on login dialog for client certificate provider

OpenID Connect provider

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. Clients can verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User. You can use any provider that supports the OpenID Connect protocol. The examples here use Microsoft Azure AD.

Note: OpenID Connect 1.0 authentication providers are not compatible with Relativity User Load Balancing (RULB).

Configuring your external identity provider

  1. Log in as an administrator in Azure.
  2. Select the ActiveDirectory extension.
  3. Click the Applications tab.
  4. Click the Add button near the bottom.
  5. Click Add an application my organization is developing.
  6. Enter the friendly name of your application.
  7. Ensure the Type is set to Web Application And/Or Web API.
  8. Press the arrow button.
  9. Enter your Relativity instance URL for the Sign-on URL.
  10. Enter a unique identifier for your application in the App ID URI.
  11. Click the check button.
  12. Click the Configure tab of the new application.
  13. Note the Application ID, it will be used later as the Client ID.
  14. Click on View Endpoints in the bottom.
  15. Copy the OAUTH 2.0 AUTHORIZATIONENDPOINT
  16. Trim off the oauth2/authorize from the end of the copied endpoint. For example:
    https://login.microsoftonline.com/8a3fa923-3223-4978-9d4d-fa012e19898b/oauth2/authorize
    https://login.microsoftonline.com/8a3fa923-3223-4978-9d4d-fa012e19898b/
    The Authority, oauth2/authorize, is required later.

Configuring this method in Relativity

  1. Enter these settings:
    • Site URL (in the Authentication Provider Information section) - sets the URL users enter into the browser to access this instances of Relativity.
    • OAuth2 Flow – set to Implicit. Azure AD doesn’t have a secret so Implicit must be used.
    • Client Secret – leave empty. Azure AD doesn’t use this secret value.
    • Client ID – enter the Azure AD's Application ID.
    • Authority URL – enter the Authority from the trimmed OAUTH 2.0 AUTHORIZATIONENDPOINT from step 16 above.
    • Subject Claim Type -for Azure AD, use oid. For other authentication provider systems, we recommend using email.
    • Redirect URL – sets the URL to the Relativity entry point. This value is read only and is generated by Relativity.
    • Display on Login Screen – determines if the client certificate button displays the on the logon screen.
    • Login Screen Button Text – sets the client certificate button text.
  2. Perform an IIS Reset on all web servers, so that proper configuration changes can take place for setting up your provider.

Completing your external identity provider set up

  1. Log in to Azure AD and navigate to the application you created earlier, if you have closed the window.
  2. Enter the Redirect URL from Relativity into the Reply URL list. Azure AD will only approve authentication requests to URLs that are listed in the Reply URL. Azure AD will allow you register multiple URLs (and thus we can reuse this for multiple instances of Relativity).
  3. Click Save.

Example: Setting up Relativity as an OpenID Connect authentication provider

Relativity can be set up as an OpenID Connect authentication provider to log users into a different Relativity instance. For example you can set up an on-premises environment (primary instance) to act as authentication provider for a RelativityOne cloud instance (secondary instance).

Before you begin:

  • Ensure that the primary instance is set up to use HTTPS.
  • Verify that the secondary instance can resolve the host address of the primary instance.
  • Confirm that the authenticated users are defined in both systems.

Complete these steps:

  1. Navigate to the primary instance and set up an OAuth2 client. You must specify Code as the OAuth2 Flow.
    Note that initially you don't have the redirect URL value (you get it when you set up the Authentication Provider on the secondary instance), so specify any placeholder URL instead. For more information, see OAuth2 clients.

  2. After you save the OAuth2 client, note the generated values of the Client Id and Client Secret. They are required to set up the authentication provider in the secondary instance.
  3. Navigate to the secondary instance and configure a new OpenID Connect authentication provider using the Client Id and Client Secret values from the previous step. Note that the OAuth2 Flow values must also be Code, and the Authority URL must point to the Relativity Identity service of the primary instance.

  4. After you save the provider, note the generated value of the Redirect URL. It is required to complete the OAuth2 client setup in the primary instance.
  5. Set up the user(s) to use the Authentication Provider as the Login Method, specifying the user's email (Relativity user ID) as the OpenID Connect Subject field value. For more information, see Managing user authentication methods.
  6. Reset the IIS server for the secondary instance.
  7. Navigate back to the primary instance and update the OAuth2 provider with the Redirect URL.

  8. In the primary instance, set up a federated instance pointing to the secondary Relativity instance. Note the use of the Home Realm Discovery (HRD) URL parameter to provide a single sign-on experience. The Home Realm discovery URL is generated when the Authentication Provider is created and can be found in the Authentication Provider Information section of the Authentication Provider page. For more information, see Federated instances.

  9. Navigate back to the secondary instance and set up a federated instance pointing to the primary Relativity instance. Don't set up the HRD redirect for that federated instance.
  10. Log out of the secondary instance.
  11. Use the federated instance link to log in to the secondary instance from the primary instance.

  12. Use the federated instance link in the secondary instance to return to primary instance.

You have now configured a Relativity environment to serve as an authentication provider for another Relativity instance.

SAML 2.0 provider

SAML is an open-standard format for exchanging authentication and authorization data between an identity provider (IdP) and a service provider (SP). As a service provider, Relativity supports SAML IdP-initiated single sign-on (SSO). SP-initiated SSO is not supported. Relativity uses SAML assertions (tokens) to verify the users mapped to the identity provider.

SAML assertions contain information on the identity of the individual who has logged in. Assertions also contain the identity provider issuing the assertion, known in Relativity as the Issuer URL. Each Assertion is typically prepared for a specific receiver, known as the Audience. Assertion protect this information by cryptography signing it. An Assertion is only valid if it is from a known Issuer URL to the expected Audience and correctly signed.

Note: SAML assertions must be cryptographically signed for Relativity to verify their authenticity. Make sure your SAML IdP is configured accordingly.

You can use Relativity with any SAML 2.0-compliant IdP, such as Centrify, Okta, Microsoft Active Directory Federation Service (ADFS), or OneLogin.

Note: SAML 2.0 authentication providers are not compatible with Relativity User Load Balancing (RULB).

The following sections provides the guidelines for integrating Relativity with Okta and ADFS.

Example: Configuring Okta as a SAML 2.0 identity provider

This is an example of configuring Okta.

Initial configuration:

  1. In Okta admin console, create a SAML 2.0 application:

  2. Specify these SAML settings:
    • For the single sign-on URL, for enter your Relativity Instance URL. This is the URL that is used for public access to go to your web servers.
    • For Audience URI (SP Entity ID) put in a unique identifier, such as the URL for your instance. Note this value for later.

      Note: Audience URI is case-sensitive. Specifying /relativity instead of /Relativity can break your authentication.

    • Application username you would like to use for logging in. In this use case, select Email.
    • For Assertion Signature, select Signed.

  3. You have now partially configured you application in Okta to set up logging in to Relativity. You must now configure the SAML provider in Relativity. You need these Okta values:
    • The Audience URI (SP Entity ID, from the previous step).
    • The Identity Provider Issuer (In Okta, click View Setup Instructions on the Sign On tab).
    • The X.509 Certificate (also in Setup Instructions).

Next, set up the SAML 2.0 authentication provider in Relativity:

  1. Log in to Relativity with system admin credentials.
  2. Open the Authentication Provider tab.
  3. Click New Authentication Provider. The Authentication Provider Information form opens.
  4. Enter a name for your provider.
  5. Select SAML2 from the Provider Type dropdown.

  6. Enter the site URL. This is the URL users enter into the browser to access this instances of Relativity.
  7. Enter the Audience URI (SP Entity ID) from Okta in the Audience field.
  8. Enter the Identity Provider Issuer from Okta in the Issuer URL with.
  9. Enter the X.509 certificate from in Okta in the Certificate field.
  10. (Optional) If you are using a specific user identifier claim that is not the default claim, enter it as the Subject Claim Type.
  11. Click Save.
  12. Note the Redirect URL on your new authentication provider.

  13. Perform an IIS reset on all web servers, so that the configuration setting changes provider take effect.

You have now set up your Relativity instance to list for SAML 2.0 assertions at a given endpoint on your server (the Redirect URL).

Next, finish setting up the SAML IdP in Okta:

  1. Log in to Okta and navigate to the application you created earlier.
  2. Update the single sign-on URL to be the Redirect URL given to us by Relativity on the authentication provider you have created.

You have now configured Okta to send SAML 2.0 assertions to your Relativity instance, and Relativity is set up to verify the SAML assertions.

Note: You must also assign Okta users to the SAML application, and then map the users to SAML login method in Relativity. When configuring the login method, you must specify the user's email in the SAML2 Subject field (if you select Email as the application username in Okta). For more information, see Managing user authentication methods.

Example: Configuring ADFS as a SAML 2.0 identity provider

You can also configure ADFS as a SAML 2.0 authentication provider for Relativity.

Note these terminology difference between Relativity and ADFS:

ADFS
Audience Relying Party Identifier(s) https://relativity.example.com/Relativity
Redirect URL End-Point URL https://relativity.example.com/Relativity/Identity/<random string>
Issuer URL Services Trust End-Point (SAML) http://<adfs-service>/adfs/services/trust
SAML Subject Name Claim Type Name ID, E-Mail Address, UPN (Leave blank in Relativity SAML Provider configuration)
n/a Claim Rules Incoming, Transformation, Outgoing Claim Rules (see below)

When setting up claim rules, you must send Name ID as default claim type for Relativity. Use these guidelines:

  1. Add Send LDAP Attributes As Claims: Select Email Addresses or User-Principal-Name to E-Mail Address from the AD store.
  2. Add Pass Thru Claim for E-Mail Address or a Transforming claim.
  3. Add Transforming Claim (from E-Mail Address to Name ID).