配置 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 驗證為必要。指定哪個 SAML 屬性擁有會在 ThingWorx 使用者登入時儲存其使用者名稱的值。請確保識別提供者中此屬性的值與您將用於 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 驗證器中該群組的自動化。如需詳細資訊，請造訪 ThingworxSSOAuthenticator。

範例：

針對 PingFederate CAS：group

針對 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 變數的這個值用來為「整合連接器」或媒體實體配置連線設定。如果配置連接器設定的管理員或開發人員沒有 ssoSecurityConfig 目錄的存取權，您會需要提供這項資訊給他們。

—

<AuthorizationServerId1>.clientSecret

指定用來透過授權伺服器執行驗證的用戶端認證。

設定為網路上完全合格的網域名稱伺服器 URL。

—

<AuthorizationServerId1>.authorizeUri

指定將使用者重新導向以便授權存取權杖的 URI。

• 將 PingFederate 作為 CAS：

https://<PingFederate 主機名稱>:<PingFederate 埠號>/as/authorization.oauth2

使用 PingFederate 安裝隨附的 PingFederate 執行時間埠。

• 將 Microsoft Entra ID 作為 CAS：請參閱「Microsoft Entra ID 授權」文件集中的更新 ThingWorx 組態檔案。

• 將 FS 作為 CAS：請參閱「AD FS 授權」文件集中的更新 ThingWorx 組態檔案。

<AuthorizationServerId1>.tokenUri

指定用來取得 OAuth2 存取權杖的 URI。

設定為網路上完全合格的網域名稱伺服器 URL。

https://<PingFederate 主機名稱>:<PingFederate 埠號>/as/token.oauth2

使用 PingFederate 安裝隨附的 PingFederate 執行時間埠。

<AuthorizationServerId1>.clientAuthScheme

指定用來驗證用戶端的配置。允許的值包括：

• form

• header

• query

• none

form

<AuthorizationServerId1>.mandatoryScopes

對於除 Microsoft Entra ID 與 ADFS 之外的 CAS 而言為選用。當定義此參數時，會將此範圍自動新增至任何請求的 accessToken。

如果有多個範圍，請使用空格作為分隔符號。

對於將 Microsoft Entra ID 作為 CAS 而言為必要。所需值為 "offline_access"。

對 ADFS 而言為必填：這可以是未在 ADFS 伺服器上範圍清單中定義的任何值。

下表描述 sso-settings.json 檔案 OIDCSettings 區段的不同參數與預設值。只有當驗證類型為 OIDC 時，此區段才為必要。

參數	描述	值
openIdConfigurationUri	必填這是 OpenID 伺服器中繼資料的 URI。它通常會在知名 URL 上發佈。
clientId	指定從授權伺服器取得存取權杖時所要使用的用戶端識別元。
clientSecret	指定用來透過授權伺服器執行驗證的用戶端認證。
additionalScopes	選用包含 oidc 授權其他範圍的逗號分隔字串
assertionUserNameAttributeName	指定哪個 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 Graph 端點

僅對於群組資訊擷取而言為必要 (如果 openid/存取權杖不包含群組宣告)

使用此選項時，必須將 OIDCSettings.useAccessTokenClaims 設定為 true。

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

這是否有幫助?