Genesys入门 - 03 连接 Connecting

01 大纲

---

原文链接：
https://help.genesys.com/developer/cic/docs/icws/webhelp/ConceptualContent/GettingStarted_Connecting.htm#top

---

Connection命名空间，提供了一个用于创建IC服务器连接的方法。
该Licenses命名空间也非常重要，用于获取所必需的某些操作的许可。

本主题包含以下部分：

• 建立基本连接
• 使用基本连接
• 连接到交换机对或服务器外会话管理器
• 使用单点登录
• 维护与服务器的会话
• 重新连接

---

一、 建立基本连接

为了使用大多数ICWS的功能，必须首先建立会话。
该POST / ICWS /连接方法用于创建一个会话（见一般要求为端点信息）。

有两个必输项：

1. Accept-Language请求标头中的参数。
2. 请求正文中的一个身份验证的表示形式。

Accept-Language报头参数，表示客户端应用程序主语言的语言代码。服务器将返回这种语言的可读文本，并格式化时间、日期和金钱，以符合区域设置首选项。

会话期间不能更改参数。此头的有效值遵循RFC2616中HTTP 1.1定义中定义的标准。例如，语言代码可以是“en-us”：

POST https://server:8019/icws/connection HTTP/1.1
Accept-Language: en-us

请求正文中的连接表示用于定义连接类型，包括有关该连接的参数。
支持的类型包括：
authTokenConnectionRequestSettings
icAuthConnectionRequestSettings，singleSignOnTokenConnectionRequestSettings。
这些中的一个（且仅一个）必须包含在请求主体中以建立连接。

下面显示了使用icAuthConnectionRequestSettings的示例。

{
    "__type":"urn:inin.com:connection:icAuthConnectionRequestSettings",
    "applicationName":"ICWS Example Application",
    "userID":"user1",
    "password":"passwordOfUser1"
}

---

二、使用基本连接

如果POST建立连接成功，则响应将包含重要的安全信息。

响应报头包括以下信息：ININ-ICWS-CSRF-Token，ININ-ICWS-Session-ID，Location，Set-Cookie。下面是一个例子。

ININ-ICWS-CSRF-Token: ABlcdeVnLmNhemFYCUlDV1MgVGVzdFgkOWVmYmNjMmYtNDViMS00OGU1LTljZDgtMmUwZTBlZDE3NzBhUzo6MQ==
ININ-ICWS-Session-ID: 12345678
Location: /icws/12345678/connection
Set-Cookie: icws_12345678=1234880c-039c-4199-8342-48e478f2b4a1; HttpOnly; Path=/icws/12345678

响应机构包括以下信息：csrfToken，sessionId。下面是一个例子。

{
    "csrfToken":"ABlcdeVnLmNhemFYCUlDV1MgVGVzdFgkOWVmYmNjMmYtNDViMS00OGU1LTljZDgtMmUwZTBlZDE3NzBhUzo6MQ==",
    "sessionId":"12345678",
    "alternateHostList": ["server2", "server3"]
}

CSRF令牌是刚刚建立的会话的PureConnect会话令牌。会话ID是刚刚建立的会话的PureConnect会话标识符。对此会话的所有经过身份验证的ICWS调用必须包含sessionId在URI中。所有经过身份验证的调用都必须在ININ-ICWS-CSRF-Token请求标头中包含CSRF令牌。有关CSRF令牌的更多信息，请参阅跨站点请求伪造（CSRF）。

这Set-Cookie是刚刚建立的会话的cookie。所有经过身份验证的调用都必须在请求标头中包含此会话cookie。浏览器将自动使用此会话cookie。非浏览器客户端应用程序需要Cookie在标头中为所有经过身份验证的调用传递它（作为参数）。

alternateHostList如果当前服务器不可用，该属性提供可用于重新连接的其他服务器的列表。有关更多信息，请参阅重新连接。

经过身份验证的呼叫的示例将是POST / icws / {sessionId} / licenses。此类调用的示例请求标头如下所示。请注意使用从POST / icws / connection返回的信息。

POST https://server:8019/icws/12345678/licenses HTTP/1.1
Accept-Language: en-us
Content-Type: application/vnd.inin.icws+JSON
Cookie: icws_12345678=1234880c-039c-4199-8342-48e478f2b4a1
ININ-ICWS-CSRF-Token: ABlcdeVnLmNhemFYCUlDV1MgVGVzdFgkOWVmYmNjMmYtNDViMS00OGU1LTljZDgtMmUwZTBlZDE3NzBhUzo6MQ==

---

三、连接到交换机对或服务器外会话管理器

当成功连接到IC服务器时，可以调用POST / icws / connection的进行初始调用。

