使用知行之桥EDI系统的HTTP签名身份验证

本文简要概述了如何在知行之桥EDI系统中使用 HTTP 签名身份验证，并将使用 CyberSource 作为该集成的示例。

API 概述

API 是”应用编程接口”的缩写。这听起来可能很复杂，但它的真正含义是一种允许两个不同实体相互通信的软件。自开发以来，API 已迅速成为全球企业、行业和服务部门使用的一种常用通信方法。

知道了这一点，知行之桥EDI系统在构建时就考虑到了 API。使用应用程序中的专用端口，用户可以设计和创建从公共 API 端点或基于 REST 的 API 发送和接收数据的工作流。在实践中，大多数（如果不是全部）RESTful API目前都使用HTTP作为传输层，因为HTTP的基础设施、服务器和客户端库已经被广泛使用。

这些工作流可以通过使用知行之桥中的许多专用端口中的几个来实现。这些端口允许用户指定他们希望面向哪个 API 端点，以便 POST 某些 JSON 数据或提交 GET 请求以接收特定报告。但是，当 API 需要 HTTP 签名身份验证等身份验证方法时，它可能会变得有点棘手。使用此方法在知行之桥中发送适当的请求需要的不仅仅是拉取和推送，稍后将更详细地解释。

什么是HTTP签名认证，如何使用？

商业 API 通常需要某种形式的安全性，以便不是任何人都可以访问他们可以提供的数据。保护 API 的最常见方法是使用共享密钥。每次调用 API 时，都必须提供此密钥。但是，此方法不提供确保所传输数据完整性的方法。在这些情况下，HTTP 签名身份验证允许提高 API 的安全性。

HTTP签名身份验证通常使用以下两种方式：

• 允许发送方通过证明他们拥有密钥来请求访问资源。
• 允许发件人确认发送的邮件内容正确无误，并且在传输或存储过程中未被更改。

以 CyberSource API 为例。API 文档要求 REST HTTP 请求必须包含用户发送给 CyberSource 的签名请求标头。此签名由发送方加密，并在 API 收到时解密，以确保发送请求的用户有权访问指定的资源。

在知行之桥EDI系统中，可以通过使用 REST端口和包含自定义脚本的Script 端口来实现，Script 端口为 HTTP 签名生成所需的标头和加密。然后将这些消息标头发送到 REST 端口，接下来 REST 端口使用这些标头（包括签名）来处理 REST 请求。

REST 端口

REST 端口允许用户使用 HTTP 协议与交易伙伴发送或接收数据，其操作与流行的应用程序 Postman 非常相似。用户及其客户端都可以建立一个公共 API 端点，双方都可以从该 API 进行 POST 或 GET 数据。

将 REST 端口拖放到工作流中时，设置选项卡将被打开并显示如下所示的内容。

此处应提供有关要与之交互的 API 的详细信息，例如请求方法和唯一的 API 端点 URL、身份验证以及所需的任何自定义标头。如果 API 需要，也可以提供服务器身份验证凭据。

但是，如果 API 要求在所有请求中使用 HTTP 签名身份验证，该怎么办？以 CyberSource 为例，其 API 要求使用 HTTP 签名身份验证发送所有请求。

在 REST 端口中使用 HTTP 签名身份验证比在端口的设置选项卡中创建消息头、提供 URL 然后提交请求要复杂得多。主要区别在于如何获取加密的签名字符串作为 REST 端口中的消息标头传递。这就是自定义脚本和Script端口发挥作用的地方。

CyberSource API

CyberSource API 是一个非常大型的业务 API，专为作为电子商务信用卡支付系统管理公司运营的公司而开发。他们的 API 允许用户执行诸如处理付款、管理发票以及在此用例中报告等操作。

本文中的所有 API 参考都可以在 CyberSource API 文档中找到，该文档位于此处。

如果使用本文通过知行之桥实现 CyberSource API，请花时间确保您已创建并按顺序创建所有必要的凭据和密钥。

此示例所需的两个密钥是 Encoded Secret Key 和 Secret Key in UUID Format。这两个密钥都可以在CyberSource商务中心内找到：网址

Script 端口

了解了 CyberSource 的要求以及知行之桥如何处理这些要求之后，是时候介绍Script端口了——这是此操作背后的核心工具。此端口允许您生成签名字符串，并将其作为消息标头传递到工作流中的 REST 端口。概括地说，Script端口中的过程如下所示：

• 创建解码密钥的字节数组（在 CyberSource Business Center 中生成）。
• 创建一个基于解码的密钥字节数组的 HMACSHA256 对象，然后使用此HMACSHA256对象计算基于字符串字节数组的HMACSHA256哈希值。
• 最后，从上一步中 HMACSHA256 对象的字节数组生成一个 base-64 编码的字符串。

使这变得棘手的是，加密的签名字符串以及密钥 ID、签名算法和标头名称构成了签名标头的实际值。但是，所有这些都可以在Script端口中使用 ArcScript 来完成。

示例工作流

