开放平台证书升级指南

开放平台在原普通公钥签名方式基础上,新增支持证书签名方式,证书签名的优势在于引入了CA机构对公钥持有者进行身份识别,保证该证书所属实体的真实性,以实现报文的抗抵赖,具备更高的安全性。


下面将从应用证书设置、开发者访问开放平台网关、开放平台出口业务三部分来描述如何升级成公钥证书签名方式。


如果你当前已经使用了服务端SDK,请注意:

  • 当前仅Java版SDK(4.4.2.ALL及以上版本)支持证书签名方式,其他语言SDK还未支持。
  • Java版SDK 4.4.2.ALL中并没有对APP支付场景添加证书支持,若业务使用到该场景,请下载4.4.5.ALL及以上版本的SDK.


应用证书配置

下面分别从新创建的应用、已存在的应用两方面来介绍如何设置应用证书。

新建应用配置证书签名方式

配置证书

针对新创建的应用,开发者在 “应用信息” - “开发设置” - “接口加签方式”弹出的密钥页面中配置证书。

image.png

在密钥配置页面中,加签模式选择公钥证书(推荐),在该模式下,上传证书文件有两种方式:上传CSR文件在线生成证书(推荐)以及上传已申请证书,下面分别介绍这两种上传方式:


1)上传CSR文件,该文件由开发者工具生成

2)上传开发者找第三方权威CA签发公钥证书(CA必须在开放平台当前支持的CA列表中,且仅支持X.509格式的证书)


提示上传成功,开发者可查看、下载已生成(已上传)的应用公钥证书,以及下载对应的支付宝公钥证书、支付宝根证书(如下图)

更换证书

若开发者发现应用证书即将过期,希望更换原来的应用公钥证书,可在“加签管理”页面点击“更换证书”更换,如下图

image.png


在更换证书弹出页面的操作方式和前面一样,支持上传CSR文件在线生成证书(推荐)、上传已申请证书两种方式,这里就不再赘述。


更换完新证书成功后,开放平台将为旧证书保留7天有效期(若在这7天内旧证书到期,则以旧证书自身过期时间为准),超过7天后旧证书将不可用。开发者务必在更新证书后的7天内及时更新访问支付宝网关的代码中密钥配置否则变更7天后仍然使用旧证书接入的请求会被支付宝网关拦截而导致无法成功调用。


若开发者已使用新证书替换掉自己代码中的旧证书,开发者可通过“立即作废”按钮立即作废旧证书。

image.png

已有应用升级证书签名方式

配置证书

针对已创建的应用,开发者在“应用信息” - “开发设置” - “接口加签方式”弹出的密钥页面,点击“更换应用公钥”配置证书(如下图)。

image.png

在“更换应用公钥”配置页面,选择加签模式为“公钥证书(推荐)”,同样上传证书文件也有两种方式:上传CSR文件在线生成证书(推荐)以及上传已申请证书,操作方式新应用配置证书一样。


上传成功后,开发者可查看、下载已生成(已上传)的应用公钥证书,以及下载对应的支付宝公钥证书、支付宝根证书(如下图)

image.png

对于从“公钥”变更到“公钥证书”签名方式的应用,在变更7天内允许开发者撤销证书回退到“公钥”模式;变更7天后不允许再回退到原“公钥”模式(如上图红色提示),开发者务必升级证书后的一周内及时更新访问支付宝网关代码中的密钥配置,否则变更7天后原来的“公钥”模式接入的请求会被支付宝网关拦截而导致无法成功调用。


撤销证书

对于从“公钥”变更到“公钥证书”签名方式的应用,在变更一周内允许开发者撤销证书回退到“公钥”模式,如下图:


image.png


撤销后原上传的应用公钥证书将会被废弃,撤销后的密钥页面如下图:

image.png

更换证书

若开发者发现应用证书即将过期,希望更换原来的应用公钥证书,可在“加签管理”页面点击“更换证书”更换,具体操作方式与新应用更换证书方式一样,这里不再赘述。


