Salesforce 集成篇零基础学习（一）Connected App

本篇参考：

https://zhuanlan.zhihu.com/p/89020647

https://trailhead.salesforce.com/content/learn/modules/connected-app-basics

https://help.salesforce.com/articleView?id=sf.connected_app_overview.htm&type=5

我曾经写过好几篇博客涉及到connected app的使用，比如

salesforce 零基础学习（三十三）通过REST方式访问外部数据以及JAVA通过rest方式访问salesforce

Salesforce Admin篇(四) Security 之Two-Factor Authentication & Single Sign On

这两篇确实用到了 connected app，但是当时只是根据官方的文档去进行相关的配置，大概了解干什么的，细节的知识却学习的很惭愧，最近有涉及到集成的知识。发现基础的概念很多都特别模糊，比如 Oauth2.0， connected app等等。所以准备慢慢找时间系统的学习一下集成的知识，夯实一下自己的知识库，从知道怎么实现到慢慢的了解基础的原理。

 一. Oauth2.0

我们涉及到和其他的平台交互的时候，很多时候都会使用到Oauth。Oauth有1.0和2.0两个版本，现在大部分都使用2.0版本，需要注意1.0和2.0两个协议并不互相兼容，我们文章涉及到的内容也是基于 Oauth2.0.那 Oauth是什么？API还是？

Oauth是一个开放的协议，用于授权一个应用从一个受保护的资源通过交换令牌(token)的方式去访问数据。这里有一个概念叫做 令牌(token)，本质上就是授予客户端应用程序的权限。我们传统方式去访问受限制资源是通过账号密码方式，这种方式不方便，某种程度上也不是特别安全。资源服务器可以验证令牌（token），并允许客户端应用程序访问定义（scope）的受保护资源。这里可以看到，验证了令牌以后不是为所欲为，而是只能访问相关scope范围内的受保护的资源，而不是扩充到管理员权限，从而也实现了权限的访问设置。在Salesforce中，我们可以使用OAuth授权来批准客户端应用程序对组织受保护资源的访问权限。上面的知乎上的文章也有对Oauth的中文的理解。

针对 Oauth通过几个小点进行讲解。

1. OAuth Authorization Flows（Oauth的授权流程）

Oauth流拥有多种类型，每个 Oauth 流都提供了不同的流程来批准对客户端应用程序的访问，但一般来说，流由三个主要步骤组成。

1. 要启动授权流，客户端应用程序会请求访问受保护的资源。
2. 作为响应，授权服务器向客户端应用程序授予访问标记。
3. 然后，资源服务器验证这些访问标记，并批准对受保护资源的访问。

以官方的一个例子,即我们打开 Salesforce 移动应用程序访问您的 Salesforce 数据时，进行Oauth授权流程更好的说明。

详情描述如下：salesforce除了网页端访问以外，还可以进行手机端访问。比如我们手机端下载了salesforce app，第一次操作时，输入账号密码登录想要获取sf的数据，我们这时就会启动一个Oauth2.0的授权流程。在这个流程当中，有这样的几个角色：

• 手机app：请求访问权限的客户端；
• sf数据：受保护的资源；
• 你的sf的org：授权的server，用来颁发授权访问的令牌(token)来授予手机app的访问权限；
• 你：资源所有者，用来允许手机app来随时访问和管理你的数据。

角色说完以后，接下来模拟一下步骤，步骤如下：

1. 你手机端打开app，手机的授权提示将会展示让你输入账号和密码；
2. 你输入了正确的账号和密码以后点击了确定；
3. sf手机app发送了你的凭证到了sf，并且初始化了Oauth授权流程；
4. sf将会发送一个确认授权验证的页面，包含了允许mobile app访问以及refresh token的确认授权；
5. 你点击了OK，批准了访问授权；
6. mobile app启用，可以看到以及操作你授权的数据。

以上的步骤便进行了一个Oauth授权的流程操作。

