Authentication

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.
• 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.

Notes:
• When implementing single sign-on (SSO) across Relativity instances, the following scenarios are supported:
  • Identity Provider-initiated SSO using SAML 2.0
  • ID provider and service provider-initiated SSO with OpenID Connect

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. 
  • Mode—always required or require only for non-trusted IPs
  • Method—authenticator app or email. For more information, see the authenticator app's documentation.

  

• Trusted IP Range—limit access to the Relativity application based on the user's source IP address.

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 does not work with the RDC is SAML because the Relativity’s IdP-initiated SAML does not 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 cannot 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.

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

Authentication Provider Types are Relativity dynamic object (RDOs) types that permit authentication methods for users to log in with. You cannot 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.

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 cannot 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.

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.

1. Log in to Azure Portal.
2. Click Azure Active Directory.
   

   (Click to expand.)

   

3. Click App registrations.

   (Click to expand.)

   

4. Click New registration.
5. Give the application a name.

   (Click to expand.)

   

6. Click Register.

7. Copy the Application (client) ID.

   (Click to expand.)

   

8. Click the Endpoints button.

   (Click to expand.)

   

9. Copy the OAuth 2.0 authorization endpoint (v2) URL.

10. Trim the oauth2/v2.0/authorize from the URL. For example:

    https://login.microsoftonline.com/8a3fa923-3223-4978-9d4d-fa012e19898b/oauth2/authorize
    https://login.microsoftonline.com/8a3fa923-3223-4978-9d4d-fa012e19898b/

Review the following list of settings that display on the Authentication Provider form. You can configure or update these settings based on your authentication needs.

Authentication Provider Information

• Name—enter a user-friendly name for the authentication provider.
• Provider Type—select OpenID Connect.
• Enabled—the provider is enabled by default. However, you can disable it.
• Site URL—set the URL that users enter in the browser to access an instance of Relativity.

Authentication Provider Settings

• OAuth2 Flow—select either Implicit or Code.
• Client ID—enter the Azure AD's Application ID.
• Display on Login Screen—determines if the OpenID Connect button displays on the login page.
• Login Screen Button Text—determines the text that appears on the button displayed on the login page.
• Authority URL—enter the Authority from the trimmed OAUTH 2.0 AUTHORIZATIONENDPOINT from step 9 in Configuring your external identity provider. See Configuring your external identity provider.
• Scopes—the default value for this field is openid. The openid checkbox must be selected because it is a required setting. However, you can also select the email or profile option.

  The identity provider responds with the claims associated with the scopes that you request. In other words, the scopes translate into claims that you can use.

• Subject Claim Type—the default value for this field is sub. Enter one of the following values based on the scopes that you set:
  • If you selected only OpenID in the Scopes field, this field must be set to sub.
  • If you selected OpenID and email in the Scopes field, set this field to upn.
  • If you selected OpenID and profile in the Scopes field, set this field to a property available from the identity provider. These properties differ for each provider.

  The identity provider sends an identity token to you, which contains the claims for your selected scopes. When you request only the OpenID scope, then sub is used as the claim type. It often represents a unique identifier for the user within your system. If you are using Azure AD, then see Microsoft identity platform ID tokens for a full list of token identifiers.

1. Log in to Azure AD and navigate to the application you created earlier, if you have closed the window.

2. Click Authentication.

   (Click to expand.)

   

3. Add your Redirect URL from the Relativity Authentication Provider.

   Note: Leave the Type as Web.

4. Complete the scenario that matches the value you selected for OAuth2 Flow.

   • Scenario: you selected Implicit for OAuth2 Flow.
     1. Check the ID Tokens box.

        (Click to expand.)

        

     2. Click Save.
   • Scenario: you selected Code for OAuth2 Flow.

     1. Click Certificates & Secrets.

     2. Click New client secret.

        

     3. Click Add.

        

     4. Copy the client secret value.

     5. Navigate back to the Authentication Provider in Relativity.

     6. Click Edit.

     7. Paste the value for Client Secret with the value from step 4.

        

     8. Click Save.

1. Click Azure Active Directory.
2. Click Enterprise Applications.
3. Click into the application that you have created for Relativity authentication.
4. Click Users and groups.

   

5. Click Add user.

   

6. Select your users.
7. Click Assign.

To configure an OpenID Connect provider for Relativity:

1. Navigate to the primary instance and set up an OAuth2 client. You must specify Implicit as the OAuth2 Flow.
   Initially, you do not have the redirect URL value. You get it when you set up the Authentication Provider on the secondary instance. Specify any placeholder URL instead. For more information, see OAuth2 clients.

2. After you save the OAuth2 client, note the generated value of the Client Id. This is 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 value from the previous step.
   The OAuth2 Flow values must also be Implicit, and the Authority URL must point to the Relativity Identity service of the primary instance. An example of a Redirect URL is https://mycompany.relativity.one/Relativity/Identity.
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 users 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. Navigate back to the primary instance and update the OAuth2 provider with the Redirect URL.

   

7. 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.
8. Navigate back to the secondary instance and set up a federated instance pointing to the primary Relativity instance. Do not set up the HRD redirect for that federated instance.
9. Log out of the secondary instance.
10. Use the federated instance link to log in to the secondary instance from the primary instance.

    

11. 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.

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

Note these terminology difference between Relativity and ADFS:

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.