配置 sso-settings.json 文件

安装和升级 > 安装 ThingWorx > 安全配置 > 单一登录身份验证 > 配置 ThingWorx 以进行单点登录 > 配置 sso-settings.json 文件

在 ssoSecurityConfig 目录中创建 sso settings.json 文件。

如果您的环境需要使用不同的路径，可以设置 THINGWORX_SSO_SETTINGS 环境变量的值，将 sso-settings.json 文件保存到不同的位置。

以下是 sso-settings.json 文件的示例结构：

{
"BasicSettings": {
"clientBaseUrl": "请参见下表中的信息",
"idpMetadataFilePath": "请参见下表中的信息",
"metadataEntityId": "请参见下表中的信息",
"metadataEntityBaseUrl": "请参见下表中的信息",
"webSSOProfileConsumerResponseSkew": "请参见下表中的信息",
"webSSOProfileConsumerReleaseDOM": "请参见下表中的信息",
"webSSOProfileResponseSkew": "请参见下表中的信息",
"retriggerOnScopesRemoval": "请参见下表中的信息",
"samlAssertionUserNameAttributeName": "请参见下表中的信息",
"samlAssertionMaxAuthenticationAge": "请参见下表中的信息",
"ptcOperatorsGroupName": "请参见下表中的信息",
"samlGroupClaimName": "请参见下表中的信息",
"administratorAlias": "请参见下表中的信息",
“administratorInternalName": "Administrator",
"authnContextAsPassword": "请参见下表中的信息",
"authenticationType": "请参见下表中的信息
},
"AccessTokenPersistenceSettings": {
"dbType": "请参见下表中的信息",
"driverClassName": "请参见下表中的信息",
"url": "请参见下表中的信息",
"username": "请参见下表中的信息",
"password": "请参见下表中的信息",
"encryptTokenInDatabase": "请参见下表中的信息",
},
"KeyManagerSettings": {
"keyStoreFilePath": "请参见下表中的信息",
"keyStoreStorePass": "请参见下表中的信息",
"keyStoreKey": "请参见下表中的信息",
"keyStoreKeyPass": "请参见下表中的信息"
},
"AuthorizationServersSettings": {
"<AuthorizationServerId1>": {
"clientId": "请参见下表中的信息",
"clientSecret": "请参见下表中的信息",
"authorizeUri": "请参见下表中的信息",
"tokenUri": "请参见下表中的信息",
"clientAuthScheme": "请参见下表中的信息"
},
"<AuthorizationServerId2>": {
"clientId": "请参见下表中的信息",
"clientSecret": "请参见下表中的信息",
"authorizeUri": "请参见下表中的信息",
"tokenUri": "请参见下表中的信息",
"clientAuthScheme": "请参见下表中的信息"
"mandatoryScopes": "请参见下表中的信息"
},
"OIDCSettings": {
"accessTokenClaimsValidation":"请参见下表中的信息",
"additionalScopes": "请参见下表中的信息",
"assertionUserNameAttributeName": "请参见下表中的信息",
"clientId": "请参见下表中的信息",
"clientSecret": "请参见下表中的信息",
"openIdConfigurationUri": "请参见下表中的信息",
"proxyAuthentication": "请参见下表中的信息",
"useAccessTokenClaims": "请参见下表中的信息"
},
"AzureSettings": {
"apiEndPoint": "请参见下表中的信息"
}
}

务必按照要求对每个参数的值进行编辑。您的实施可能会有所不同，具体取决于多个因素，例如 ThingWorx 的托管位置、您组织的安全策略以及联合的 CAS。根据下表中的信息来设置不同参数的值。

以下表格描述了 sso-settings.json 文件 BasicSettings 部分的不同参数和默认值：

参数

说明

值

clientBaseUrl

指定 ThingWorx 服务器实例的 URL。

将其设置为 ThingWorx 服务器的完全限定域名 (FQDN)。

如果已将 ThingWorx 配置为在高可用性 (HA) 环境下运行，那么请指定负载均衡器的主机和端口。

http://<ThingWorx-FQDN>:<port-number>/Thingworx

或

在高可用性环境中，https://<负载均衡器主机名>:<负载均衡器端口号>/Thingworx

idpMetadataFilePath

仅对 SAML 身份验证为必要参数。指定 IdP 元数据文件的绝对文件路径位置。

/ThingworxPlatform/ssoSecurityConfig/sso-idp-metadata.xml

metadataEntityId

仅对 SAML 身份验证为必要参数。指定服务提供者连接的实体 ID。

• PingFederate 作为 CAS：使用在配置服务提供者连接时所选择的唯一 ID。

• Microsoft Entra ID 作为 CAS：使用在配置基本 SAML 设置时定义的 Identifier (Entitity ID)。

• AD FS 作为 CAS：使用在配置信赖方信任设置时所定义的“信赖方信任标识符”

—

metadataEntityBaseUrl

仅对 SAML 身份验证为必要参数。指定 ThingWorx 服务器的完全限定域名。

建议不要使用非完全限定的域名。如果您的组织选择使用非完全限定的域名，则您的 IT 部门必须确保该域名可由客户端计算机访问，且在 ThingWorx SSO 配置文件中对该域名进行了正确的配置。

如果已将 ThingWorx 配置为在高可用性 (HA) 环境下运行，那么请指定负载均衡器的主机和端口。

http://<ThingWorx-FQDN>:<port-number>/Thingworx

或

在高可用性环境中，https://<负载均衡器主机名>:<负载均衡器端口号>/Thingworx

webSSOProfileConsumerResponseSkew

指定 SAML 2.0 WebSSO Assertion Consumer 响应偏差容限。

设置此值时，请考虑您自己的安全需求以及企业网络中的延迟情况。

使用此设置可确定从 CAS 返回到 ThingWorx 的登录请求响应所允许的时间 (以秒为单位)。如果登录请求响应比此置花费的时间更长，则登录将失败。

偏差容限是接收人所允许的响应有效性偏差范围，造成偏差的原因是各系统时钟之间可能存在的差异。最好确保所涉及的每个系统时钟均能正确同步以最大限度地减小偏差影响。

300

webSSOProfileConsumerReleaseDOM

确定安全框架在身份验证完成后是否保留 SAML 断言。

如果设置为 false，则在身份验证完成后会保持 SAML 断言。

true

webSSOProfileResponseSkew

指定 SAML 2.0 Web SSO 配置文件响应偏差容限。

设置此值时，请考虑您自己的安全需求以及企业网络中的延迟情况。

300

retriggerOnScopesRemoval

指定所需范围的列表是否已更改且必须刷新。

如果将值设置为 true，则表示已从所需范围的列表中添加或移除范围。

如果将值设置为 false，则表示范围已添加到所需范围的列表中。

true

samlAssertionUserNameAttributeName

仅对 SAML 身份验证为必要参数。指定 ThingWorx 用户登录时哪个 SAML 属性具有存储用户名的值。确保标识提供工具中该属性的值与您使用的 ThingWorx 用户名的值一致。

对于 ThingWorx 管理员帐户，必须将用户名值设置为 Administrator。请确保将 IdP 配置为返回管理员帐户的 Administrator 值。有关详细信息，请参阅在标识提供工具中创建 ThingWorx 管理员别名。

• PingFederate 或 Microsoft Entra ID 作为 CAS：

uid

• AD FS 作为 CAS：

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

samlAssertionMaxAuthenticationAge

仅对 SAML 身份验证为必要参数。指定过期之前 SAML 2.0 断言的最大时长 (以秒为单位)。这也指定了身份验证断言的最长会话时间。

该值在设置后应与标识提供工具中所指定的会话超时值相匹配。该值因所使用的 IdP 而异。

• PingFederate 作为具有 LDAP IdP 的 CAS (Windchill)：7200 (此为默认值)

• AD FS 作为 IdP (AD FS 或 PingFederate 作为 CAS)：28800

• Microsoft Entra ID 作为 IdP (Microsoft Entra ID 或 PingFederate 作为 CAS)：86400

ptcOperatorsGroupName

可选。

设置此参数以自动将组 (如 IDP 中所定义) 配置为 ThingWorx 管理员组的一部分

administratorAlias

对于 OIDC 身份验证为必要参数。

CAS[IDP] 中配置的管理员用户名。

administratorInternalName

如果 administratorAlias 已定义，则为必备参数。

ThingWorx 中配置的管理员用户名。例如 Administrator。

samlGroupClaimName

可选，仅对 SAML 身份验证为必要参数。

此参数仅在定义了 ptcOperatorsGroupName 时相关。

输入在 CAS 中配置的 IDP SAML Group Claim Name，以在 Thingworx SSO 身份验证器中完成该组的自动化操作。有关详细信息，请参阅 Thingworx SSO 身份验证器。

示例：

对于 PingFederate CAS：组

对于 ADFS CAS：http://schemas.xmlsoap.org/claims/Group

对于 Microsoft Entra ID CAS：http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

authnContextAsPassword

可选。在少数情况下，IdP 会要求您将下一个声明放入 SAML 请求中。

<saml2p:RequestedAuthnContext Comparison="exact">
<saml2:AuthnContextClassRef xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
urn:oasis:names:tc:SAML:2.0:ac:classes:Password
</saml2:AuthnContextClassRef>
</saml2p:RequestedAuthnContext>

在上述情况下，应定义此属性。

false

authenticationType

可选。身份验证类型：oidc/saml。默认值 = saml

PingFederate 和 ADFS 无需此参数 (因为 saml 为默认值)

对于 Microsoft Entra ID - saml/oidc

对于 Azure AD B2C 和 Atlas IAM - oidc

如果您想要在启用 SSO 的情况下启用应用程序密钥身份验证器，则必须将以下 ApplicationKeySettings 配置部分添加到 BasicSettings 下的 sso-settings.json 设置中。只有当您想要通过 REST API 请求使用应用程序密钥进行身份验证时，才需要执行此操作。无论该设置处于启用还是禁用状态，均可以通过 WebSocket 从边缘设备使用应用程序密钥。

{
"BasicSettings": {
...
},
"ApplicationKeySettings": {
"enabled": true
},
...
}

以下表格描述了 sso-settings.json 文件 AccessTokenPersistenceSettings 部分的不同参数和默认值：

参数	说明	值
dbType	指定配置并用于 ThingWorx 安装的数据库类型。 • 要使用在 platform-settings.json 文件中设置的相同数据库，请指定在 platform-settings.json 中设置的相同数据库类型和凭据。	postgres
dbType		mssql
driverClassName	指定您在 platform-settings.json 文件中使用的驱动类名称。	对于设置为 postgres 的 dbType，可设置为 org.postgresql.Driver。
driverClassName	指定您在 platform-settings.json 文件中使用的驱动类名称。	对于设置为 mssql 的 dbType，可设置为 com.microsoft.sqlserver.jdbc.SQLServerDriver。
url	指定您安装 ThingWorx 的数据库位置的 URL。	对于设置为 postgres 的 dbType，可设置为 jdbc:postgresql://<主机名>:<端口>/thingworx。
url	指定您安装 ThingWorx 的数据库位置的 URL。	对于设置为 mssql 的 dbType，可设置为 jdbc:sqlserver://<主机名>:<端口>;databaseName=thingworx;applicationName=Thingworx。
username	指定您的系统用于存储访问令牌的数据库用户名。此用户名应该与您在 platform-settings.json 文件中指定的用户名相匹配。	—
password	指定您的系统用于存储访问令牌的数据库密码。此密码应该与您在 platform-settings.json 文件中指定的密码相匹配。	—
encryptTokenInDatabase	设置为 true 以在将访问令牌持久保留在数据库之前对其进行加密。	true

根据 dbType 的值，OAuth 2.0 访问令牌 (授权批准) 存储在不同的位置。下表提供了有关授权批准在数据库中的存储位置的信息：

dbType	数据库中用于存储授权批准的位置
postgres	在 ThingWorx PostgreSQL 数据库中的 Oauth_client_token 表中。
mssql	在 ThingWorx MS SQL 数据库中的 Oauth_client_token 表中。

以下表格描述了 sso-settings.json 文件 KeyManagerSettings 部分的不同参数和默认值：

参数

说明

值

keyStoreFilePath

指定密钥库的绝对文件路径位置。根据您的环境，修改路径以使用保存密钥库文件的目录。

强烈建议密钥库密钥文件夹与 sso-settings.json 文件采用不同的存储位置。这样，您就可以对这些文件应用更为细化的文件系统访问控制。ThingWorx 的常规设置应该存储在与密钥库密钥文件夹和 sso-settings.json 文件不同的位置。

对于 Windows：<驱动器>:\\ThingworxPlatform\\ssoSecurityConfig\\sso-keystore.jks

其中 <驱动器> 指定安装有 ThingWorx 的驱动器。

对于 Linux：<完整路径>/ThingworxPlatform/ssoSecurityConfig/sso-keystore.jks

keyStoreStorePass

指定密钥库密码。

—

keyStoreKey

指定默认密钥。

—

keyStoreKeyPass

指定用于访问私人密钥的密码。

—

以下表格描述了 sso-settings.json 文件 AuthorizationServersSettings 部分的不同参数和默认值：

AuthorizationServersSettings 设置可包含不止一个身份验证服务器的信息。每个服务器在 sso settings.json 文件中采用唯一标识符进行标识。

参数

说明

值

<AuthorizationServerId1>.clientId

指定从身份验证服务器获取访问令牌时使用的客户端标识符。

为变量 AuthorizationServerId1 赋值。变量 AuthorizationServerId1 的这一值用于配置 Integration 连接器或媒体实体的连接设置。如果配置连接器设置的管理员或开发人员无权访问 ssoSecurityConfig 目录，则需要将这些信息提供给他们。

—

<AuthorizationServerId1>.clientSecret

指定用于通过身份验证服务器进行身份验证的客户端凭据。

设置为网络上的完全限定域名服务器 URL。

—

<AuthorizationServerId1>.authorizeUri

指定授权访问令牌时作为用户重定向目标的 URI

• PingFederate 作为 CAS：

https://<PingFederate-host-name>:<PingFederate-Port-Number>/as/authorization.oauth2

使用随 PingFederate 安装一起提供的 PingFederate 运行时端口。

• Microsoft Entra ID 作为 CAS：请参阅 Microsoft Entra ID 授权文档中的更新 ThingWorx 配置文件。

• AD FS 作为 CAS：请参阅 AD FS 授权文档中的更新 ThingWorx 配置文件。

<AuthorizationServerId1>.tokenUri

指定用于获取 OAuth2 访问令牌的 URI

设置为网络上的完全限定域名服务器 URL。

https://<PingFederate-host-name>:<PingFederate-Port-Number>/as/token.oauth2

使用随 PingFederate 安装一起提供的 PingFederate 运行时端口。

<AuthorizationServerId1>.clientAuthScheme

指定用于验证客户端的方案。允许的值包括：

• form

• header

• 查询

• 无

form

<AuthorizationServerId1>.mandatoryScopes

对于除 Microsoft Entra ID 和 ADFS 以外的 CAS 为可选参数。定义此参数后，此范围将自动添加到任何请求的 accessToken。

如果有多个范围，请使用空格作为分隔符。

对于作为 CAS 的 Microsoft Entra ID 为必要参数。所需值为 "offline_access"。

对于 ADFS 为必要参数：该参数可以是 ADFS 服务器上范围列表中未定义的任何值。

下表给出了 sso-settings.json 文件 OIDCSettings 部分的不同参数和默认值。仅当身份验证类型为 OIDC 时，才需要此部分。

参数	说明	值
openIdConfigurationUri	必填此为 OpenID 服务器元数据的 URI。其通常发布在知名的 URL 上。
clientId	指定从身份验证服务器获取访问令牌时使用的客户端标识符。
clientSecret	指定用于通过身份验证服务器进行身份验证的客户端凭据。
additionalScopes	可选带有 oidc 授权附加范围并以逗号分隔的字符串
assertionUserNameAttributeName	指定 ThingWorx 用户登录时哪个 openId 声明具有存储 ThingWorx 用户名的值。确保身份提供者中该属性的值与用于 ThingWorx 用户名的值保持一致。对于 Azure AD B2C - 请确保该属性的值在所有身份提供者中均具有唯一性。
accessTokenClaimsValidation	可选指定访问令牌声明是否存在以及是否验证声明值。输入是一个简单的 JSON 字符串，其中每个属性都是一个必要的声明名称，相关值为必要的声明值。如果未提供任何值 (空字符串) - 将仅验证声明名称是否存在。
useAccessTokenClaims	可选指定是否检索用户扩展映射的访问令牌声明。仅在以下情况将该属性设置为 true： • 访问令牌包含 openid 令牌未包括的声明，这些声明是用户扩展所需的。 • 对于 Azure AD B2C - 如果希望使用 AzureSettings.apiEndPoint 检索用户组信息。	true/false
authorizeUriAdditionalParameters	可选 OIDC 身份验证附加参数。

下表给出了 sso-settings.json 文件 AzureSettings 部分的不同参数和默认值。只有具有 OIDC 配置的 Azure Entra ID 才需要此部分。

参数

说明

值

apiEndPoint

可选

Azure 图形端点

仅对组信息检索为必要参数 (前提是 openid/访问令牌不包含组声明)

使用此选项时，OIDCSettings.useAccessTokenClaims 必须设置为 true。

https://graph.microsoft.com/v1.0/

这对您有帮助吗?