所以小伙伴们，当我们在手机端操作看到了类似这个页面以后，其实应该了解到背后的原理就是 Oauth针对手机移动应用的授权流程。

通过上面的连接中我们可以知道 Oauth2.0操作时，token的时间通常都是短时间有效的，那如果超过了这个时间，token失效，怎么办？？？会不会有这种担忧。这里就要简单的描述一下这个token。token可以简单的分成2种：1种是access token，用于客户端进行请求用的，这个token是短时有效的；2种是refresh token，这个通常都会设置长时间有效的。当access token失效以后我们可以通过refresh token去获取新的access token即可。所以上面展示了第一次进入登录授权的操作，下面说一下以后通过手机app进入的流程。

1. 你打开了手机app；
2. session如果是可用的，mobile app立马启动；如果session失效了，mobile app通过refresh token功能从初始化的授权中获取更新以后的session，然后mobile app启动。

上面我们描述了通过手机端app进行Oauth授权的流程，当然Oauth不止是简简单单的运用于此，实际上 Oauth太强大了，我们在不同的条件下应该选择不同的Oauth授权流程。以下的用例是官方提供的，为我们应用程序中可以选择正确的流程。https://help.salesforce.com/articleView?id=sf.remoteaccess_oauth_web_server_flow.htm&type=5

2. token（令牌）

token的作用为授权对受保护的资源的访问。授权后，连接的应用程序代表客户端接收标记。token 搭配着scope进一步定义了连接的应用程序可以访问的受保护资源的类型。scope的概念我们下面讲。Oauth中授权的server可以提供的token主要有以下的几种类型：

• Authorization code：授权服务器创建授权代码，这是一个短期token，并在成功身份验证后将其传递给客户端。客户端会将授权码发送到授权服务器，以获取access token或者refresh token；
• Access token：客户端获得授权后，Salesforce 会向客户端发送Access token。客户端将Access token传递给资源服务器，以请求访问受保护的资源。在授予客户端访问权限之前，资源服务器先验证访问标记和附加权限。Access token的使用寿命比Authorization code长，通常为几分钟或数小时。当Access token过期时，如果还使用 Access token获取资源将会失败，客户端必须通过使用refresh token或重新初始化授权流来获取新的Access token。

  收到Access token后，客户端可以使用以下方法之一请求访问。

  • 对于 REST API，使用带有以下格式的 header：Authorization: Bearer Access_Token
  • 对于 SOAP API，使用 SessionHeader SOAP 授权的header。access token放在header里面
  • 对于URL方式，使用 与 REST API 相同方式或 HTTP 参数 oauth_token

这里说的有点复杂，我们看一下常用的rest方式的代码更好的了解。以下的代码结构做过和其他系统交互的相比都特别的熟悉。其中 request.setHeader设置 Authorization： Bearer方式就是REST API的访问方式。（前序获取token通常都是基于账号密码获取，这里不额外展示）

request.setEndPoint('xxxxxxx');//指定的rest
request.setMethod('PUT');
request.setHeader('Content-Type', 'application/json');
request.setHeader('Authorization','Bearer '+token);
request.setBody(jsonData);
HttpResponse response = http.send(request);

3. scope（OAuth范围）

我们通过Oauth的最终目的是什么？是访问资源，所以如何来确保当前的user通过access_token可以访问哪些的授权数据呢？这里就引出了scope的概念。salesforce提供了以下 Oauth 范围配置分配给连接的应用程序，以定义客户端可以访问的受保护资源的类型。

• Full access (full)：允许登录用户访问所有数据，并包含所有其他范围。需要注意的是，如果scope设置成了full，不会返回refresh token，必须明确请求 refresh_token 范围才能获得。
• Access custom permissions (custom_permissions)：允许访问当前的org关联的connected app的自定义权限。
• Provide access to custom applications (visualforce)：只允许用户访问用户创建的VF页面，这个scope不允许访问标准的salesforce UI。
• Access and manage your data (api)：允许使用API访问当前的登录的用户账号。如 REST API 和 Bulk API。此范围还包括 chatter_api，允许访问连接 REST API 资源。

