Salesforce 整合篇零基礎學習（一）Connected App

zero.zhang發表於2021-05-06
SalesforceAPP

本篇參考：

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. 聯合身份驗證（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編輯和管理等感興趣可以自行檢視文件。篇中有錯誤地方歡迎指出，有不懂的歡迎留言。

相關文章