ThingWorx Model Definition in Composer > Security > Single Sign-on Authentication > Configure ThingWorx for Single Sign-On > Configure the sso-settings.json File
Configure the sso-settings.json File
* 
If you have installed ThingWorx Flow on a ThingWorx Foundation instance that you are configuring for SSO, 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",
"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": "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"
}
}
}
}
* 
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 of the ThingWorx server.
If you have installed ThingWorx Flow, then specify the ThingWorx Flow Nginx URL.
http://<host-name>:<port-number>/Thingworx
OR
https://<ThingWorx Flow Nginx host-name>:<ThingWorx Flow Nginx 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.
This is the unique ID that you chose when configuring the service provider connection in PingFederate.
—
metadataEntityBaseUrl
Specifies the fully qualified domain name of the ThingWorx server. This value is the same as the ThingWorx browser URL.
If you have installed ThingWorx Flow, then specify the ThingWorx Flow Nginx URL.
* 
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.
http://<host-name>:<port-number>/Thingworx
OR
https://<ThingWorx Flow Nginx host-name>:<ThingWorx Flow Nginx 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.
uid
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.
7200 seconds
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.
true
keyczarKeyFolderPath
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 Windows: <drive>:\\ThingworxPlatform\\ssoSecurityConfig\\symmetric
where <drive> specifies the drive where you have installed ThingWorx.
For Linux: \\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: \\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.
https://<PingFederate-host-name>:<PingFederate-Port-Number>/as/authorization.oauth2
* 
Use the PingFederate run time port that is provided with the PingFederate installation.
<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
Was this helpful?