除此之外，还有很多其他的配置，想要全量的理解这些可以自行查看上面的官方文档。

二. Connected App

所以我们终于聊起了 Connected App。什么是 Connected App， Connected APP Use Case 以及 如何创建一个Connected App。

1. Connected App 以及 Use Case

Connected App是一个允许外部的应用通过API 以及 标准协议来实现和Salesforce交互的架构。标准协议我们可以使用 Oauth，SAML或者 Open ID Connect。Connected App使用这些协议去对外部应用程序进行身份验证、授权并提供单点登录 (SSO)。 和Salesforce进行交互的外部应用可以运行在customer success platform, 其他平台,设备,或者saas的订阅方.所以在我们上面的流程中，登录 Salesforce 移动应用程序并从 Salesforce 查看数据时，其实我们就是在使用 connected app。概念有了以后，我们需要知道实际项目中哪些场景可以用到Connected App。官方介绍了以下的四种场景。

• 通过 API 集成访问数据：这个应该是我们项目中用到最多的情况。我们可以使用 connected app去代表外部应用来请求访问到salesforce的数据。为了请求connected app，必须使用 OAuth 2.0 协议与 Salesforce API 集成。

• 将服务提供商与您的 Salesforce 组织集成：我们在SSO的博客中有两个概念：一个是 Service Provider，一个是Identity Provider。Identity Provider用于对用户进行身份认证的，而 Service Provider用来请求用户身份认证是否通过的。当Salesforce充当 Identity Provider时，我们可以使用connected app将service provider与 Salesforce 组织集成在一起。这种用的比较多的协议是SAML。这里说几个SSO的术语描述：

1. 1. 联合身份验证（Federation Id）：通过联合身份验证，用户可以登录一次来访问多个应用程序。例如，您登录到您的 Salesforce 组织，从那里可以访问您公司的福利应用程序 Workday。
   2. 安全声明标记语言 (SAML)：SAML 是一个开放的标准身份验证协议，您可以使用它在您的 Salesforce 组织中实施 SSO。SAML 允许身份提供商和服务提供商安全地交换用户信息，支持服务之间的用户身份验证。
   3. 身份提供商(Identity Provider)：身份提供商充当验证用户身份的可信服务。
   4. 服务提供商（Service Provider）：服务提供商是用户希望访问的应用程序，例如 Salesforce 组织或第三方应用程序，如 Workday。
   5. SAML 请求：当用户试图访问服务提供商时，服务提供商会发送 SAML 请求，要求身份提供商对用户进行身份验证。
   6. SAML 响应：为了验证用户，身份提供商会向服务提供商发送 SAML 响应。响应包含一个带有用户事实的签名 SAML 声明。
   7. SAML 声明SAML 声明是 SAML 响应的一部分，它通过声明事实（例如用户名或电子邮件地址）来描述用户。在身份验证期间，身份提供商签署 SAML 声明，服务提供商验证签名。
   8. 即时 (JIT) 配置使用带有 SAML SSO 的 JIT 配置，在用户第一次登录时自动向服务提供商注册用户帐户。如果我们希望单点登录以后更新某个user的标识等自定义操作，我们可以进行一个JIT的自定制。

• 管理对第三方应用程序的访问权限:管理员可以设置安全策略来控制第三方应用程序可以从org访问哪些数据。管理员也可以定义谁可以使用第三方应用程序。
• 提供对外部 API 网关的授权：Salesforce 可以作为独立 OAuth 授权服务器，以保护在外部 API 网关中托管的资源。例如，对于在 MuleSoft Anypoint Platform 中托管的 API 网关，Salesforce 可以作为 OAuth 授权服务器。作为资源服务器，MuleSoft Anypoint Platform 可将客户端应用程序动态创建为连接的应用程序。这些连接的应用程序可向 Salesforce 发送请求，并要求访问由 API 网关保护的数据。然后，Salesforce 可以对连接的应用程序进行身份验证，并授予其对由 API 网关保护的数据的访问权限。（这个我在实际项目中用到很少，理解有限）