注意:对于从“公钥”变更到“公钥证书”签名方式的应用,在变更一周内,证书配置页面上是没有“更新证书”选项的。若开发者希望换新证书,只能通过撤销证书回退到“公钥”模式,再重新上传证书的方式做到。


开发者访问开放平台网关

若应用使用公钥证书签名方式,开发者发送到开放平台网关(openapi)的请求报文、网关的响应报文和普通公钥签名方式下有所区别,下面就SDK接入、非SDK接入两种方式分别介绍。


使用开放平台SDK接入

支付宝开放平台 SDK 封装了签名和验签过程,只需配置账号及密钥参数即可,强烈建议使用。


SDK下载地址


开放平台 SDK 封装了证书签名实现,只需在创建 DefaultAlipayClient 对象时,设置请求网关 (gateway),应用id (app_id),应用私钥 (private_key),应用公钥证书路径(app_cert_path),支付宝公钥证书文件路径(alipay_cert_path),支付宝CA根证书文件路径(alipay_root_cert_path),编码格式 (charset),签名类型 (sign_type)即可,报文请求时会自动进行签名。


说明: 文中代码部分以 JAVA 语言演示,其他语言请参考各自 SDK。

//构造client
CertAlipayRequest certAlipayRequest = new CertAlipayRequest();
//设置网关地址
certAlipayRequest.setServerUrl("https://openapi.alipay.com/gateway.do");
//设置应用Id
certAlipayRequest.setAppId(app_id);
//设置应用私钥
certAlipayRequest.setPrivateKey(privateKey);
//设置请求格式,固定值json
certAlipayRequest.setFormat("json");
//设置字符集
certAlipayRequest.setCharset(charset);
//设置签名类型
certAlipayRequest.setSignType(sign_type);
//设置应用公钥证书路径
certAlipayRequest.setCertPath(app_cert_path);
//设置支付宝公钥证书路径
certAlipayRequest.setAlipayPublicCertPath(alipay_cert_path);
//设置支付宝根证书路径
certAlipayRequest.setRootCertPath(alipay_root_cert_path);
//构造client
AlipayClient alipayClient = new DefaultAlipayClient(certAlipayRequest);
//构造API请求
AlipayTradeQueryRequest request = new AlipayTradeQueryRequest();
//发送请求
AlipayTradeQueryResponse response = alipayClient.certificateExecute(request);

注:强烈建议开发者不要将应用私钥写死在代码中,可以存到DB、文件等,构造AlipayClient时动态传入,降低应用私钥泄漏风险。

应用公钥证书方式下发起加密请求

//构造client
CertAlipayRequest certAlipayRequest = new CertAlipayRequest();
DefaultAlipayClient alipayClient = new DefaultAlipayClient(certAlipayRequest);
//设置加密类型AES
certAlipayRequest.setEncryptType("AES");
//设置加密key
certAlipayRequest.setEncryptor(aes_key);
AlipayTradeQueryRequest request = new AlipayTradeQueryRequest();
AlipayClient alipayClient = new DefaultAlipayClient(certAlipayRequest);
//发送请求
AlipayTradeQueryResponse response = alipayClient.certificateExecute(request);


应用公钥证书方式下发起用户授权请求

//构造client
CertAlipayRequest certAlipayRequest = new CertAlipayRequest();
DefaultAlipayClient alipayClient = new DefaultAlipayClient(certAlipayRequest);
//构造业务API请求
AlipayTradeQueryRequest request = new AlipayTradeQueryRequest();
//发送用户授权请求
AlipayTradeQueryResponse response = alipayClient.certificateExecute(request, access_token);


应用公钥证书方式下发起应用授权请求

//构造client
CertAlipayRequest certAlipayRequest = new CertAlipayRequest();
AlipayClient alipayClient = new DefaultAlipayClient(certAlipayRequest);
//构造业务API请求
AlipayTradeQueryRequest request = new AlipayTradeQueryRequest();
//发送应用授权请求
AlipayTradeQueryResponse response = alipayClient.certificateExecute(request, access_token, app_auth_token);