如果考虑负载均衡方面，如果有更好的服务器要连接，将返回包含备用主机列表的503 HTTP状态代码。该列表由alternateHostList属性提供，是客户端应连接到的服务器的有序列表，首先包括首选服务器。列表的顺序将因每个ICWS连接尝试而异，并由服务器确定，以允许ICWS连接的加载在可用的会话管理器之间分配。

当客户端应用程序收到503 HTTP状态代码以响应连接请求时，应用程序应继续按顺序为列表中的每个服务器调用POST / icws / connection，直到创建连接，如201 HTTP状态代码所示。建立连接后，必须将所有后续请求发送到已建立连接的服务器。

例：客户端应用程序向IC服务器发出初始连接尝试：

POST https://ICServer.example.com:8019/icws/connection HTTP/1.1
Accept-Language: en-us
...

服务器当前不接受连接，因此它使用503 HTTP状态代码响应alternateHostList:

HTTP/1.1 503 Service Unavailable
...
{
    "alternateHostList": [
        "OSSM1.example.com",
        "OSSM2.example.com"
    ],
    "errorId": "error.server.notAcceptingConnections",
    "message": "This Session Manager is not currently accepting connections."
}

客户端应用程序尝试按列出的顺序与备用主机建立连接：

POST https://OSSM1.example.com:8019/icws/connection HTTP/1.1
Accept-Language: en-us
...

服务器接受了请求，已建立连接，并返回会话cookie：

HTTP/1.1 201 Created
ININ-ICWS-CSRF-Token: ABlcdeVnLmNhemFYCUlDV1MgVGVzdFgkOWVmYmNjMmYtNDViMS00OGU1LTljZDgtMmUwZTBlZDE3NzBhUzo6MQ==
ININ-ICWS-Session-ID: 12345678
Location: /icws/12345678/connection
Set-Cookie: icws_12345678=1234880c-039c-4199-8342-48e478f2b4a1; HttpOnly; Path=/icws/12345678
...

所有后续请求必须发送到建立连接的服务器：

POST https://OSSM1.example.com:8019/icws/12345678/licenses HTTP/1.1
Cookie: icws_12345678=1234880c-039c-4199-8342-48e478f2b4a1
ININ-ICWS-CSRF-Token: ABlcdeVnLmNhemFYCUlDV1MgVGVzdFgkOWVmYmNjMmYtNDViMS00OGU1LTljZDgtMmUwZTBlZDE3NzBhUzo6MQ==
...

---

四、使用单点登录

单点登录是一种方法，通过该方法，用户可以安全地与身份提供商进行身份验证，以访问单独服务提供商上的资源，而无需使用该服务提供商已知的凭据。

交互中心和ICWS作为服务提供商，支持身份提供商的安全身份验证。目前，ICWS支持实现安全断言标记语言（SAML）2.0的身份提供程序。

检索身份验证配置
为了让百仕瑞的服务器和ICWS建立经过了身份验证的会话，单点登录需要包含几个额外的步骤。

确保您的系统管理员已在Interaction Administrator中启用了一个或多个以下身份验证的类型：

• SAML 2 Web Browser Post
• SAML 2 Web Browser Redirect

1、客户端必须首先检索可用于身份验证的身份提供程序列表。
2、GET/icws/connection/server-info
的方法用于访问：配置的身份提供程序和各种其他连接前配置信息的列表。
3、ICWSAPI支持多个SAML 2.0协议绑定。
4、并非所有客户端应用程序都支持ICWSAPI支持的所有绑定，因此singleSignOnCapabilities必须将查询字符串参数指定为客户端支持的以逗号分隔的功能列表。
5、API将仅返回为指定的协议绑定配置的身份提供程序，并且如果未指定参数，则不会返回任何身份提供程序。

按优先顺序列出功能。目前包含以下内容：

大多数基于Web浏览器的应用程序都支持这两种应用程序saml2Post，saml2Redirect但建议这些应用程序saml2Post首先指示它是首选绑定。

对此，API的请求是：
GET /icws/connection/server-info?singleSignOnCapabilities=saml2Post,saml2Redirect

响应是一个serverInfo数据协定，其中包含身份验证配置和其他详细信息。一个示例serverInfo响应是：

{
    "languages": [
        { "languageID": "en-US", "languageDisplayName": "English (United States)" }
    ],
    "acceptLanguage": "en-US,en;q=0.8",
    "authentication": {
        "allowIcAuth": true,
        "identityProviders": [
            { "identityProviderId": "e00b7273-269c-40f6-ad3c-5721f167dce3",
              "displayName": "IC Server" },
            { "identityProviderId": "071753cd-1794-4f17-ac3f-67dce52417d8", 
              "displayName": "Active Directory Federation Services" },
        ]
    }
}