2. Connected App创建和管理

我们在 setup处搜索 App Manager，右上角就有新建 Connected App的按钮，点击新建以后，有上图的UI。我们可以看到分成了大概六部分，下面就针对这6部分作为简单的介绍。

Basic Information

这里主要是必填的三个选项：

• Connected App Name：用来设置这个 Connected App Name；
• API Name：做sf的都了解API Name的含义，不解释；
• Contact Email：如果别人想要通过邮件联系到支持的人，这里输入支持的人的Email；
• Contact Phone：同上作用，区别是填入手机号；
• Logo Image URL：我们正常在app launcher搜索的app都带有图标，如果我们希望这个 connect app在app launcher展示里面拥有自己的图标，就设置这一项；
• Info URL：如果 Web 页面包含有关应用程序的更多信息；
• Description：app launcher针对app可以做一个简单的描述，如果需要在app launcher中展示在这个app后面，可以输入需要的内容。

API（Enable Oauth Settings）

项目中经常用到外部系统Oauth通过API调用访问sf系统限定数据，通常我们可能写一些restful接口或者直接用标准的接口，这种我们通常使用Oauth配置。

当我们勾选OAuth Settings配置以后弹出来后续的启用的配置项。

• Enable for Device Flow：上面的OAuth授权流程中有一项use case是适用于 IoT 集成的 OAuth 2.0 设备流。当我们在输入或显示能力有限的设备（例如电视、电器或命令行应用程序）上为外部应用程序设置connect app，我们需要勾选此项；
• Callback URL：根据使用的 OAuth 授权流程，通常这就是在成功验证后，用户的浏览器重定向的 URL。因为此 URL 用于某些 OAuth 流程以传递访问权限标记，所以 URL 必须使用安全 HTTPS 或自定义 URI 方案。
• Use digital signatures：如果我们的OAuth授权流程选择的类型是JWT的授权类型，需要勾选并且上传电子签名；
• Selected OAuth Scopes：这个和我们上面讲的Oauth Scope定义相同，用来定义connected app的权限；
• Require Secret for Web Service Flow：勾选的情况下要求交换access token时必须要求client secret；
• Require Secret for Refresh Token Flow：以在refresh token和混合refresh token流的授权请求中，要求app的client secret；
• Enable Single Logout：启用单点退出情况下，输入 logout URL，当用户 logout salesforce情况下，跳转到配置的 logout页面。

其他三点项目上很少用到，感兴趣自行查看API文档。

Web App Settings

当我们sf端想作为 identity provider去和service provider进行集成进行单点登录的配置，我们可以实现了SAML 2.0的connected app用来进行用户验证操作。

