Salesforce Email Integration Security Guide PDF

1m ago
2 Views
0 Downloads
712.08 KB
24 Pages
Transcription

Salesforce Email IntegrationSecurity GuideSalesforce, Spring ’[email protected] updated: March 16, 2021

Copyright 2000–2020 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc.,as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.

CONTENTSSecurity Guide Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Outlook Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Outlook Integration without Public Exchange Web Services (Pilot)First-Time User Authentication Login Flow . . . . . . . . . . . . . . .Outlook Integration with an EWS Endpoint . . . . . . . . . . . . . . .Configuration Requirements . . . . . . . . . . . . . . . . . . . . .Configuration Requirements for Outlook on the Web . . . . .Logging Emails with Attachments to Salesforce Flow . . . . .APIs Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Exchange Web Services (EWS) . . . . . . . . . . . . . . . . . . . .EWS APIs Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245566888Gmail Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Configuration Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Email Integrations with an Inbox License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Org Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Network Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Salesforce and Amazon Web Services (AWS) Servers Storage . . . . . . . . . . . . . . . . . . . . . . . . 12AWS Data Retention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Encryption Key Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Data Storage for Inbox Mobile Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Subsequent Logins for Inbox-Licensed Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Gmail Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Exchange Online (Office 365) Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Microsoft Exchange On-Premises Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17More About the OAuth Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Salesforce AWS Server Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Mobile Device and Application Management and Inbox . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Mobile App Data Removal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

SECURITY GUIDE OVERVIEWThe Salesforce integration with Outlook and Gmail helps sales reps manage their sales more efficiently, regardless of where they chooseto complete their work. The integrations with Outlook and Gmail are available at no cost with Sales Cloud.This document covers technical and security guidelines for: The Outlook and Gmail integrations. Desktop and mobile solutions for when an Inbox license is provisioned. An Inbox license is available with Sales Cloud Einstein, HighVelocity Sales, and as a standalone license.The addition of an Inbox license provides: More features available in the Outlook and Gmail integrations to increase sales reps’ productivity while they’re working in Outlookand Gmail. Access to select Inbox features in email from Lightning Experience. Access to Inbox mobile app.Complete information, including setup steps, considerations, and details about the features are available in Salesforce Help.Salesforce offers other features and solutions to integrate email accounts with Salesforce that complement the Outlook and Gmailintegration and Inbox features. For example, set up Einstein Activity Capture or Lightning Sync to sync contacts and calendar eventsbetween Salesforce. Set up automated email and event logging with Einstein Activity Capture. For security considerations, see theEinstein Activity Capture Security Guide and the Lightning Sync Design and Security Guide.Important: An Inbox license includes Einstein Activity Capture. However, you can enable Inbox with or without the EinsteinActivity Capture feature. You can also enable Einstein Activity Capture without Inbox.1

OUTLOOK INTEGRATIONSetting up the Outlook integration requires access to your Exchange server. How you choose to set up that access depends on theversions of Outlook you use, your internal security policies, and the features that sales reps need within the integration.The Outlook integration add-in is built on the Microsoft Office Add-In Framework. To log emails from Outlook to Salesforce (amongother end-user actions) within that framework, Salesforce is required to make calls to the Exchange server.In a typical Exchange on-premises setup, a firewall blocks access from the internet.Outlook integration taps into the Exchange API and places Exchange Web Services (EWS) calls from Salesforce application servers. Theadd-in calls are placed with an Exchange-provided JSON Web Token (JWT) at the URL provided by Exchange itself, via EWS. The JWTcalls require an exposed EWS endpoint. An EWS endpoint is required to access the features in the integration.Outlook Integration without Public Exchange Web Services (Pilot)First-Time User Authentication Login FlowOutlook Integration with an EWS EndpointOutlook Integration without Public Exchange Web Services (Pilot)With recent Microsoft enhancements, in modern versions of Outlook and Exchange the historic EWS server calls can be client calls inthe Office.js API that Outlook provides.2

Outlook IntegrationOutlook Integration without Public Exchange Web Services(Pilot)With the correct versions of Outlook and Exchange, there’s no need to expose an EWS endpoint to power the features in the Outlookintegration. However, a local EWS connection is still required between Outlook and Exchange and the Exchange Metadata URL muststill be publicly exposed.If your Outlook runs JavaScript API v1.8 or later, you use Exchange Online, and don’t use Inbox features, contact your Salesforce accountrepresentative for more details about this configuration.The latest builds of Exchange Online run JavaScript API v1.8, or later. To determine if your Outlook client runs the JavaScript API v1.8 orlater, see Outlook JavaScript API requirement sets.Important: Features available with an Inbox license, such as insert availability and send later, require access to the Exchangeserver, regardless of the Outlook API version. If you have an Inbox license, review Outlook Integration with an EWS Endpoint onpage 5 and Outlook and Gmail Integrations with an Inbox License on page 10.3

Outlook IntegrationFirst-Time User Authentication Login FlowFirst-Time User Authentication Login FlowSalesforce connects to Exchange to authenticate a user via the metadata URL and is a separate consideration from EWS. This diagramdetails the flow for how Exchange is mapped to the corresponding Salesforce user the first time the user loads the Outlook integrationadd-in.This flow applies to all versions of Outlook and Exchange, regardless of the JavaScript API version.This diagram details the flow for how the Exchange mail is mapped to the corresponding Salesforce user the first time they load theOutlook integration add-in.1. The Outlook add-in retrieves an identity token with a simple JavaScript Async(callback, userContext);The JavaScript method requests an Exchange user identity token (a JSON Web Token or JWT) from the Exchange server. The add-inopens the sign-up page in a popup window hosted on Salesforce.2. The user authenticates with their Salesforce credentials.4