执行SAML 2.0身份验证

一旦应用程序检索到身份提供者列表，应用程序就可以将该列表呈现给用户以供选择。选择所需的身份验证方法后，通过使用所选方法向GET / icws / connection / single-sign-on / identity-providers / {identityProviderId}方法发出请求，启动SAML 2.0身份验证过程identityProviderId。由于可以为多个SAML 2.0协议绑定配置单个身份提供程序，因此客户端应用程序必须通过singleSignOnCapabilities查询字符串参数再次指定其功能，以确保选择支持的绑定。

基于Web浏览器的应用程序如何执行SAML 2.0身份验证有两种选择：选项1：使用弹出窗口和选项2：使用重定向。

对于桌面应用程序，建议使用选项1：使用弹出窗口。

选项1：使用弹出窗口

为了使用弹出窗口执行SAML过程，基于Web浏览器的应用程序应在单独的框架中打开GET / icws / connection / single-sign-on / identity-providers / {identityProviderId} URL，而不应该使用XMLHttpRequest。除singleSignOnCapabilities参数外，基于Web浏览器的应用程序还应将webBrowserApplicationOrigin查询字符串参数指定为加载应用程序的源。这是为了确保单点登录令牌可以安全地传递到应用程序代码，如下所述。

对GET / icws / connection / single-sign-on / identity-providers / {identityProviderId}请求的响应是由SAML 2.0协议定义的HTML页面以及协商的特定绑定。对于在新框架中打开请求的基于Web浏览器的应用程序，将根据绑定规范自动处理请求序列。

SAML 2.0进程的最终HTML页面将从请求返回到/ icws / connection / single-sign-on / return。对于有权访问响应标头的应用程序，标头中将提供单点登录标记ININ-STS-Token。基于Web浏览器的应用程序将无法访问响应头，因此最终的HTML页面将window.postMessage使用指定为GET / icws / connection / single-sign-on /中的webBrowserApplicationOrigin查询字符串参数值的目标源进行调用。 identity-providers / {identityProviderId}请求。该消息是一个JSON对象，已使用转换为字符串JSON.stringify。成功进行身份验证的JSON对象示例如下：

{
    "key": "icwsSsoComplete",
    "data": {
        "token": "SomeSingleSignOnToken",
        "errorMessage": "",
        "errorId": "",
        "httpStatus": 200
    }
}

此JSON对象将始终包含此结构。该key属性将始终为icwsSsoComplete状态。

如果身份验证过程成功，则该token属性将包含：可在POST / icws / connection请求中使用的单一登录令牌。

如果验证过程失败，token属性将为空字符串，并且ErrorMessage和ErrorID属性将包含与ICWS API中的其他错误响应一致的错误信息。http status属性始终是HTTP响应的状态代码。

选项2：使用重定向

为了在同一窗口中执行SAML过程，基于Web浏览器的应用程序应该在浏览器中导航到GET / icws / connection / single-sign-on / identity-providers / {identityProviderId} URL。除singleSignOnCapabilities参数外，基于Web浏览器的应用程序还应指定redirectUri查询字符串参数。此值应该是SAML过程完成后浏览器应指向的绝对URL。导航完成后，身份验证过程将按照SAML 2.0协议和协商的特定绑定的定义开始。

SAML过程完成后，将指示Web浏览器导航回redirectUri查询字符串参数指定的URL 。为了使应用程序能够检索可在POST / icws / connection请求中使用的单点登录令牌，Web应用程序必须调用GET / icws / connection / single-sign-on / response。

如果身份验证过程成功，将在HTTP 200响应的JSON正文中提供单点登录令牌。

如果发生错误，错误信息将包含在HTTP 400响应中。

使用单点登录令牌登录

获得单点登录令牌后，可以使用POST / icws / connection方法建立连接。此过程与建立基本连接所描述的相同，而不是icAuthConnectionRequestSettings使用singleSignOnTokenConnectionRequestSettings。singleSignOnTokenConnectionRequestSettings下面是一个例子：

{
    "__type":"urn:inin.com:connection:singleSignOnTokenConnectionRequestSettings",
    "applicationName":"ICWS Example Application",
    "singleSignOnToken":"SomeSingleSignOnToken"
}

身份提供商配置
出于安全原因，SAML 2.0身份提供程序需要将使用身份提供程序提供的声明的服务的URL。此预防措施有助于确保索赔不会传递给不受信任的第三方。根据身份提供者，此URL可以称为“断言消费者服务”或“依赖方”。对于Active Directory联合身份验证服务（ADFS），此设置为“依赖方信任”。