• Start URL：要在用户进行身份验证后将其定向到特定位置，比如我们希望验证身份以后，跳转到顾客列表，我们就可以设置 Start URL为： https://MyDomainName.my.salesforce.com/001/oEnable
• SAML: 勾选就代表我们这个connected app的目的是用来允许SAML做单点登录用；
• Entity Id：Service Provider提供的globally unique ID；
• ACS URL：ACS是Assertion Consumer Service的缩写，用来接收接收 SAML 断言的Service Provider的endpoint；
• Enable Single Logout：设置是否允许单点的 logout，勾选以后可以配置 logout需要跳转的指定的页；
• Subject Type：为应用程序指定哪个字段定义用户的身份，通常用 Federation ID(联合ID)；
• Name ID Format：指定 SAML 消息发送格式属性。默认的选择是未指定；
• Issuer： 默认情况下，我们在这里设置SF的domain信息作为发行者。如果 SAML 的Service Provider需要其他值，就修改成其他的；
• IdP Certificate：如果Service Provider需要唯一证书验证来自 Salesforce 的 SAML 请求，我们就需要上传指定的证书，否则默认即可；
• Verify Request Signatures：如果Service Provider提供了安全证书，则选择验证请求签名，然后上传指定的即可，否则不需要勾选；
• Encrypt SAML Response：如果需要选择加密 SAML 响应，以在系统中浏览证书并将其上载。选择用来加密声明的加密方法。有效加密算法值是 AES–128（128 位密钥）、AES–256（256 位密钥）和 Triple-DES（三重数据加密算法），这个实际中很少选择；
• Signing Algorithm for SAML Messages：选择 SHA1 或 SHA256 来保护从 Salesforce 发送的 SAML 消息。作为Identity Provider，Salesforce 将所选算法应用于其 SAML 请求和响应。所选的签名算法适用于从Service Provider到Identity Provider的单点登录和单点注销消息。

Custom Connected App Handler

Custom Connected App Handler可以支持新协议，或者以有利于业务流程的方式响应用户属性。如果我们需要有上述的业务流程需求，我们可以设置自定义的Connected App Handler。

• Apex Plugin Class：此类需要继承ConnectedAppPlugin 类，详细可以参考：https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_Auth_ConnectedAppPlugin.htm
• Run As：选择代表运行插件的user

Mobile App Settings

当我们使用 Salesforce Mobile SDK想要实现移动应用程序连接到sf，我们可以connected app设置 Mobile App Settings，从而实现 移动应用程序这些连接的应用程序可以访问 Salesforce OAuth 服务，并调用 Salesforce REST API。

• Mobile Start URL：用于从移动设备访问应用程序时将用户转到特定位置，比如（完整域名）/001/则跳转到Account列表；
• PIN Protect：如果应用程序支持 PIN 码保护，则选择 PIN 码保护。此设置允许管理员在安装连接的应用程序后，为移动应用程序设置会话超时和 PIN 码长度。
• App Platform：选择应用平台，是IOS还是Android；
• Restrict to Device Type：为移动应用程序指定支持的设备形式。如果应用程序是支持所有形式因素，则不选择值，可选值Phone 、 Tablet、Mini-Tablet；
• App Version：对于应用程序版本，输入移动应用程序的版本号；
• Minuim OS Version：对于最低 OS 版本，输入应用程序所需的版本；
• Private App：如果此应用程序仅用于内部（非公用）分发，则选择此项；
• App Binary URL：如果勾选了 Private App，则指定移动应用程序二进制文件的位置。文件格式是 IPA for iOS 和 APK for Android；
• Push Messaging Enabled：是否启用用来发送移动的推送通知，详情可查看：发送移动推送通知 (salesforce.com)
• Enable subscription to notification types：针对通知类型用。

Canvas App Settings

用于将 connected app暴露成 Canvas App。用户可以通过Chatter Tab来访问 个人的canvas app。

• Canvas：勾选以后即启用了Canvas画布；
• Canvas App URL：这个URL用于当用户点了canvas app以后，跳转到这个配置的URL；
• Access Method：选择一个访问方式去指定canvas app如何去初始化一个 oauth流；
• SAML Initiation Method：针对canvas app授权使用了SSO方式，则选择这个选项；
• Locations：选择向用户显示画布应用程序的地方；

后面的内容基本很少会有配置，这里不做讲解，可以自行查看官方文档。

 总结：篇中也只是针对 Oauth以及 Connected App做简单介绍，详细的了解可以自行查看上方的官方的文档。关于 Oauth的不同的授权流针对不同case的不同使用方式以及 Connected App编辑和管理等感兴趣可以自行查看文档。篇中有错误地方欢迎指出，有不懂的欢迎留言。