Merge pull request #96 from relativitydev/develop

12.3 Release
relativitydev · Jun 1, 2020 · 585ea25 · 585ea25
2 parents a78d503 + 9d65f6f
commit 585ea25
Show file tree

Hide file tree

Showing 9 changed files with 254 additions and 86 deletions.
diff --git a/docs/authorization.md b/docs/authorization.md
@@ -0,0 +1,158 @@
+# Relativity Trace Authorization
+
+This document lists various methods of authorization with Azure services including Exchange Web Services (EWS) and Azure Information Protection (AIP).
+
+### Exchange Web Services (EWS)
+
+Trace offers three methods for authentication and authorization with Exchange: Basic Authentication and 2 forms of OAuth 2.0 using application registrations in Azure.
+
+##### Basic Authentication
+
+With Basic Authentication, Trace will use the username and password configured on the data source to authenticate directly with the configured Exchange server. This authentication method allows Exchange admins to scope which mailboxes Trace has access to by modifying the configured user's permissions.
+
+###### Required Fields on Data Source:
+
+- Username
+- Password
+
+> **NOTE:** Microsoft will no longer allow basic username/password authentication in O365 starting in October 2020 and Data Sources using it will begin failing.
+
+##### OAuth 2.0 - Resource Owner Password Credentials Grant
+
+Using the Resource Owner Password Credentials Grant, Trace will use the username and password configured on the data source to authenticate against an Azure Active Directory authorization server. The authorization server will return an authorization token that Trace will use to make calls against the Exchange server. This authentication method also allows Exchange admins to scope which mailboxes Trace has access to by modifying the configured user's permissions.
+
+###### Required Fields on Data Source:
+
+- Username
+- Password
+-  Exchange Settings - Authorization Client Id 
+-  Exchange Settings - Authorization Tenant Id 
+
+##### OAuth 2.0 -  Client Credentials Grant
+
+Using the Client Credentials Grant, Trace will act as a service principal instead of a user. This means the Trace application will have it's own credentials that are unique to it. Trace will use its own credentials to authenticate against an Azure Active Directory authorization server. The authorization server will return an authorization token that Trace will use to make calls against the Exchange server. This authentication method does not allow Exchange admins to scope which mailboxes Trace has access to and Trace will have access to all mailboxes within the configured Azure Active Directory.
+
+###### Required Fields on Data Source:
+
+- Exchange Settings - Authorization Client Id 
+- Exchange Settings - Authorization Tenant Id 
+- EWS Client Secret
+
+
+
+### Azure Information Protection (AIP)
+
+Trace can authenticate against Azure Information Protection services using only the two OAuth 2.0 authorization methods listed above. The authorization flow is identical to that of each OAuth method EWS, but the authorization token will be used against AIP services instead of Exchange. Additionally, the required fields on the data source differ.
+
+##### OAuth 2.0 - Resource Owner Password Credentials Grant
+
+###### Required Fields on Data Source:
+
+- Username
+- Password
+- AIP Client Id
+- AIP Tenant Id
+
+##### OAuth 2.0 -  Client Credentials Grant
+
+###### Required Fields on Data Source:
+
+- AIP Application Id 
+- AIP Tenant Id
+- AIP Client Secret
+
+## Trace and Azure Application Registrations (OAuth 2.0)
+
+Application Registrations in Azure are a way of authorizing users and services to use certain Azure resources. This documentation assumes a familiarity with Azure Application Registrations. For information on creating an Application Registration, please see here: https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#register-a-new-application-using-the-azure-portal. 
+
+
+
+### Application Registration Configurations Required by Trace
+
+#### General
+
+Trace relies on specific configurations of application registrations to be used for authorization using OAuth 2.0. The following parameters must be set while creating an application registration:
+
+- **Name** : This is the name of your app registration and can be anything. Trace does not rely on the name to identify the app registration.
+- **Account Type** : This should be set to "Accounts in this organizational directory only". If using the ROPC flow, this means that configured user on the data source in Trace must belong to the Azure Active Directory where you are creating the application registration.
+- **Redirect URI** : A redirect URI is not required for use with Trace. This may be left as a default value.
+
+If using the ROPC authorization method, the application registration must be enabled be treated as a public client. This can be done under the advanced settings on the "Authentication" blade in your application registration by selecting "Yes" next to "Treat application as a public client".
+
+![1590532045656](media/authorization/1590532045656.png)
+
+#### API Permissions
+
+The API Permissions blade in the application registrations config allows you to assign permissions to API endpoints in Azure. Each permission can be added by navigating to the API permissions blade and clicking "Add a permission". This will cause a pop-up where you can navigate to the API endpoint that is needed scoped permissions can be granted.
+
+##### Exchange Web Services (EWS)
+
+The API permissions required by Trace for Exchange vary depending on the authorization flow you are using.
+
+###### Resource Owner Password Credential
+
+To configure ROPC authorization in Trace, your application registration will need the following permission:
+
+- API : Exchange
+  - Delegated permissions
+    - EWS
+      - EWS.AccessAsUser.All
+
+###### Client Credential
+
+To configure Client Credential authorization in Trace, your application registration will need the following permission:
+
+- API : Exchange
+  - Application permissions
+    - full_access_as_app
+
+This permission will require an Azure Portal admin to grant consent for your application registration to use it.
+
+##### Azure Information Protection (AIP)
+
+The API permissions required by Trace for AIP vary depending on the authorization flow you are using.
+
+###### Resource Owner Password Credential
+
+To configure ROPC authorization in Trace, your application registration will need the following permissions:
+
+- API : Azure Rights Management Services
+  - Delegated permissions 
+    -  user_impersonation
+- API: Microsoft Information Protection Sync Service
+  - Delegate permissions
+    - UnifiedPolicy
+      - UnifiedPolicy.User.Read
+
+These permissions will require an Azure Portal admin to grant consent for your application registration to use them.
+
+###### Client Credential
+
+To configure Client Credential authorization in Trace, your application registration will need the following permission:
+
+- API : Azure Rights Management Services
+  - Application permissions
+    - Content
+      - Content.SuperUser
+- API: Microsoft Information Protection Sync Service
+  - Application permissions
+    - UnifiedPolicy
+      - UnifiedPolicy.Tenant.Read
+
+These permissions will require an Azure Portal admin to grant consent for your application registration to use them.
+
+### Configuration in Trace
+
+To use either OAuth 2.0 authorization method in Trace, you will need to supply all of the required fields listed under the required fields section above. 
+
+The Client ID required fields for both AIP and EWS refer to the ID of your application registration. This value is unique per app registration and can be found on the landing page of your application registration in Azure next to "Application (client) ID" (it will be a GUID).
+
+
+
+The Tenant ID required fields for both AIP and EWS refer to the ID of your Azure Active Directory. This value is shared by all app registrations in your Azure Active Directory and can be found on the landing page of your application registration in Azure nex to "Directory (tenant) ID" (it will be a GUID).
+
+
+
+#### Client Secret for Client Credentials Grant
+
+If using the Client Credentials grant with AIP or EWS, there is a Client Secret value required. To get a value for your Client Secret, navigate to the "Certificates & secrets" blade under your application registration. Once there, you can click "New client secret", which will generate a random client secret string. Copy the value and paste it into the corresponding Client Secret field in Trace. You will not be able to view the secret value after leaving the page.
diff --git a/docs/index.md b/docs/index.md
@@ -5,9 +5,10 @@
   2. [Relativity Trace Release Notes](https://relativitydev.github.io/relativity-trace-documentation/release_notes)
 
 ## Data Ingestion
-  1. [Relativity Trace Data Source User Guide](https://relativitydev.github.io/relativity-trace-documentation/trace_connectors_user_guide)
-  2. [Relativity Trace API](https://relativitydev.github.io/relativity-trace-documentation/proactive_ingestion_api_documentation)
-  3. [Relativity Trace Shipper Service Documentation](https://relativitydev.github.io/relativity-trace-documentation/trace_shipper_service)
+  1. [Relativity Trace Data Source](https://relativitydev.github.io/relativity-trace-documentation/trace_connectors_user_guide)
+  2. [Relativity Trace Authorization](https://relativitydev.github.io/relativity-trace-documentation/authorization)
+  3. [Relativity Trace API](https://relativitydev.github.io/relativity-trace-documentation/proactive_ingestion_api_documentation)
+  4. [Relativity Trace Shipper Service](https://relativitydev.github.io/relativity-trace-documentation/trace_shipper_service)
 
 ## Support
   1. [Relativity Trace Troubleshooting Guide](https://relativitydev.github.io/relativity-trace-documentation/troubleshooting_guide)

diff --git a/docs/media/authorization/1590532045656.png b/docs/media/authorization/1590532045656.png
diff --git a/docs/media/user_documentation/9631ef5e-4ec9-4096-8c52-0af0377437fc.png b/docs/media/user_documentation/9631ef5e-4ec9-4096-8c52-0af0377437fc.png
diff --git a/docs/media/user_documentation/9631ef5e-4ec9-4096-8c52-0af0377437fc_annotated.png b/docs/media/user_documentation/9631ef5e-4ec9-4096-8c52-0af0377437fc_annotated.png
diff --git a/docs/media/user_documentation/ed6d268b-1439-4a66-aab2-7c8904bbd808.png b/docs/media/user_documentation/ed6d268b-1439-4a66-aab2-7c8904bbd808.png
diff --git a/docs/media/user_documentation/ed6d268b-1439-4a66-aab2-7c8904bbd808_annotated.png b/docs/media/user_documentation/ed6d268b-1439-4a66-aab2-7c8904bbd808_annotated.png
diff --git a/docs/release_notes.md b/docs/release_notes.md
@@ -1,6 +1,7 @@
 # Relativity Trace Release Notes
 
-- [12.2.0.13 (27 April 2020)](#122013-27-april-2020)
+- [12.3.0.3 (1 June 2020)](#12303-1-june-2020)
+- [12.2.0.13 (27 April 2020 - DEPRECATED)](#122013-27-april-2020---deprecated)
 - [12.1.0.13 (30 March 2020) - DEPRECATED](#121013-30-march-2020---deprecated)
 - [12.0.8.2 (24 February 2020) - DEPRECATED](#12082-24-february-2020---deprecated)
 - [12.0.5.2 (24 October 2019) - DEPRECATED](#12052-24-october-2019---deprecated)
@@ -10,7 +11,35 @@
 - [11.2.6.1 (17 June 2019) - DEPRECATED](#11261-17-june-2019---deprecated)
 - [11.2.4.4 (10 June 2019) - DEPRECATED](#11244-10-june-2019---deprecated)
 
-# 12.2.0.13 (27 April 2020)
+# 12.3.0.3 (1 June 2020)
+
+**Relativity Compatibility**
+
+- **≥ 10.3.287.3**
+
+**Features**
+
+- Microsoft Exchange/O365 Data Source now supports OAuth 2.0 including support for client credential flow where Relativity Trace is registered as a service principal
+- Embedded File Behavior option on Data Sources allows customers to control extraction behavior of embedded content within communications and attachments to preventing the creation of excessive and unneeded files
+
+**Enhancements**
+
+- Data Disposal action is now supported for custom Data Sources
+- Data Batch Retry is now supported across fileshares for custom Data Sources
+- Added automatic retry of failures to decrypt AIP messages to improve reliability
+- Increased security for storing credentials on Data Sources
+
+**Defect Fixes**
+
+- Fixed issue with load file path on failed Data Batches from custom Data Sources that would prevent retry
+- Added an automatic retry of Data Batches stuck in Enriching status for more than 24 hours if they have not yet been retried
+- Trace Shipper now logs an error instead of overwriting the existing file if a file with the same name already exists in the destination folder
+
+**Upgrade Considerations**
+
+- All Office 365 customers should migrate to use of OAuth 2.0. Microsoft will no longer allow basic username/password authentication in O365 starting in October 2020 and Data Sources using it will begin failing. Review [Relativity Trace Authorization](https://relativitydev.github.io/relativity-trace-documentation/authorization) documentation for OAuth 2.0 information.
+
+# 12.2.0.13 (27 April 2020) - DEPRECATED
 
 **Relativity Compatibility**