Installation and Upgrade > Installing ThingWorx > Security Configuration > Single Sign-on Authentication > Configure ThingWorx for Single Sign-On > Configure the sso-settings.json File
Configure the sso-settings.json File
* 
Complete the steps related to ThingWorx Flow if you are on earlier versions than ThingWorx Flow 9.2. The steps are automated in ThingWorx Flow 9.2. If you have installed ThingWorx Flow, you must stop all ThingWorx Foundation and ThingWorx Flow services, including RabbitMQ and Nginx, before you configure the sso-settings.json file. After configuring this file, you must restart RabbitMQ first, and then all ThingWorx Foundation and ThingWorx Flow services, including Nginx.
Create the sso-settings.json file in the ssoSecurityConfig directory.
If your environment requires a different path, set the value of the THINGWORX_SSO_SETTINGS environment variable to save the sso-settings.json file to a different location.
The following is a sample structure of the sso-settings.json file:
{
"BasicSettings": {
"clientBaseUrl": "See information in the table below",
"idpMetadataFilePath": "See information in the table below",
"metadataEntityId": "See information in the table below",
"metadataEntityBaseUrl": "See information in the table below",
"webSSOProfileConsumerResponseSkew": "See information in the table below",
"webSSOProfileConsumerReleaseDOM": "See information in the table below",
"webSSOProfileResponseSkew": "See information in the table below",
"retriggerOnScopesRemoval": "See information in the table below",
"samlAssertionUserNameAttributeName": "See information in the table below",
"samlAssertionMaxAuthenticationAge": "See information in the table below",
"ptcOperatorsGroupName": " New parameter for 9.4.1 and later. See information in the table below",
"samlGroupClaimName": " New parameter for 9.4.2 and later. See information in the table below",
"administratorAlias": "See information in the table below",
"administratorInternalName": "Administrator",
"authnContextAsPassword": "See information in the table below"
},
"AccessTokenPersistenceSettings": {
"dbType": "See information in the table below",
"driverClassName": "See information in the table below",
"url": "See information in the table below",
"username": "See information in the table below",
"password": "See information in the table below",
"encryptTokenInDatabase": "See information in the table below",
"keyczarKeyFolderPath": "Deprecated from 9.3 and later. See information in the table below"
},
"KeyManagerSettings": {
"keyStoreFilePath": "See information in the table below",
"keyStoreStorePass": "See information in the table below",
"keyStoreKey": "See information in the table below",
"keyStoreKeyPass": "See information in the table below"
},
"AuthorizationServersSettings": {
"<AuthorizationServerId1>": {
"clientId": "See information in the table below",
"clientSecret": "See information in the table below",
"authorizeUri": "See information in the table below",
"tokenUri": "See information in the table below",
"clientAuthScheme": "See information in the table below"
},
"<AuthorizationServerId2>": {
"clientId": "See information in the table below",
"clientSecret": "See information in the table below",
"authorizeUri": "See information in the table below",
"tokenUri": "See information in the table below",
"clientAuthScheme": "See information in the table below"
"mandatoryScopes": "See information in the table below"
}
}
}
}
* 
Ensure that you edit the value of every parameter as per your requirement. Your implementation might vary depending on several factors, such as where ThingWorx is hosted, the security policies of your organization, and the CAS for your federation. Use the information in the following tables as guidance to set values of different parameters.
The following table describes the different parameters and default values of the BasicSettings section of the sso-settings.json file:
Parameter
Description
Value
clientBaseUrl
Specifies the URL of the ThingWorx server instance.
Set this to the fully qualified domain name (FQDN) of the ThingWorx server.
If you have installed ThingWorx Flow, then you must specify the ThingWorx Flow Nginx host name and ThingWorx Flow Nginx port number in the URL.
If you have configured ThingWorx to operate in a High Availability (HA) environment, then specify the host and port of the load balancer.
http://<ThingWorx-FQDN>:<port-number>/Thingworx
OR
For ThingWorx Flow, https://<ThingWorx Flow Nginx host-name>:<ThingWorx Flow Nginx port-number>/Thingworx
OR
In a High Availability environment, https://<Load balancer host-name>:<Load balancer port-number>/Thingworx
idpMetadataFilePath
Specifies the absolute file path location of the IdP metadata file.
/ThingworxPlatform/ssoSecurityConfig/sso-idp-metadata.xml
metadataEntityId
Specifies the entity ID of the service provider connection.
• PingFederate as CAS: Use the unique ID you chose when configuring the service provider connection.
• Microsoft Entra ID as CAS: Use the Identifier (Entitity ID) you defined when configuring the Basic SAML settings.
• AD FS as CAS: Use the Relying party trust identifier you defined when configuring relying party trust settings
—
metadataEntityBaseUrl
Specifies the fully qualified domain name of the ThingWorx server.
* 
It is not recommended to use domain names that are not fully qualified. If your organization chooses to use a non-fully-qualified domain name, then the IT department must ensure that the domain name is accessible by client machines and is configured correctly within the ThingWorx SSO configuration files.
If you have installed ThingWorx Flow, then specify the ThingWorx Flow Nginx URL.
* 
Complete this step if you are on earlier versions than ThingWorx Flow 9.2. This step is automated in ThingWorx Flow 9.2.
If you have configured ThingWorx to operate in a High Availability (HA) environment, then specify the host and port of the load balancer.
http://<ThingWorx-FQDN>:<port-number>/Thingworx
OR
For ThingWorx Flow, https://<ThingWorx Flow Nginx host-name>:<ThingWorx Flow Nginx port-number>/Thingworx
OR
In a High Availability environment, https://<Load balancer host-name>:<Load balancer port-number>/Thingworx
webSSOProfileConsumerResponseSkew
Specifies the SAML 2.0 WebSSO assertion consumer response skew tolerance.
When setting this value, consider your own security requirements as well as latency in your enterprise network.
Use this setting to establish the amount of time (in seconds) that is allowed for a login request response to be returned from the CAS to ThingWorx. If the login request response takes longer than this value, then the login attempt fails.
Skew tolerance is the deviation in response validity that the recipient allows due to presumed differences between system clocks. It is a best practice to minimize the effects of skew by ensuring that the clocks of each system involved are properly synchronized.
300
webSSOProfileConsumerReleaseDOM
Determines whether the security framework holds onto the SAML assertion after authentication is complete.
If set to false, SAML assertion is held after authentication is complete.
true
webSSOProfileResponseSkew
Specifies the SAML 2.0 Web SSO profile response skew tolerance.
When setting this value, consider your own security requirements as well as latency in your enterprise network.
Skew tolerance is the deviation in response validity that the recipient allows due to presumed differences between system clocks. It is a best practice to minimize the effects of skew by ensuring that the clocks of each system involved are properly synchronized.
300
retriggerOnScopesRemoval
Specifies whether the list of required scopes has changed and must be refreshed.
If the value is set to true, it indicates that a scope was added or removed from the list of required scopes.
If the value is set to false, it indicates that a scope was added to the list of required scopes.
true
samlAssertionUserNameAttributeName
Specifies which SAML attribute carries the value that stores the user names of ThingWorx users when they log in. Ensure that the value of this attribute in the identity provider aligns with the user name values that you would use for ThingWorx user names.
* 
For the ThingWorx administrator account, the user name value must be set to Administrator. Ensure that you configure your IdP to return the Administrator value for the administrator account. For more information, see Create ThingWorx Administrator Alias in Identity Provider.
• PingFederate or Microsoft Entra ID as CAS:
uid
• AD FS as CAS:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
samlAssertionMaxAuthenticationAge
Specifies the maximum age (in seconds) of the SAML 2.0 assertion before it expires. This also specifies the maximum session time for an authentication assertion.
Set the value to match the session time-out value specified in the identity provider. This value will differ based on which IdP is in use.
• PingFederate as CAS with LDAP IdP (Windchill): 7200 (this is the default)
• AD FS as IdP (with AD FS or PingFederate as CAS): 28800
• Microsoft Entra ID as IdP (with Microsoft Entra ID or PingFederate as CAS): 86400
ptcOperatorsGroupName
Optional.
Set this parameter to configure a group (as defined in IDP) to be a part of the ThingWorx Administrators Group automatically
samlGroupClaimName
Optional.
This parameter is relevant only when ptcOperatorsGroupName is defined.
Enter the IDP SAML Group Claim Name configured in CAS to complete the automation for that group in Thingworx SSO Autheticator. For more information, see ThingworxSSOAuthenticator.
Examples:
For PingFederate CAS : group
For ADFS CAS : http://schemas.xmlsoap.org/claims/Group
For Microsoft Entra ID CAS: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
administratorAlias
Optional.
The administrator username as it is configured in CAS[IDP].
administratorInternalName
Mandatory if administratorAlias is defined.
The administrator username as it is configured in ThingWorx.
For example, Administrator.
authnContextAsPassword
Optional. In some rare cases, IdP requires you to put next assertion into the SAML Request.
<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>
In those cases, you should define this property.
false
* 
If you want to enable the application key authenticator when SSO is enabled, you must add the following ApplicationKeySettings configuration section to the sso-settings.json settings under BasicSettings. This is required only if you want to use Application Keys for authentication through REST API requests. Application keys can still be used from edge devices through WebSockets whether this setting is enabled or disabled.
{
"BasicSettings": {
...
},
"ApplicationKeySettings": {
"enabled": true
},
...
}
The following tables describe the different parameters and default values of the AccessTokenPersistenceSettings section of the sso-settings.json file:
Parameter
Description
Value
dbType
Specifies the type of database that is configured and used for the ThingWorx installation.
• To use the same database as set in the platform-settings.json file, specify the same database type and credential as set in platform-settings.json.
• To use a dedicated database for the authorization token, specify “default” value. Once configured as “default,” a new dedicated H2 database is created.
default
* 
This “default” database type is the default selection for SSO settings.
H2
postgres
mssql
hana
driverClassName
Specifies the driver class name that you use in the platform-settings.json file.
For dbType set as default, set to org.h2.Driver.
For dbType set as h2, set to org.h2.Driver.
For dbType set as postgres, set to org.postgresql.Driver.
For dbType set as mssql, set to com.microsoft.sqlserver.jdbc.SQLServerDriver.
For dbType set as hana, set to com.sap.db.jdbc.Driver
url
Specifies the URL to the database location for your ThingWorx installation.
For dbType set as default, set to jdbc:h2:\\<drive>:\\ThingworxPlatform\\ssoSecurityConfig\\sso-oauth2-client-db.
For dbType set as h2, this parameter is not required.
For dbType set as postgres, set to jdbc:postgresql://<hostname>:<port>/thingworx.
For dbType set as mssql, set to jdbc:sqlserver://<hostname>:<port>;databaseName=thingworx;applicationName=Thingworx.
For dbType set as hana, set to jdbc:sap://<ip_address>:39041/?databaseName=thingworx&currentschema=TWADMIN.
username
Specifies the user name for the database that your system uses to store access tokens. This should match the username that you specified in the platform-settings.json file.
* 
When SSO is enabled in ThingWorx, the H2 database needs to be password protected. For more information, see Password-Protect H2 Database When ThingWorx is SSO Enabled.
—
password
Specifies the password for the database that your system uses to store access tokens. This should match the password that you specified in the platform-settings.json file.
* 
When SSO is enabled in ThingWorx, the H2 database needs to be password protected. For more information, see Password-Protect H2 Database When ThingWorx is SSO Enabled.
—
encryptTokenInDatabase
Set to true to encrypt the access token before persisting it in the database.
For ThingWorx 9.2.x and earlier:
Set the keyczarKeyFolderPath to a valid keyCzarKey location.
true
keyczarKeyFolderPath
• For ThingWorx 9.3 and later:
The Keyczar tool has been deprecated and replaced by Tink. This property is no longer required to encrypt access tokens before they are persisted to the database.
• For ThingWorx 9.2.x and earlier:
If the value of the encryptTokenInDatabase parameter is set to true, then this path must point to a valid keyCzarKey location. Modify the path to use the directory where your ThingworxPlatform\ssoSecurityConfig\symmetric folder is located.
* 
It is highly recommended to use a storage location for the keystore key that is different from where the sso-settings.json file is stored. Thus, you can apply more granular file system access controls to these files. The general settings for ThingWorx should be stored in a different location from the keystore key folder and the sso-settings.json file.
• For ThingWorx 9.3 and later:
–
• For ThingWorx 9.2.x and earlier:
For Windows: <drive>:\\ThingworxPlatform\\ssoSecurityConfig\\symmetric
where <drive> specifies the drive where you have installed ThingWorx.
For Linux: <full path>/ThingworxPlatform/ssoSecurityConfig/symmetric
Depending on the value of dbType, the OAuth 2.0 access tokens (grant approvals) are stored in different locations. The following table provides information about the location in the database where grant approvals are stored:
dbType
Location in the database where grants approvals are stored
default
A subset H2 database is created as specified by the path of the url parameter. By default, the database is placed in a directory that is relative to the Tomcat directory.
If you set dbType as default, it is recommended that you specify the fully qualified path of the JDBC URL, and not the relative path only.
For example: jdbc:h2:./ThingworxPlatform/ssoSecurityConfig/sso-oauth2-client-db
H2
H2 ThingWorx war files in the ThingworxStorage/database H2 database files.
postgres
In the oauth_client_token table in the ThingWorx PostgreSQL database.
mssql
In the oauth_client_token table in the ThingWorx MS SQL database.
hana
In the oauth_client_token table in the ThingWorx SAP HANA database.
The following table describes the different parameters and default values of the KeyManagerSettings section of the sso-settings.json file:
Parameter
Description
Value
keyStoreFilePath
Specifies the absolute file path location of the keystore. According to your environment, modify the path to use the directory where your keystore file is saved.
* 
It is highly recommended to use a storage location for the keystore key that is different from where the sso-settings.json file is stored. Thus, you can apply more granular file system access controls to these files. The general settings for ThingWorx should be stored in a different location from the keystore key and the sso-settings.json file.
For Windows: <drive>:\\ThingworxPlatform\\ssoSecurityConfig\\sso-keystore.jks
where <drive> specifies the drive where you have installed ThingWorx.
For Linux: <full path>/ThingworxPlatform/ssoSecurityConfig/sso-keystore.jks
keyStoreStorePass
Specified the keystore password.
—
keyStoreKey
Specifies the default key.
—
keyStoreKeyPass
Specifies the password used to access private keys.
—
The following table describes the different parameters and default values of the AuthorizationServersSettings section of the sso-settings.json file:
* 
The AuthorizationServersSettings settings might contain information for more than one Auth server. Each server is identified by a unique identifier in the sso-settings.json file.
Parameter
Description
Value
<AuthorizationServerId1>.clientId
Specifies the client identifier to use when obtaining access tokens from the Auth server.
* 
Choose a value to provide for the AuthorizationServerId1 variable. This value of the AuthorizationServerId1 variable is used to configure the connection settings for an Integration Connector or media entity. If the administrator or developer that configures connector settings does not have access to the ssoSecurityConfig directory, then you need to provide this information to them.
—
<AuthorizationServerId1>.clientSecret
Specifies the client credentials that are used to authenticate with the auth server.
Set to the fully qualified domain name server URL on the network.
—
<AuthorizationServerId1>.authorizeUri
Specifies the URI to which the user is to be redirected to authorize an access token.
• PingFederate as CAS:
https://<PingFederate-host-name>:<PingFederate-Port-Number>/as/authorization.oauth2
* 
Use the PingFederate run time port that is provided with the PingFederate installation.
• Microsoft Entra ID as CAS: See Update the ThingWorx Configuration Files in the Microsoft Entra ID Authorization documentation.
• AD FS as CAS: See Update the ThingWorx Configuration Files in the AD FS Authorization documentation.
<AuthorizationServerId1>.tokenUri
Specifies the URI to use to obtain an OAuth2 access token.
Set to the fully qualified domain name server URL on the network.
https://<PingFederate-host-name>:<PingFederate-Port-Number>/as/token.oauth2
* 
Use the PingFederate run time port that is provided with the PingFederate installation.
<AuthorizationServerId1>.clientAuthScheme
Specifies the scheme to use to authenticate the client. The allowed values are:
• form
• header
• query
• none
form
<AuthorizationServerId1>.mandatoryScopes
* 
Available from 9.3.8, 9.4, and later.
Optional for CAS other than Microsoft Entra ID and ADFS. This scope will be automatically added to any requested accessToken when this parameter is defined.
* 
If there is more than one scope, use space as a delimiter.
Mandatory for Microsoft Entra ID as CAS. Required value is "offline_access".
Mandatory for ADFS: This can be any value that is not defined in the list of scopes on the ADFS server.
Was this helpful?