配置 sso-settings.json 檔案
 |
如果使用 ThingWorx Flow 9.2 之前的版本，請完成與 ThingWorx Flow 相關的步驟。這些步驟在 ThingWorx Flow 9.2 中會自動進行。如果您已安裝 ThingWorx Flow，則必須先停止所有 ThingWorx Foundation 與 ThingWorx Flow 服務，包括 RabbitMQ 與 Nginx，然後才能配置 sso-settings.json 檔案。配置完此檔案之後，您必須先重新啟動 RabbitMQ，然後再重新啟動所有 ThingWorx Foundation 與 ThingWorx Flow 服務，包括 Nginx。
|
在 ssoSecurityConfig 目錄中建立 sso-settings.json 檔案。
如果您的環境需要使用不同路徑，請設定 THINGWORX_SSO_SETTINGS 環境變數的值，將 sso-settings.json 檔案儲存至不同位置。
以下是 sso-settings.json 檔案的範例結構：
{
"BasicSettings": {
"clientBaseUrl": "請參閱下表中的資訊",
"idpMetadataFilePath": "請參閱下表中的資訊",
"metadataEntityId": "請參閱下表中的資訊",
"metadataEntityBaseUrl": "請參閱下表中的資訊",
"webSSOProfileConsumerResponseSkew": "請參閱下表中的資訊",
"webSSOProfileConsumerReleaseDOM": "請參閱下表中的資訊",
"webSSOProfileResponseSkew": "請參閱下表中的資訊",
"retriggerOnScopesRemoval": "請參閱下表中的資訊",
"samlAssertionUserNameAttributeName": "請參閱下表中的資訊",
"samlAssertionMaxAuthenticationAge": "請參閱下表中的資訊",
"authnContextAsPassword": "請參閱下表中的資訊"
},
"AccessTokenPersistenceSettings": {
"dbType": "請參閱下表中的資訊",
"driverClassName": "請參閱下表中的資訊",
"url": "請參閱下表中的資訊",
"username": "請參閱下表中的資訊",
"password": "請參閱下表中的資訊",
"encryptTokenInDatabase": "請參閱下表中的資訊",
"keyczarKeyFolderPath": "在 9.3 及更新版本中已廢用。請參閱下表中的資訊"
},
"KeyManagerSettings": {
"keyStoreFilePath": "請參閱下表中的資訊",
"keyStoreStorePass": "請參閱下表中的資訊",
"keyStoreKey": "請參閱下表中的資訊",
"keyStoreKeyPass": "請參閱下表中的資訊"
},
"AuthorizationServersSettings": {
"<AuthorizationServerId1>": {
"clientId": "請參閱下表中的資訊",
"clientSecret": "請參閱下表中的資訊",
"authorizeUri": "請參閱下表中的資訊",
"tokenUri": "請參閱下表中的資訊",
"clientAuthScheme": "請參閱下表中的資訊"
},
"<AuthorizationServerId2>": {
"clientId": "請參閱下表中的資訊",
"clientSecret": "請參閱下表中的資訊",
"authorizeUri": "請參閱下表中的資訊",
"tokenUri": "請參閱下表中的資訊",
"clientAuthScheme": "請參閱下表中的資訊"
}
}
}
}
"BasicSettings": {
"clientBaseUrl": "請參閱下表中的資訊",
"idpMetadataFilePath": "請參閱下表中的資訊",
"metadataEntityId": "請參閱下表中的資訊",
"metadataEntityBaseUrl": "請參閱下表中的資訊",
"webSSOProfileConsumerResponseSkew": "請參閱下表中的資訊",
"webSSOProfileConsumerReleaseDOM": "請參閱下表中的資訊",
"webSSOProfileResponseSkew": "請參閱下表中的資訊",
"retriggerOnScopesRemoval": "請參閱下表中的資訊",
"samlAssertionUserNameAttributeName": "請參閱下表中的資訊",
"samlAssertionMaxAuthenticationAge": "請參閱下表中的資訊",
"authnContextAsPassword": "請參閱下表中的資訊"
},
"AccessTokenPersistenceSettings": {
"dbType": "請參閱下表中的資訊",
"driverClassName": "請參閱下表中的資訊",
"url": "請參閱下表中的資訊",
"username": "請參閱下表中的資訊",
"password": "請參閱下表中的資訊",
"encryptTokenInDatabase": "請參閱下表中的資訊",
"keyczarKeyFolderPath": "在 9.3 及更新版本中已廢用。請參閱下表中的資訊"
},
"KeyManagerSettings": {
"keyStoreFilePath": "請參閱下表中的資訊",
"keyStoreStorePass": "請參閱下表中的資訊",
"keyStoreKey": "請參閱下表中的資訊",
"keyStoreKeyPass": "請參閱下表中的資訊"
},
"AuthorizationServersSettings": {
"<AuthorizationServerId1>": {
"clientId": "請參閱下表中的資訊",
"clientSecret": "請參閱下表中的資訊",
"authorizeUri": "請參閱下表中的資訊",
"tokenUri": "請參閱下表中的資訊",
"clientAuthScheme": "請參閱下表中的資訊"
},
"<AuthorizationServerId2>": {
"clientId": "請參閱下表中的資訊",
"clientSecret": "請參閱下表中的資訊",
"authorizeUri": "請參閱下表中的資訊",
"tokenUri": "請參閱下表中的資訊",
"clientAuthScheme": "請參閱下表中的資訊"
}
}
}
}
|
|
請確定有依照需求來編輯每個參數的值。您的實行可能會有所不同且它取決於若干因素，比如 ThingWorx 的主控位置、貴組織的安全性原則，以及用於聯合的 CAS。使用下列表格中的資訊作為指引，設定不同參數的值。
|
下表說明 sso-settings.json 檔案的 BasicSettings 部份裡的不同參數和預設值：
|
參數
|
描述
|
值
|
||||
|---|---|---|---|---|---|---|
|
clientBaseUrl
|
指定 ThingWorx 伺服器實例的 URL。
將此參數設定為 ThingWorx 伺服器的完整網域名稱 (FQDN)。
如果您已安裝 ThingWorx Flow，必須在 URL 中指定 ThingWorx Flow Nginx 主機名稱與 ThingWorx Flow Nginx 埠號。
如果您已將 ThingWorx 配置為在「高可用性」(HA) 環境中運作，則請指定負載平衡器的主機與埠。
|
http://<ThingWorx-FQDN>:<port-number>/Thingworx
或者
針對 ThingWorx Flow，為 https://<ThingWorx Flow Nginx 主機名稱>:<ThingWorx Flow Nginx 埠號>/Thingworx
或者
在高可用性環境中，為 https://<負載平衡器主機名稱>:<負載平衡器埠號>/Thingworx
|
||||
|
idpMetadataFilePath
|
指定 IdP 中繼資料檔案的絕對檔案路徑位置。
|
/ThingworxPlatform/ssoSecurityConfig/sso-idp-metadata.xml
|
||||
|
metadataEntityId
|
指定服務提供者連線的實體 ID。
• 將 PingFederate 作為 CAS：使用您在配置服務提供者連線時選擇的具唯一性 ID。
|
—
|
||||
|
metadataEntityBaseUrl
|
指定 ThingWorx 伺服器完全合格的網域名稱。
如果您已安裝 ThingWorx Flow，請指定 ThingWorx Flow Nginx URL。
如果您已將 ThingWorx 配置為在「高可用性」(HA) 環境中運作，則請指定負載平衡器的主機與埠。
|
http://<ThingWorx-FQDN>:<port-number>/Thingworx
或者
針對 ThingWorx Flow，為 https://<ThingWorx Flow Nginx 主機名稱>:<ThingWorx Flow Nginx 埠號>/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 使用者登入時儲存其使用者名稱的值。請確保識別提供者中此屬性的值與您將用於 ThingWorx 使用者名稱的使用者名稱值一致。
|
• 將 PingFederate 或 Azure AD 作為 CAS：
uid
• 將 AD FS 作為 CAS：
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
|
||||
|
samlAssertionMaxAuthenticationAge
|
指定 SAML 2.0 宣告在到期前的最長存留期 (以秒計)。這也會指定驗證宣告的最長工作階段時間。
請將值設定為符合在識別提供者中指定的工作階段逾時值。根據使用中的 IdP 而定，此值將會有所不同。
|
• 將 PingFederate 作為具有 LDAP IdP 的 CAS (Windchill)：7200 (這是預設)
• 將 AD FS 作為 IdP (且將 AD FS 或 PingFederate 作為 CAS)：28800
• 將 Azure AD 作為 IdP (且將 Azure AD 或 PingFederate 作為 CAS)：86400
|
||||
|
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
|
|
|
如果您想在啟用 SSO 時啟用應用程式金鑰驗證器，必須將下列 ApplicationKeySettings 組態部份新增至 BasicSettings 下的 sso-settings.json 設定。只有在您要使用應用程式金鑰來透過 REST API 請求進行驗證時，才需要執行此操作。無論是啟用還是禁用此設定，都仍然可以透過 WebSocket，從 Edge 裝置使用「應用程式金鑰」。
{
"BasicSettings": { ... }, "ApplicationKeySettings": { "enabled": true }, ... } |
下表說明 sso-settings.json 檔案的 AccessTokenPersistenceSettings 部份裡的不同參數和預設值：
|
參數
|
描述
|
值
|
||
|---|---|---|---|---|
|
dbType
|
指定已配置且用於 ThingWorx 安裝的資料庫類型。
• 欲使用與在 platform-settings.json 檔案中所設定相同的資料庫，請指定與在 platform-settings.json 中所設定相同的資料庫類型與認證。
• 欲針對授權權杖使用專用資料庫，請指定 "default" 值。配置為 "default" 之後，會建立一個新的專用 H2 資料庫。
|
default
|
||
|
H2
|
||||
|
postgres
|
||||
|
mssql
|
||||
|
hana
|
||||
|
driverClassName
|
指定您在 platform-settings.json 檔案中使用的驅動程式類別名稱。
|
針對設定為 default 的 dbType，請設定為 org.h2.Driver。
|
||
|
針對設定為 h2 的 dbType，請設定為 org.h2.Driver。
|
||||
|
針對設定為 postgres 的 dbType，請設定為 org.postgresql.Driver。
|
||||
|
針對設定為 mssql 的 dbType，請設定為 com.microsoft.sqlserver.jdbc.SQLServerDriver。
|
||||
|
針對設定為 hana 的 dbType，請設定為 com.sap.db.jdbc.Driver
|
||||
|
url
|
指定用於 ThingWorx 安裝的資料庫位置 URL。
|
針對設定為 default 的 dbType，請設定為 jdbc:h2:\\<磁碟機>:\\ThingworxPlatform\\ssoSecurityConfig\\sso-oauth2-client-db。
|
||
|
針對設定為 h2 的 dbType，不需要此參數。
|
||||
|
針對設定為 postgres 的 dbType，請設定為 jdbc:postgresql://<主機名稱>:<連接埠>/thingworx。
|
||||
|
針對設定為 mssql 的 dbType，請設定為 jdbc:sqlserver://<主機名稱>:<連接埠>;databaseName=thingworx;applicationName=Thingworx。
|
||||
|
針對設定為 hana 的 dbType，請設定為 jdbc:sap://<IP 位址>:39041/?databaseName=thingworx¤tschema=TWADMIN。
|
||||
|
username
|
指定您系統用來儲存存取權杖之資料庫的使用者名稱。此名稱應符合您在 platform-settings.json 檔案中指定的使用者名稱。
|
—
|
||
|
password
|
指定您系統用來儲存存取權杖之資料庫的密碼。此密碼應符合您在 platform-settings.json 檔案中指定的密碼。
|
—
|
||
|
encryptTokenInDatabase
|
設定為 true 可在將存取權杖保留在資料庫中之前對其進行加密。
• 針對 ThingWorx 9.3 及更新版本：
若將此值設定為 true，系統將在 ThingWorx 啟動時自動建立 private-keyset.cfg 檔案並將其儲存在 ssoSecurityConfig 資料夾中。此金鑰集檔案僅建立一次。
• 針對 ThingWorx 9.2.x 及更早版本：
將 keyczarKeyFolderPath 設定為有效的 keyCzarKey 位置。
|
true
|
||
|
keyczarKeyFolderPath
|
• 針對 ThingWorx 9.3 及更新版本：
Keyczar 工具已廢用，由 Tink 取代。此內容持久儲存至資料庫之前，不再需要加密存取權杖。
• 針對 ThingWorx 9.2.x 及更早版本：
如果將 encryptTokenInDatabase 參數的值設定為 true，則此路徑必須指向有效的 keyCzarKey 位置。修改路徑來使用您的 ThingworxPlatform\ssoSecurityConfig\symmetric 資料夾所在的目錄。
|
• 針對 ThingWorx 9.3 及更新版本：
–
• 針對 ThingWorx 9.2.x 及更早版本：
針對 Windows：<磁碟機>:\\ThingworxPlatform\\ssoSecurityConfig\\symmetric
其中，<磁碟機> 指定您安裝 ThingWorx 的磁碟機。
針對 Linux：<完整路徑>/ThingworxPlatform/ssoSecurityConfig/symmetric
|
根據 dbType 的值而定，OAuth 2.0 存取權杖 (授與核准) 會儲存在不同位置。下表提供資料庫中用來儲存授與核准之位置的相關資訊：
|
dbType
|
資料庫中用來儲存授與核准的位置
|
|---|---|
|
「預設」
|
會根據 url 參數路徑的指定，建立子集 H2 資料庫。依預設，會將資料庫置於相對於 Tomcat 目錄的目錄中。
如果您將 dbType 設定為 default，建議指定 JDBC URL 的完全合格路徑，而不是僅指定相對路徑。
例如：jdbc:h2:./ThingworxPlatform/ssoSecurityConfig/sso-oauth2-client-db
|
|
H2
|
ThingworxStorage/database H2 資料庫檔案中的 H2 ThingWorx war 檔案。
|
|
postgres
|
在 ThingWorx PostgreSQL 資料庫的 oauth_client_token 表中。
|
|
mssql
|
在 ThingWorx MS SQL 資料庫的 oauth_client_token 表中。
|
|
hana
|
在 ThingWorx SAP HANA 資料庫的 oauth_client_token 表中。
|
下表說明 sso-settings.json 檔案的 KeyManagerSettings 部份裡的不同參數和預設值：
|
參數
|
描述
|
值
|
||
|---|---|---|---|---|
|
keyStoreFilePath
|
指定金鑰庫的絕對檔案路徑位置。可根據您的環境，路徑改為使用儲存您的金鑰庫檔案的目錄。
|
針對 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>.clientSecret
|
指定用來透過授權伺服器執行驗證的用戶端認證。
設定為網路上完全合格的網域名稱伺服器 URL。
|
—
|
||
|
<AuthorizationServerId1>.authorizeUri
|
指定將使用者重新導向以便授權存取權杖的 URI。
|
• 將 PingFederate 作為 CAS：
https://<PingFederate 主機名稱>:<PingFederate 埠號>/as/authorization.oauth2
• 將 Azure AD 作為 CAS：請參閱「Azure AD 授權」文件集中的更新 ThingWorx 組態檔案。
• 將 FS 作為 CAS：請參閱「AD FS 授權」文件集中的更新 ThingWorx 組態檔案。
|
||
|
<AuthorizationServerId1>.tokenUri
|
指定用來取得 OAuth2 存取權杖的 URI。
設定為網路上完全合格的網域名稱伺服器 URL。
|
https://<PingFederate 主機名稱>:<PingFederate 埠號>/as/token.oauth2
|
||
|
<AuthorizationServerId1>.clientAuthScheme
|
指定用來驗證用戶端的配置。允許的值包括：
• form
• header
• query
• none
|
form
|