Outlook IntegrationOutlook Integration with an EWS Endpoint3. Salesforce prompts the user to connect their Exchange account (specified in the identity token) with the authenticated Salesforceuser.4. The user clicks the prompt, confirming they want to sign in.5. Salesforce serves then validates the Exchange token contents and fetches the public certificate of the metadata URL. Salesforceexpects the EWS endpoint to have a valid certificate. See Salesforce Help for information about supported SSL certificates.6. Salesforce validates the identity token signature by accessing the public signing key from the authentication metadata documenton the Exchange server.When the Exchange server initially provides the JSON Token to the add-in, it specifies the following: An Exchange Metadata Endpoint URL inside the payload part of the token itself The Salesforce add-inThe add-in sends a request to the defined metadata URL to validate the signature. The Exchange metadata URL must be publiclyaccessible for validation of the user’s identity token.To learn more about validating a token, see Microsoft documentation.7. The Exchange to Salesforce user mapping is then stored within the user’s Salesforce org data.Outlook Integration with an EWS EndpointThis section covers the authenticated calls that the Outlook integration add-in uses in the following scenarios. Outlook versions are running JavaScript API 1.7 or earlier. Check which version of the API your Outlook application runs in OutlookJavaScript API requirement sets. Implementations are using Exchange on-premises. You’ve added an Inbox license, which enables features including insert availability, sent later, text shortcuts, and email tracking.These features require access to the Exchange server. Also review Outlook and Gmail Integrations with an Inbox License on page10 in this guide. That section includes security and implementation considerations beyond what is discussed in this section.Important: Without the EWS endpoint in these scenarios, integration users can’t log attachments from the integration or useany Inbox productivity features.Configuration RequirementsConfiguration Requirements for Outlook on the WebLogging Emails with Attachments to Salesforce FlowAPIs UsedExchange Web Services (EWS)EWS APIs UsedConfiguration RequirementsConfiguring the Outlook integration requires the public exposure of URLs. Exchange metadata URL that permits unauthenticated HTTP access. See the First-Time User Authentication Login Flow on page 4 Exchange Web Service URL5

Outlook IntegrationConfiguration Requirements for Outlook on the WebConfiguration Requirements for Outlook on the WebBecause Salesforce makes outgoing calls to Exchange endpoints, each endpoint URL must each have a valid SSL certificate supportedby Salesforce.If your reps use Outlook on the web (also known as the Outlook Web App (OWA)), specify any custom OWA URLs, such as non-Office365 URLs, in the Outlook integration settings in Salesforce setup. Custom URLs don’t require public exposure because only the clientbrowser needs access to Outlook on the web. These settings apply only when if your reps use the integration in Outlook on the web.Logging Emails with Attachments to Salesforce FlowFrom the Outlook integration, users can manually log a selected Outlook email message and its attachments to Salesforce. The add-inuses the following flow to complete the logging:6

Outlook IntegrationLogging Emails with Attachments to Salesforce Flow1. Authenticates with Salesforce (see Login flow) for details.2. Makes an authenticated call to Exchange Web Services (EWS) via the API provided to Outlook add-ins. See Microsoft Office APIdocumentation. Salesforce servers are now allowed to fetch the current email or event to be logged.3. Performs the EWS operations EWS GetItem GetAttachment(s) for the current email or event and its attachments.4. Saves the email or event and the attachments to Salesforce and associates both to the selected Salesforce records.5. Modifies the email or event in Exchange to include the Salesforce record ID in the extended properties of the Exchange object.7

Outlook IntegrationAPIs UsedAPIs UsedWe make client-side API calls via Office.js and server EWS calls, limited to GetItem and GetAttachment operations. The EWS calls that wemake are initiated from the client side and from the Salesforce app servers. A user action triggers these calls in the context of a particularemail or event. The calls coming from the Salesforce app servers to your EWS URL come from the published IP address ranges.The Outlook integration specifies ReadWriteMailbox so that it can read the email or event and its attachments. The Write access is towrite the Salesforce task or event ID back to the Exchange record via an EWS call placed through the Office.js API. See the Office.jsdocumentation for details about the configuration requirements for making this EWS call.Exchange Web Services (EWS)The EWS request contains: HTTP headers– Authorization: Bearer token (from Office.js getCallbackTokenAsync)– User-Agent: ExchangeServicesClient/0.0.0.0 SOAP request body XMLEWS APIs UsedWe make the following calls via EWS to get the email or event and its attachments. We also write the Salesforce record ID to the propertiesof the Exchange item. Click the links for Microsoft documentation about the specific call. GetItem (client side and server side) to get and set AdditionalProperties and the content of the current email message when savingto Salesforce records. GetAttachment (server side) to retrieve the attachments from Exchange and add to Salesforce records (associated with the Salesforceemail message representation). UpdateItem (client side) GetFolder (client side) to get the drafts folder. CreateItem (client side), which we use to create a draft message.“Client side” refers to calls made via the Office.js API makeEwsRequestAsync. “Server side” refers to calls made from Salesforce app serversto EWS endpoint. For these server-side calls, we use a five-minute token from getCallbackTokenAsync.8

GMAIL INTEGRATIONThis section covers login authentication and the authenticated calls that the features in the Gmail integration Chrome extension use. Ifyour email integration includes Inbox, also review the Email Integrations with an Inb

SECURITY GUIDE OVERVIEW The Salesforce integration with Outlook ® and Gmail ™ helps sales reps manage their sales more efficiently, regardless of where they choose to complete their work. The integrations with Outlook and Gmail are available at no cost with Sales Cloud.