在介绍了一般 API 信息、HTTP 签名以及如何在此过程中使用知行之桥之后，现在是时候介绍使用CyberSource API 的示例 HTTP 签名身份验证流程了。强烈建议在继续之前安装此工作流。

示例工作流由Script 端口以及REST端口组成。

分解

CyberSource API 要求在请求中传递特定的 HTTP 标头。这些标头是：

• v-c-merchant-id v-c-商家 ID
• Date 日期
• Host 主机
• Signature 签名

v-c-merchant-id、Date 和 Host 是相对清晰的，复杂之处在于签名部分。

Signature 标头由多个名称-值对或参数组成，由 keyid、algorithm、headers 和 signature 组成。标头名称-值对只是所有必需标头的字符串，而签名名称-值对是签名哈希，它是标头字段及其值的 base-64 编码哈希。

通过将这些 HTTP 标头连接在一起形成一个字符串，并使用具有共享密钥的对称算法 （hmac-sha256） 获取该字符串的加密哈希值，从而生成 HTTP 请求的数字签名。最后，对加密的字节进行base-64编码，得到签名字符串。

下面的代码块显示了使用 CyberSource API 时生成的 HTTP 签名标头的示例。如上所述，签名标头由多个名称-值对组成，签名名称-值对包含上述 base-64 编码的签名字符串。

v-c-merchant-id: mymerchantid

Date: Fri, 12 Jul 201900:44:13 GMT

HOst: apitest.cybersource.com

Signature: keyid="6d75ffad-ed36-4a6d-85af-5609185494f4", algorithm="HmacSHA256", headers="host date (request-target) v-c-merchant-id", signature="eQkzhzu8UHEQmpBTVMibdNpPw1aLunmY41ckyLKoOjs="

Script 脚本

了解Script端口以及它如何利用 HTTP 签名身份验证后，是时候更深入地挖掘脚本本身并了解脚本编写过程的每个步骤中发生的情况了。

专为 CyberSource API 设计的 HTTP 签名身份验证脚本可分为四个主要部分。

• 解码被编码的密钥
• 将十六进制密钥暂存为 Base-64 编码的HMACSHA256哈希
• 设置消息头部
• 生成签名哈希

接下来将详细介绍以上四个部分。

解码被编码的密钥

脚本中的第一步是从 CyberSource Business Center 获取的解码密钥设置为脚本中的项目。然后，使用 encDecode 操作将该编码的密钥解码为十六进制值。

使用 encEncode 或 encDecode 操作时，可以使用“informat”和“outformat”属性指定输入和输出格式。默认的格式是 base64，原始密钥是在这里编码的，所以在这种情况下不需要指定格式。但是，outformat 已设置为“HEX”。

在这种情况下，此操作还需要一个“in”项，然后需要一个指定的“out”项。这是指将哪个项目传递到操作中，以及操作完成处理后输出项目的所需名称。

此过程的最后一步是将解码的密钥（现在为十六进制值）设置为全局项，以便它可以在脚本范围内的任何位置使用。十六进制值必须以“0x”为前缀，以告知分析引擎它正在处理常量，而不是标识符或保留字。然后，此十六进制值稍后用于创建 base-64 编码的HMACSHA256哈希。

<!-- encoded secret key in base64 encoding to HEX -->

<arc:set attr="encodedKey.data" value="JIVAFb/fO0WmocDuc3EvSjNiye7tif/aj+STWdFi/sU="/>

<arc:set attr="encodedKey.outformat" value="HEX"/>

<!-- setting decodedGlobal and setting value to hex key to be available globally -->

<arc:set attr="decodedGlobal.data" value="" />

<arc:call op="encDecode" in="encodedKey" out="decodedKey">

<arc:set attr="decodedGlobal.data" value="0x[decodedKey.decodeddata]" />

</arc:call>

将编码的密钥暂存为 base-64 编码的 HMACSHA256 哈希

脚本中的下一步是为后续步骤做准备。在脚本结束时，必须将每个标头字段名称的字符串及其关联值以及十六进制键编码为 base-64。在此步骤中，必须设置要编码的输入数据 （encIn） 的参数。必须在此处指定输入格式、hmackey、算法、位数和输出格式。

然后，此数据稍后将由 encEncode 操作处理，其中将以 Base64 编码。

<!-- encoding the hex key to HMACSHA256 -->

<arc:set attr="encIn.format" value="HMAC" />

<arc:set attr="encIn.hmackey" value="[decodedGlobal.data]" />

<arc:set attr="encIn.hmacalgorithm" value="SHA" />

<arc:set attr="encIn.hmacbits" value="256" />

<arc:set attr="encIn.outformat" value="BASE64" />

设置消息头部

配置解码的密钥和编码参数后，现在可以将消息头添加到Script端口创建的消息中，以便能够在 REST 端口中评估它们。

需要注意的一点是，API 密钥在脚本的这一部分中定义，但它也可以在之前的任何步骤中定义，因为它在最后一节之前不会使用。

在此处使用 arc：set 关键字，可以定义所需的标头，例如 MerchantID、HeaderDate 和 HeaderHost。

<!-- API secret key. this is the secret key in UUID format -->

