Security > Single Sign-on Authentication > Configure ThingWorx for Single Sign-On > Configure the sso-settings.json File
  
Configure the sso-settings.json File
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"
},
"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 and it depends 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.
Basic Settings
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.
http://<host-name>:<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.
* 
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
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
Application Key Settings
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 if you want to use Application Keys for authentication through REST API requests or to utilize a Remote Access Client (RAC) with a ThingWorx server that has SSO authentication enabled. Application Keys can still be used from edge devices through WebSockets whether this setting is enabled or disabled.
Using the Remote Access Client with a ThingWorx Server that has SSO Authentication Enabled
* 
The enabled and allowedEndpoint settings are available in ThingWorx 8.4.3+.
To use a Remote Access Client when SSO is enabled, additional settings must be added to the sso-settings.json file that allows Application Keys as a valid authentication credential to ThingWorx Server URI endpoints. If endpoints are not specified within that configuration, then all ThingWorx Server endpoints are allowed to be accessible via Application Keys. If endpoints are specified, then Application Keys can only be used as an authentication credential on the URI endpoints that start with the URL endpoint specified (i.e. match exactly or are sub-resources of those specified allowed URI endpoints); thus resulting in a whitelist configuration.
* 
The following configuration is necessary only if you are using the Remote Access Client when SSO is enabled. If SSO is enabled, but you do not need remote access, do not include these settings in your sso-settings.json file.
{
...
,
"ApplicationKeySettings": {
"enabled": true,
"allowedEndpoints": [
{
"uri": "/WSTunnelClient",
"method": "GET"
},
{
"uri": "/WSTunnelServer",
"method": "GET"
}
]
}
}
* 
You can further filter requests to a given endpoint by specifying the HTTP Method used to access the endpoint. More details per configuration setting are discussed in the table below.
Parameter
Description
Default Value
ApplicationKeySettings
Provides control over allowing and disallowing Application Keys as credentials for accessing the ThingWorx HTTP Request based URL endpoints (excluded websocket endpoints) when SSO is enabled.
If the EnableSSO setting is false in the platform-settings.json file and if this configuration is present, neither it nor the sso-settings.json is utilized to configure the ThingWorx server runtime behavior.
If the EnableSSO setting is true in the platform-settings.json file and if this configuration is present, it and its sub-element configuration will be utilized to configure the ThingWorx server runtime behavior.
n/a
enabled
Enables or disables Application Keys as credentials in addition to SSO-based authentication across ThingWorx server URI endpoints.
The endpoints that can be accessed with an Application Key depend on if there is additional allowedEndpoints configuration.
false- disables Application Keys as a credential across all HTTP Request based URI endpoints (excluding websocket endpoints) when SSO is enabled.
true-enables Application Keys as a credential across all HTTP Request based URI endpoints (excluding websocket endpoints) when SSO is enabled if there are no allowedEndpoints URL endpoint configurations specified.
false
allowedEndpoints
This setting allows control over which ThingWorx Server URI endpoints can be accessed when an Application Key credential is used for authentication. This setting is an array of URI JSON object configurations.
Each URI JSON object row of this array must be a well formed JSON object with the following string properties.
uri - The URI resource within ThingWorx endpoints. The value is assumed to be a sub URI of the /Thingworx URI, therefore Thingworx does not need to be specified. The uri string value specified is interpreted as any URI that starts with this value, including but not limited to the exact match of this URI.
method - Optional case sensitive string value that must match the HTTP requests that are made to the endpoint URI with an Application Key. If a method value is not specified, then all HTTP methods are allowed ( PUT, POST, GET, DELETE, and so on).
An example of a URI JSON Object:
{ "uri": "/Things/Thing1/services/Service1", "method": "POST" }
Multiple URI JSON Objects are comma separated in the array [] brackets. An example of this is:
{ "uri": "/Things/a", "method": "GET" },
{ "uri": "/Things/b", "method": "GET" }
Example Values and their Runtime Behavior Impact:
If the allowedEndpoints configuration is specified, but endpoints are not set, then Application Keys cannot be used on any URL endpoint. This has the same behavior as setting the enabled parameter to false.
If the allowedEndpoints configuration is specified, and URI endpoint configurations are set, then Application Keys can only be used as credentials on endpoints that start with the specified URI. By specifying URI endpoints, you can create a whitelist of endpoints that can be accessed via Application Keys. See the example configurations below.
none
Example Configuration that allows RAC tunneling to work with SSO
{
...
,
"ApplicationKeySettings": {
"enabled": true,
"allowedEndpoints": [
{
"uri": "/WSTunnelClient",
"method": "GET"
},
{
"uri": "/WSTunnelServer",
"method": "GET"
}
]
}
}
SAML Context Provider Settings
* 
If ThingWorx is configured with a reverse-proxy server or a load balancer, you must add the following SAMLContextProviderSettings configuration under BasicSettings in the sso-settings.json file:
“BasicSettings”: {
…..
},
"SAMLContextProviderSettings": {
"scheme": "<URL scheme>",
"serverName": "<reverse-proxy server host name>",
"serverPort": "<reverse-proxy server port>",
"includeServerPortInRequestURL": "<true or false>",
"contextPath": "<contextPath>"
},
Parameter
Description
Value
scheme
The scheme for the URL.
http or https
serverName
The reverse proxy or load balancer server host name.
<host-name>
serverPort
The reverse proxy or load balancer server port number.
An integer value. For example, 443.
includeServerPortInRequestURL
A flag to indicate whether to include the port in the request URL.
true or false
contextPath
The context path. The context path is required and must start with a forward slash.
For example: /Thingworx
Access Token Persistence Settings
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. Specify the same database type in the platform-settings.json file.
Ensure that you at least password-protect the database.
default
* 
This “default” database type is the default selection for SSO settings.
H2
* 
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.
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 (grants approvals) are stored in different locations. The following table provides information about the location in the database where grants 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.
Key Manager Settings
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.
Authorization Servers Settings
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 runtime 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 runtime 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