未使用开放平台SDK


如果未使用开放平台SDK,需要自行实现签名,验签过程,参考自行实现签名自行实现验签


开放平台出口业务

开放平台存在主动向开发者应用发送异步通知、主动同步调用开发者三方能力的业务场景,这些场景下开发者应用对开放平台请求报文验签以及对发送给开放平台的响应报文加签,在证书签名方式下也有所区别,下面分别介绍这两个场景下加签、验签方式的变化。


异步通知

如某些情况下(比如扫码支付成功时),支付宝会给商户发送异步通知,


开发者对收到的异步通知做验签

应用升级成公钥证书签名模式后,支付宝访问开发者服务的通知报文签名方式不会有变化,开发者只需要在收到请求报文后使用支付宝公钥证书来做验签,详见文档


开发者对返回给支付宝的响应报文加签

开发者收到支付宝发送的异步通知后,需要将通知处理结果发送给支付宝,当前通知处理结果只有true/false,不涉及签名,无需改造。


三方能力调用

随着开放生态的逐步发展,商家业务的不断壮大,对于服务的多样性、效率及体验都有了更高的要求。我们需要依托支付宝开放平台,和不同的ISV交互,使用ISV提供的三方能力扩展更多的业务场景。三方能力旨在解决蚂蚁域内业务系统调用域外ISV服务的场景,支付宝开放平台通过http/https协议向域外ISV发起请求,并需要ISV同步返回规定格式的响应报文。


开发者对收到的同步调用请求验签

应用升级成公钥证书签名模式后,支付宝访问开发者服务的请求报文签名方式不会有变化,开发者只需要在收到请求报文后使用支付宝公钥证书来做验签,详见文档


开发者对返回给支付宝的响应报文加签

开发者应用发送给支付宝的响应报文需要加签,当前支付宝对开发者返回的响应报文支持两种数据格式(xml、json)。若应用使用公钥证书签名方式,返回给支付宝的响应报文内容和公钥签名方式有所区别,下面分别描述这两种报文格式的响应报文的不同点。

xml响应报文

公钥签名方式响应报文示例:

<alipay> 
    <response> 
      <result1>T</result1> 
      <result2>1.0</result2> 
      <result3>xyz</result3> 
    </response> 
    <sign>daa3db08d7e30fd78517b372b35848d9</sign> 
    <sign_type>RSA</sign_type> 
</alipay>


公钥证书签名方式响应报文示例:

<alipay> 
    <response> 
      <result1>T</result1> 
      <result2>1.0</result2> 
      <result3>xyz</result3> 
    </response> 
    <app_cert_sn>6cd4ee7e4f31c1adba2380cc65da4a3a</app_cert_sn>
    <sign>daa3db08d7e30fd78517b372b35848d9</sign> 
    <sign_type>RSA</sign_type> 
</alipay>
json响应报文

公钥签名方式响应报文示例:

{
  "response": {
    "code":"10000",
    "msg":"success",
    "key_1": "Value1",
    "key_2": {
      "inner_key1": "ThisIsInnerValue"
    }
  },
  "sign":"XXXX"
}


公钥证书签名方式响应报文示例:

{
  "response": {
    "code":"10000",
    "msg":"success",
    "key_1": "Value1",
    "key_2": {
      "inner_key1": "ThisIsInnerValue"
    }
  },
  "app_cert_sn":"6cd4ee7e4f31c1adba2380cc65da4a3a", 
  "sign":"XXXX"
}


从上面示例可以看到,在公钥证书签名的方下,xml、json格式的响应报文里都多了一个app_cert_sn(应用公钥证书序列号,注意:app_cert_sn不参与签名),支付宝会在开发者上传应用公钥证书中,寻找匹配的应用公钥证书对响应报文验签。


onlineServer