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
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": "See information in the table below",
"samlGroupClaimName": "See information in the table below",
"administratorAlias": "See information in the table below",
"administratorInternalName": "Administrator",
"authnContextAsPassword": "See information in the table below",
"authenticationType": "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",
},
"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"
},
"OIDCSettings": {
"accessTokenClaimsValidation":"See information in the table below",
"additionalScopes": "See information in the table below",
"assertionUserNameAttributeName": "See information in the table below",
"clientId": "See information in the table below",
"clientSecret": "See information in the table below",
"openIdConfigurationUri": "See information in the table below",
"proxyAuthentication": "See information in the table below",
"useAccessTokenClaims": "See information in the table below"
},
"AzureSettings": {
"apiEndPoint": "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 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
In a High Availability environment, https://<Load balancer host-name>:<Load balancer port-number>/Thingworx
idpMetadataFilePath
Mandatory for SAML authentication only. Specifies the absolute file path location of the IdP metadata file.
/ThingworxPlatform/ssoSecurityConfig/sso-idp-metadata.xml
metadataEntityId
Mandatory for SAML authentication only. 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
Mandatory for SAML authentication only. 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 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
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
Mandatory for SAML authentication only. 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
Mandatory for SAML authentication only. 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
administratorAlias
Mandatory for OIDC authentication.
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.
samlGroupClaimName
Optional, but mandatory for SAML authentication only.
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
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
authenticationType
Optional. The authentication type: oidc/saml. Default value = saml
Not required for PingFederate and ADFS (as saml is the default)
For Microsoft Entra ID– saml/oidc
For Azure AD B2C and Atlas IAM - oidc
* 
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.
postgres
mssql
driverClassName
Specifies the driver class name that you use in the platform-settings.json file.
For dbType set as postgres, set to org.postgresql.Driver.
For dbType set as mssql, set to com.microsoft.sqlserver.jdbc.SQLServerDriver.
url
Specifies the URL to the database location for your ThingWorx installation.
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.
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.
—
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.
—
encryptTokenInDatabase
Set to true to encrypt the access token before persisting it in the database.
true
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
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.
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
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.
The following table describes the different parameters and default values of the OIDCSettings section of the sso-settings.json file. This section is required only if the authentication Type is OIDC.
Parameter
Description
Value
openIdConfigurationUri
Mandatory
This is the URI for the OpenID server metadata.
It is typically published at a well-known URL.
clientId
Specifies the client identifier to use when obtaining access tokens from the Auth server.
clientSecret
Specifies the client credentials that are used to authenticate with the auth server.
additionalScopes
Optional
A comma separated string with additional scopes for the oidc authorization
assertionUserNameAttributeName
Specifies which openId claim 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 Azure AD B2C – make sure that the value of this attribute is unique among all identity providers.
accessTokenClaimsValidation
Optional
Specifies access token claims existence and claims value validation.
The input is a simple JSON string where each property is a required claim name and the value is the required claim value. If no value is provided (empty string) – only the claim name existence will be validated.
useAccessTokenClaims
Optional
Specifies whether to retrieve access token claims for user extension mapping.
Set this property to true only if:
• The access token contains claims that are not included in the openid token and are required for user extension.
• For Azure AD B2C — if you wish to retrieve user group information using AzureSettings.apiEndPoint.
true/false
authorizeUriAdditionalParameters
Optional
OIDC authentication additional parameters.
The following table describes the different parameters and default values of the AzureSettings section of the sso-settings.json file. This section is required only for Azure Entra ID with OIDC configuration.
Parameter
Description
Value
apiEndPoint
Optional
Azure Graph endpoint
Required only for group information retrieval (if openid/access token does not contain group claim)
* 
When using this option, OIDCSettings.useAccessTokenClaims must be set to true.
https://graph.microsoft.com/v1.0/
Was this helpful?