从外部系统调Salesforce的REST API或者你在做一个和Salesforce做单点登录的Web应用90%的情况下你都得先跟一个东西打交道就是Connected App。很多刚接触Salesforce集成的人后端代码都写完了结果调接口时一直被怼回一个unknown_client或者invalid_grant翻来覆去查不出原因。其实问题十有八九出在Salesforce后台的这个Connected App没配好或者授权策略选错了。这篇文章我就从实际做集成的角度把Connected App的概念、创建步骤、授权策略、三种主流认证流程以及排坑经验一次性完整讲清楚。适合所有要对接Salesforce API的实施顾问、后端开发、集成工程师也包括只想搞清楚后台配置项的运维同学。1. Connected App到底在解决什么问题1.1 为什么外部应用绕不开OAuth先不急着点按钮得先理解Connected App在整个集成链路里扮演的角色。Salesforce作为一个SaaS平台把所有业务数据和API都锁在自家认证体系后面。外部应用想通过API读取Contact、Account、自定义对象或者发起一次单点登录都必须先证明“我是谁、我要访问什么、谁批准了这次访问”。Connected App就是Salesforce侧的一个注册档案它记录了三个核心信息这个外部应用是谁、它能申请哪些权限范围、以及它用什么方式发起认证。本质上可以把它理解成“给外部系统发的一张授权门禁卡”。没有这张门禁卡哪怕你把用户、密码、权限集都配好了API也照样进不来。很多企业项目里开发往往先写代码、配好用户权限最后才发现漏了Connected App。这个顺序其实错了。正确的做法是先到Salesforce后台把Connected App建好拿到Client ID和Client Secret再把这两个值交给后端去实现OAuth流程。否则后面排查起来你根本分不清到底是代码问题、网络问题还是认证配置本身的问题。1.2 Connected App里的两个“钥匙”消费者密钥与消费者秘钥创建Connected App之后系统会生成两个字符串一个是“消费者密钥”也就是Client ID另一个是“消费者秘钥”也就是Client Secret。这俩东西分工完全不同。消费者密钥是公开的它标识的是这个应用本身。在授权码流程里用户浏览器跳转到Salesforce登录页时URL上带的client_id就是它。这个值就算被前端别人拿到单独他也干不了什么因为它还需要配合回调URL和消费者秘钥才能完成令牌交换。消费者秘钥则必须严格保密因为它相当于这个应用的密码一旦泄露别人就能冒充你的应用去申请令牌。所以秘钥只应该存放在后端服务或密钥管理服务里绝对不要写进前端代码、Git仓库或者随便发给第三方。我在实际项目里见过有人把Client Secret直接放到前端Vue或者React的环境变量里然后打包上线这是非常危险的操作。要知道浏览器里所有东西都是透明的看Network面板就能把秘钥翻出来。正确的做法是通过后端接口或环境变量注入到服务端进程里去。1.3 Scope怎么选权限边界怎么定Connected App的OAuth Scope决定了外部应用获得令牌后能用这把令牌做什么。很多人容易忽略这一步直接把所有Scope勾上或者只勾一个full_access后患无穷。常用的Scope有这几个full完全访问当前用户的数据权限最大一般不建议直接勾。api通过API访问用户可访问的数据是最常见的业务集成Scope。refresh_token和offline_access允许获取Refresh Token让应用在访问令牌过期后能自动刷新服务端集成的必选项。openid用于获取身份信息做SSO单点登录时用。id、profile、email这些主要用于读取用户基础信息比如头像、邮箱、姓名。选Scope的原则是“最小权限”。比如你只想读取Account名称用于做数据同步那就勾api加refresh_token别去勾full。因为full虽然省事一旦令牌泄露攻击者能操作这个用户能操作的所有数据风险等级完全不同。2. 从新建到落地Connected App创建全流程2.1 进入App Manager新建Connected App创建入口在Setup里。你可以在闪电体验的右上角点齿轮进入Setup然后在左侧快速查找框里输入“App Manager”打开应用管理器界面。这里会列出组织里所有的自定义应用和Connected App。点击右上角的“New Connected App”按钮会进入创建向导。注意这里要选“New Connected App”而不是“New Lightning Platform Connected App”后者虽然也能创建工作但配置项入口略有差异。我一般直接在App Manager里创建因为它生成的Connected App在保存后仍然可以比较方便地编辑OAuth配置而老的Connected App创建入口生成的档案很多字段保存后就被锁死了。进入向导后需要填的内容分几个区块基本信息、API那栏的OAuth设置、以及下面的权限设置。先不要着急勾选所有选项一步步来。2.2 基本信息与回调URL的填写要点第一栏是Connected App名称和联系人信息。“Connected App Name”用来在Salesforce后台标识这个应用建议用有业务含义的名称比如“订单系统同步App”方便以后维护。API Name会用英文自动生成可以自定义改成OrderSyncApp之类这个字段最终会体现在代码和权限引用里固定下来后尽量别改。“Contact Email”是必填项一般填集成负责人或者管理员邮箱。这个邮箱会出现在授权确认页面上用户如果对应用有疑问会通过这个邮箱联系。Logo URL可不填。关键字段是“Callback URL”也就是回调地址。授权码流程里用户登录成功后Salesforce会把认证code重定向回这个地址。这个地址必须和你在代码里配置的回调地址完全一致一个字符都不能差包括协议、端口、路径。开发阶段可以用http://localhost:8080/callback但上生产环境前务必改成正式环境的HTTPS地址。这里有三个实践建议回调地址尽量是HTTPSSalesforce最新策略里对明文HTTP限制越来越严格。一个Connected App可以配置多个回调URL需要配置多个环境时直接在回调URL字段里用逗号或空格分隔即可。回调URL是“精确匹配”不是“前缀匹配”或“模糊匹配”所以不要把https://example.com/callback和https://example.com/callback/混用两个其实是不一样的地址。2.3 勾选OAuth设置并选择Scope在向导的“API (Enable OAuth Settings)”区域勾选“Enable OAuth Settings”下面的配置选项才会激活。这里能看到Client ID和Client Secret的应用消费密钥将在保存后生成但在这个页面配置阶段要先把以下事情定下来第一Scopes选什么。按我们刚才说的原则业务API集成至少勾api和refresh_token, offline_access。如果要做SSO再增加openid和基础信息相关的Scope。第二下面有一个“Require Secret for Web Server Flow”的选项默认是勾上的建议保持勾选。这意味着授权码换令牌时需要出示Client Secret。如果取消勾选客户端应用就可以不携带秘钥直接换令牌安全性下降。第三页面里还有一段“API Version”选择默认是当前版本。一般保持默认就行。如果你同时对接多个系统尽量统一API版本否则不同版本下有些字段的返回结构会有差异增加后端解析成本。保存后系统会生成这个Connected App的Consumer Key和Consumer Secret。回到App Manager列表里找到你刚创建的这个应用点击行右侧的下拉箭头选择“View”可以看到这两个关键值。Consumer Secret只在创建时完整显示一次如果之后忘记了需要点“Manage”进去重置重置后旧秘钥立刻失效。2.4 保存后马上要做的事创建成功后不要急着去写代码还有几个尾巴要处理。第一确认OAuth策略。回到App Manager在刚才创建的应用行点击下拉菜单里的“Manage”进入管理页面。这里能设置Access Token有效期、Refresh Token策略、IP限制等。这些我们下一章详讲。第二给用户分配访问权限。新创建的Connected App默认状态下用户要登录并显式授权一次应用才能代表用户访问数据。如果业务上希望管理员预先批准可以在Manage页面里对相关权限集或个人用户进行授权避免用户端弹授权确认框。第三做一次令牌请求验证。用Postman、curl或者任意你熟悉的HTTP调试工具先用密码授权流程拿一次Access Token再拿令牌调一次https://yourInstance.salesforce.com/services/data/v60.0/sobjects/Account/确认返回200和JSON数据。这一步能在半小时内排除掉80%的基础配错问题。3. 授权策略与安全参数深度调整3.1 令牌生命周期配置Connected App的Manage页面里OAuth策略一般分两大块访问令牌策略和刷新令牌策略。访问令牌有效期默认是15分钟可以拉到最长24小时。我看到很多项目图省事直接把访问令牌设成24小时说这样可以少刷令牌。短期看确实减少了刷新逻辑但长期看隐患很大因为访问令牌一旦泄露攻击者能在一天内持续使用它。更稳妥的做法是保留较短的有效期比如1小时然后利用Refresh Token自动续期。Refresh Token策略有几种模式策略效果适用场景Until Revoked刷新令牌长期有效直到用户或管理员撤销常见于企业内部后台系统长期运行的数据同步任务Expire after N days刷新令牌到期自动失效对安全要求高、希望令牌周期轮换的场景Sliding Window每次使用时刷新有效期需要控制长时间不活跃的客户端自动失效的场景这里有个很坑的细节修改Refresh Token策略后已经发出的令牌并不会马上失效新策略通常只对后续新签发的令牌生效。所以如果你是为了紧急收回某个泄露的令牌光改策略没用得直接在Manage页面找到“Revoke”按钮去撤销已发令牌或者到用户详情页里清除该用户的Session和令牌。3.2 数字签名证书与JWT准备如果你打算走JWT Bearer流程也就是服务器对服务器的集成需要在Connected App里配置数字签名证书。这个证书是用来验证JWT签名的Salesforce这边保存的是公钥证书你那边持有对应私钥。实际操作里生成方式多种多样。常见的是用OpenSSL生成一对私钥和自签名证书然后把证书内容上传到Connected App的数字签名区。生成命令大概是这样的openssl req -newkey rsa:2048 -x509 -keyout privatekey.pem -out certificate.pem -days 365 -nodes命令执行完你会得到privatekey.pem和certificate.pem两个文件。私钥自己保管证书内容粘贴到Connected App的“Digital Signature”上传区域即可。这里要特别注意几点证书Key Size建议不低于2048位否则部分Salesforce实例会拒绝校验。证书有效期到了之后不会自动续期需要重新生成、重新上传、然后后端同步更换签名私钥。JWT里的aud字段要匹配你的认证端点生产环境是https://login.salesforce.com沙盒环境是https://test.salesforce.com写错会直接报invalid_grant: audience invalid。3.3 用户批准机制与权限集分配Connected App上还有一个很重要但容易被忽略的点应用授权用户的管理方式。默认情况下用户首次通过该应用登录时会看到一个授权确认页面列出应用申请的权限范围用户点“允许”后系统才签发令牌。这种模式适合用户自助完成授权。但在集成场景里很多外部系统使用的是“技术用户”例如一个专门的系统账号integrationcompany.com。你肯定不希望每次同步任务都要人工去点一次“允许”。这时就需要把Connected App的OAuth策略改成“管理员批准的预授权模式”在Connected App的OAuth设置里有一项“Admin approved users are pre-authorized”选项。开启后从Manage页面进入“Manage Profiles”或“Manage Permission Sets”把对应的Profile或权限集加进去这样该Profile下的用户登录时就不会再看到授权确认页直接签发令牌。还有一种更细粒度的方式是管理员直接到用户详情页分配访问权限。我实际操作中更推荐权限集的方式因为权限集可以精确加到某些系统账户上且不影响标准业务用户。需要注意预授权模式并不会绕过登录这一步用户仍然需要提供有效的Salesforce凭据以及安全令牌或者通过MFA验证。它只是跳过了“授权确认”这个环节。3.4 IP限制上生产环境前必须想清楚老牌企业里IT安全策略一般会要求限制API访问来源IP。Connected App的Manage页面里可以配置IP限制一般有三种Relax IP restrictions不限制来源IP最省事但安全上最松。Restrict IP based on the organization’s IP limits按整个组织的IP限制来。Restrict IP based on the user’s profile按用户Profile上的IP限制来最灵活。如果集成应用的调用方是公司的一台固定服务器或者云上的弹性IP强烈建议开启IP限制。方法很简单选择“Restrict IP based on organization limits”然后到Salesforce的Trusted IP Ranges配置里加入服务器出口IP地址范围。这样即使Client Secret或Refresh Token意外泄露攻击者在其他网络环境下也无法发起令牌请求。Dashboard上如果出现大量来自陌生IP的API调用排查的第一步也往往就是去看Connected App的IP限制配置。我曾经在一次项目里遇到令牌被异常的第三方反复调用就是因为IP限制当时设成了“Relax”攻击者拿一个从日志里泄露出来的Refresh Token从海外机房一直刷接口。改成IP限制后那类调用直接被拦在网关问题立刻消失。4. 三种授权流程的对接实操4.1 授权码流程Web应用接入的标准姿势授权码流程适用于有后端服务器的Web应用比如公司内部的管理门户要登录Salesforce或者展示报告数据。流程分两步。第一步把用户浏览器重定向到Salesforce授权页https://login.salesforce.com/services/oauth2/authorize?response_typecodeclient_idYOUR_CLIENT_IDredirect_urihttps://example.com/callback用户登录并授权后Salesforce会302跳转到你的回调地址并携带一个code参数。注意这个code有效期非常短通常是几分钟必须在拿到后马上使用。第二步后端拿这个code去换令牌curl -X POST https://login.salesforce.com/services/oauth2/token \ -H Content-Type: application/x-www-form-urlencoded \ -d grant_typeauthorization_code \ -d client_idYOUR_CLIENT_ID \ -d client_secretYOUR_CLIENT_SECRET \ -d redirect_urihttps://example.com/callback \ -d code这里填写第一步获取的code正常返回的JSON里会有access_token、refresh_token和instance_url三个关键字段。instance_url是本次调用实际要走的Salesforce实例地址比如https://ap23.salesforce.com后续API请求都要打这个地址而不是固定的login.salesforce.com。这里有个新手高频问题换令牌的时候redirect_uri参数到底要不要带答案是要带而且必须和第一步授权页上的redirect_uri完全一致。很多人在这个字段上翻车报mismatched_redirect_uri就是因为换令牌时把回调地址写成了别的格式。4.2 密码流程脚本和测试场景怎么用密码授权流程适合简单的后台脚本、本地测试、或者完全受信任的内部工具。它不需要用户跳转浏览器直接POST用户名密码换令牌。curl -X POST https://login.salesforce.com/services/oauth2/token \ -H Content-Type: application/x-www-form-urlencoded \ -d grant_typepassword \ -d client_idYOUR_CLIENT_ID \ -d client_secretYOUR_CLIENT_SECRET \ -d usernameintegrationcompany.com \ -d password你的密码加安全令牌注意password字段是“登录密码拼接安全令牌”不是单独只有密码。很多系统的密码字段会报invalid_grant: password expired往往就是因为漏了安全令牌或者密码里包含了符号导致URL编码问题。所以这里送一个建议在curl里使用--data-urlencode参数让工具帮你处理特殊字符转义。密码流程虽然方便但有个明显的弊端它拿不到上下文中的MFA验证、SSO验证也无法实现“用户确认”机制。Salesforce在官方文档里也一直对password flow持保守态度如果企业开启了MFA强制部分环境下密码流程会被拦截。能用授权码或JWT的地方尽量别用password flow只在本地联调、自动化测试等场景下使用。4.3 JWT Bearer流程服务端对服务端的无感认证JWT Bearer流程最适合做服务端到服务端的集成比如定时同步任务、事件总线推送、自定义中间件调用Salesforce API。整个流程不需要用户交互也不需要密码只要用签名断言证明自己的身份。先在Connected App的数字签名区上传证书然后你需要构造一个JWT断言。断言里通常包含{ iss: YOUR_CLIENT_ID, sub: integrationcompany.com, aud: https://login.salesforce.com, exp: 1690000000 }iss必须是这个Connected App的Consumer Keysub是Salesforce用户账号exp是过期时间必须用Unix时间戳。然后用之前生成证书时的私钥做RS256签名最后用断言去换访问令牌curl -X POST https://login.salesforce.com/services/oauth2/token \ -H Content-Type: application/x-www-form-urlencoded \ -d grant_typeurn:ietf:params:oauth:grant-type:jwt-bearer \ -d client_idYOUR_CLIENT_ID \ -d assertion这里填写JWT字符串JWT流程里最容易出错的就是aud字段。如果是生产环境写https://login.salesforce.com沙盒环境写https://test.salesforce.com。有些人抄网上的例子把生产环境的aud也写成test.salesforce.com结果永远报invalid_grant audience invalid。另外要提一下JWT Bearer Flow中的sub用户也需要有API调用权限并且要在该用户的记录上勾选“允许使用OAuth JWT Bearer流程”这一项否则换令牌时会被系统拒绝。这个选项在用户详情页的安全设置里比较隐蔽很多人在这个坑里浪费了大半天时间。5. 实战踩坑与问题排查速查5.1 invalid_client_id、invalid_grant一类的认证失败这类错误在对接初期出现概率极高而且错误信息往往比较笼统。按照我的经验先按方向排查错误关键字可能原因排查动作unknown_clientConsumer Key填错或所在环境不对检查Client ID是否复制完整注意开发环境和生产环境的ID完全不同invalid_clientClient Secret错误或已重置去App Manager的View页面重新核对必要时重置秘钥invalid_grant用户名密码错误、安全令牌缺失、账号被锁确认用户名、密码、安全令牌拼接查看用户是否被锁定或密码过期invalid_grant audience invalidJWT的aud字段填错环境生产填https://login.salesforce.com沙盒填https://test.salesforce.cominactive user系统用户被停用去Setup里查看该用户License状态和是否被冻结我还遇到过一种情况Connected App的Client ID是对的Secret也是对的但错误始终是invalid_client。后来发现是环境变量里还残留了旧版Client ID程序起动时加载的是老的配置文件两种信息一混就匹配不上了。这种时候不要死盯错误信息把实际发起请求时用的参数打印出来看一眼往往几秒钟就能定位。5.2 redirect_uri 不匹配的处理mismatched_redirect_uri在授权码流程里非常经典。用户跳转时用的回调和换令牌时用的回调不一致或者和Connected App“Callback URL”配置的不一致都会立刻报错。处理的唯一逻辑是三个地方必须一模一样。一是Salesforce Connected App界面里配置的Callback URL二是第一个授权请求URL上的redirect_uri参数三是换令牌POST请求里的redirect_uri参数。一个常见问题是回调URL里面带不带/结尾https://example.com/callback和https://example.com/callback/在字符串匹配上就是两个不同值。还有本地开发场景很多人的项目是前端React跑在3000端口后端Spring Boot跑在8080端口。配置回调URL时要指向那个能接收到code的完整后端路由而不是看浏览器的地址栏。别问我为什么知道这是个老生常谈但始终会有人撞的坑。5.3 拿到令牌但接口403怎么办令牌都换到了调API却返回403这通常是用户权限的问题不是认证问题。403和401不同401说明你根本没通过认证403说明系统认识你但你的权限不够。这里有几个排查方向API Enabled权限是否开启。用户Profile或权限集里必须有一项“API Enabled”的勾选否则即使拿到令牌也不能用API。查看方法Setup里找到该用户然后查看Profile的SystemPermissions。该用户是否能访问对应的对象和字段。Connected App只是给了个入场券能不能看Account、能看哪些字段还是由Profile的Object Permissions和Field Permissions决定。该用户是否被加入了Connected App的预授权列表。如果是管理员预授权模式检查Manage页面里是否添加了正确的Profile或PermissionSet。如果用户是用单点登录创建的账号有时其权限集是动态分配的未分配完整时API部分也会失败。403还有一个伪装成“404”的情况当你调用某个sObject API时如果对象存在但用户没有该对象的“已部署”和“预授权”访问权限Salesforce可能返回404。这其实是轻微的误导本质上还是权限不够。所以我排查403时习惯直接打开浏览器的Network面板同时看Response Body里的errorCode和message字段里面通常会有INSUFFICIENT_ACCESS_OR_READONLY之类的具体原因。5.4 策略改了不生效先看批准和缓冲修改Refresh Token策略、关闭某个授权方式、或者调整Scope之后常有同事反馈“我改完了怎么接口还在用旧令牌”这其实不是系统没生效而是已签发的令牌在新策略生效前就已经存在了。令牌的生命周期不是配置文件热加载它必须在授权那一刻按照策略生成。策略修改只会影响之后新签发的令牌。因此合理的操作顺序是先修改Connected App策略然后到Manage页面里撤销相关用户已有的Token或者直接让用户退出重新登录授权。对于系统集成账号建议在改完策略后确认该用户账号下的连接访问记录已被清掉再重新走认证流程拿新令牌。另外Connected App的修改在一些老版本UI保存后会有缓存延迟。如果改了策略怎么测都不生效到Setup搜索“Read Update in Flight Test”不佳其实更直接的做法是稍等几分钟再测或者换个浏览器无痕窗口去触发授权流程避免命中本地缓存的旧页面。结尾一点长期维护的小建议我做了这么多年Salesforce集成最大的体会是Connected App配置本身并不复杂麻烦在于它跟权限、策略、环境、证书这些东西纠缠在一起任何一个环节没对齐表现方式都是一样的“认证失败”或“接口拒绝”。所以建议你在项目初期就明确几件事用哪个环境、哪个系统用户、哪种授权流程、回调地址列表、谁负责保管Client Secret。这些定下来后把配置归档到内部文档里后续排查会快得多。还有一个很实际的小技巧给每一个对接方单独创建一个Connected App不要所有系统共用一个。虽然多几个应用看起来麻烦但这样做的好处是当某个系统出安全问题时你只需要撤销那一个App的令牌和权限其他系统完全不受影响。而且App Manager里还提供了每个Connected App的令牌使用统计和最近访问记录这些数据在审计和排障时都是非常宝贵的线索。