<arc:set attr="apiSecret.key" value="b84ba2d7-1a4b-4814-b757-2f747ccab086" />??

<arc:set attr="Report.Date" value=[_|utcnow(yyyy-MM-dd)] />

<!-- Setting custom headers. Make sure you replace the merchant ID with your ID -->

<arc:set attr="Fileload.header:MerchantID" value="nsoft_test1" />

<arc:set attr="Fileload.header:myCustomHeader" value="?organizationId=[Fileload.header:MerchantID]&reportDate=[Report.Date]&reportName=test" />

<arc:set attr="Fileload.header:HeaderDate" value= [_|date(r)] />

<arc:set attr="Fileload.header:HeaderHost" value="apitest.cybersource.com" />

此处还定义了一个 myCustomHeader，其中包含 MerchantID、报告日期和报告名称。创建此标头，以便可以在 REST 端口的 URL 中将其作为查询字符串的一部分引用，如下所示：

https://apitest.cybersource.com/reporting/v3/report-downloads[_message.header:MyCustomHeader]

定义这些标头后，可以在标头值字段中使用 _message.header 语法在 REST 端口中引用它们。

生成签名哈希

最后一步是创建签名哈希。这是用于验证消息内容或提交请求的实体的真实性的内容。如前所述，数字签名是通过将所有 HTTP 标头连接在一起形成一个字符串来获得的。然后，使用第二步中设置的 hmac-sha256 算法，使用解码的密钥通过该字符串获取加密哈希值。最后，所有内容都以 base-64 编码，从而生成签名字符串。

此过程可以分为两个不同的部分：

• 设置和连接标头
• 对标头字符串进行编码以生成签名字符串

使用 arc：set 关键字，将所有标头及其值连接在一起为一个字符串。在本例中，将执行此操作并将其设置为 encIn 项（要编码的项）的 data 属性。在此步骤中，特别是使用 CyberSource API，标头字段的放置顺序必须与在消息标头中传递的顺序相同。

这里需要注意的一件事是，包含一个名为“request-target”的标头。request-target 标头值是小写的 HTTP 谓词，后跟空格，然后是资源路径（减去主机）。以下示例显示了对“/reporting/v3/report-downloads”资源的 GET 请求。在请求目标值中包含查询字符串和请求 ID。在本例中，已在 myCustomHeader 值中定义了查询字符串。

(request-target): get /reporting/v3/report-downloads[Fileload.header:myCustomHeader]

在这种情况下，为每个单独的标头包含一个新行也很重要，但不要在字符串末尾包含任何换行符 （\n）。

<arc:set attr="encIn.data">host: [Fileload.header:HeaderHost]

(request-target): get /reporting/v3/report-downloads[Fileload.header:myCustomHeader]

date: [Fileload.header:HeaderDate]

v-c-merchant-id: [Fileload.header:MerchantID]</arc:set>

此块完成脚本中的最后两个进程。首先，调用 encEncode 操作，并将之前定义为 encIn 的所有数据作为操作的输入参数传入。输出（在本例中定义为 encOut）包含所有输入数据，但现在它是 base64 编码的。

然后，arc：set 关键字用于创建由 keyid、algorithm、headers 和 signature 组成的签名标头。为了从 encEncode 操作访问编码数据，必须引用输出项的“encodeddata”属性。

在这种情况下，签名标头设置为 [encOut.encodeddata]，其计算结果为实际编码的签名字符串。

成功的签名标头应如下所示：

Signature: keyid="6d75ffad-ed36-4a6d-85af-5609185494f4", algorithm="HmacSHA256", headers="host date (request-target)

v-c-merchant-id", signature="eQkzhzu8UHEQmpBTVMibdNpPw1aLunmY41ckyLKoOjs="

<!-- generating signature hash -->

<arc:call op="encEncode" in="encIn" out="encOut">

<arc:set attr="Fileload.header:signature">keyid="[apiSecret.key]", algorithm="HmacSHA256", headers="host (request-target) date v-c-merchant-id", signature="[encOut.encodeddata]"</arc:set>??

</arc:call>



<!-- push the output -->

<arc:push item="Fileload" />

最后，使用 arc：push 关键字将包含所有标头和签名的整个项目从Script端口中推出。然后，此文件将发送到 REST 端口，在该端口中可以发出 HTTP 请求，在本例中为 GET 请求。

结论

本文的目的是帮助了解知行之桥是如何围绕 API 构建的，以及它如何使用预构建的端口和自定义脚本与 API 集成，以及如何使用知行之桥来遵守 API 的特定身份验证要求，例如 HTTP 签名身份验证。

此脚本包含专为与 CyberSource API 集成而开发的 ArcScript，但我们提供它的方式可以轻松操作，以适应可能需要 HTTP 签名身份验证的许多其他用例。

有关Script端口的详细信息，请参阅此处。如果要查找有关REST 端口的更多信息，可以在此处查看。

如果您想更深入地了解 ArcScript 以及脚本系统工作原理的基础知识，我们编写了 ArcScript 快速入门指南，可在此处找到该指南。

扩展阅读：EDI是什么？