服务URL的格式ICWS如下：将{server}占位符替换为实际主机名：

https://{server}:8019/icws/connection/single-sign-on/return

所有IC服务器和服务器外会话管理器的身份提供者都需要有一个条目，以便身份提供者信任所有ICWS端点。如果客户端ICWS通过反向代理连接，则URL将需要反映代理URL。有关代理URL的详细信息，请参阅代理HTTP请求。

---

五、维护与服务器的会话

客户端应用程序可以选择三种不同的选项，通过使用其中一种消息传递机制来维护与服务器的会话。

选项1：使用服务器发送的事件（首选选项）

事件消息在ICWS服务器上的消息传递队列中发送，因为它们可用。只要服务器发送的事件连接在客户端和服务器之间打开，服务器就会保持会话打开。有关服务器发送事件的更多信息，请参阅检索消息。

选项2：使用短轮询

客户端应用程序使用短轮询通过GET / icws / {sessionId} / messaging / messages方法请求排队的消息。由于此请求是对经过身份验证的端点完成的，因此每次服务器收到短轮询请求时，会话超时都会重置。请注意，如果没有向服务器发出其他经过身份验证的请求，则会话将在2分钟后超时。有关短轮询的详细信息，请参阅检索邮件。

选项3：使用带有心跳选项的服务器发送事件

heartbeat选项是一种轻量级方式，客户端可以通知服务器使用服务器发送的事件的会话仍处于活动状态，并且由于不活动而不应超时。只有在服务器发送的事件连接可能比客户端连接更长的情况下，才应该这样做。在极少数情况下，心跳选项可用于帮助及时清理会话。

由于服务器至少每2分钟由于不活动而强制执行会话超时，在某些情况下，客户端可能希望让服务器知道特定会话仍然存在并且不应该超时; 反之亦然，会话不再有效，应该断开连接。客户端可以heartbeat通过使用GET / icws / {sessionId} / messaging / messages方法在消息传递资源上包含查询字符串来通知服务器它希望使用心跳。然后，客户端需要定期向服务器发送心跳请求，以使其知道会话仍处于活动状态。这是通过POST / icws / {sessionId} / messaging / heartbeat完成的方法。对此POST请求的响应是HTTP 204响应。如果在90秒内没有其他经过身份验证的请求流量发送到服务器，建议客户端每90秒向服务器发送一次心跳请求。如果在彼此至少90秒内对其他经过身份验证的端点发出请求，则无需发送心跳请求。

---

六、重新连接

由于ICWS各种原因，连接可能会丢失，包括切换，从其他位置的后续登录以及用户的帐户被删除。当连接丢失时，ICWS服务器将开始拒绝具有401 HTTP状态代码的请求; 但是，在有限的时间内，GET / icws / {sessionId} /连接方法将继续运行。这为客户端应用程序提供了检索连接丢失原因的信息的机会。该reason属性提供可以向用户显示的本地化文本描述。该shouldReconnect物业将是true，如果客户端应用程序可以尝试自动重新连接。这将是false当客户端应用程序不应尝试自动重新连接时。如果能够，ICWS服务器也可以发送connectionStateChangeMessage以指示客户端已断开连接。这个消息包括相同的reason和shouldReconnect特性作为GET / ICWS / {的sessionId} /连接反应。

如果服务器指示允许自动重新连接，则客户端应用程序应使用以下逻辑重新建立连接。它应该使用对最后一个POST / icws / connection请求的响应中提供的备用主机列表。

1. 选择15到25秒之间的随机值作为重新连接间隔。
2. 等待重新连接间隔的持续时间。
3. 选择备用主机列表中的第一个主机。
4. 尝试创建与所选主机的连接。
   • 如果HTTP响应为201，则成功重新连接客户端应用程序，并结束重新连接过程。
   • 如果HTTP响应为400，则停止重新连接并将错误信息提供给用户。
   • 如果HTTP响应为503，则将任何新的备用主机附加到备用主机列表的末尾，请继续执行步骤5。
   • 如果HTTP响应是另一个状态代码或请求完全失败，请继续执行步骤5。
5. 如果备用主机列表中有更多项目：
   • 在备用主机列表中选择下一个主机。
   • 转到第4步。
6. 如果备用主机列表中没有其他主机：
   • 如果重新连接过程已超过两个小时，请将重新连接间隔设置为原始重新连接间隔的10倍。
   • 如果重新连接过程的时间不超过两个小时，但自上次更新重新连接间隔以来已超过30分钟，则重新连接间隔加倍。
   • 等待重新连接间隔的持续时间。
   • 转到第3步。