Install and Configure the Experience Service > Configuration Parameters
  
Configuration Parameters
* 
If the installer is used to install the Experience Service, these parameters are configured by the installer.
This section describes the different configuration parameters that can be used to configure various aspects of your Experience Service. The values for these configuration parameters can be specified using any of the following methods:
1. Specify the values of the configuration parameters on the command line when starting the service. This can be done by entering the parameter name on the command line prefixed with a double dash (--) and followed immediately with the parameter value. For example, --port 3000.
2. Use environment variables to specify values for configuration parameters. This can be done by creating an environment variable with a name corresponding to the configuration parameter and setting the value of the environment variable equal to the desired parameter value. The name of the environment variable should be equal to the configuration parameter, except in the case of nested configuration parameters. In this case, a double underscore (__) must be used as the separator instead of dot (.). For example, to specify the value of db.connectionString, create an environment variable named db__connectionString.
3. Specify the values of the configuration parameters in the service’s configuration.json file found in the root installation directory.
Basic Authentication Configuration Parameters
* 
If you’re configuring for single sign-on authentication, see the “Single Sign-on (SSO) Authentication Configuration Parameters” section below.
The Experience Service uses ThingWorx for authentication. The installer configures the Experience Service to use the ThingWorx server that you identify during installation for authentication.
If necessary, you can manually configure authentication using the following configuration parameters:
Parameter
Description
authentication.type
If using Basic Authentication, this parameter must be set to twxUser.
authentication.baseURL
The URL for the ThingWorx server that is used for authentication. For example: https://twx.example.com:8443
authentication.authorization.appKey
The ThingWorx application key that is used by the Experience Service to read the memberships of ThingWorx groups. The group memberships are used to determine which Experience Service role a user belongs to and the permissions that have been granted to that user.
For more information about configuring the authorization application key, see Configure Access to ThingWorx Group Memberships.
authentication.authorization.refreshRate
This parameter determines how frequently the membership of Experience Service roles are synchronized with the membership of ThingWorx groups. The value specified is in milliseconds.
By default, this is set to 5 minutes. The fastest rate this can be set to is 30 seconds.
Single Sign-on (SSO) Authentication Configuration Parameters
This section describes additional authentication configuration parameters and modifications to existing configuration parameters provided to support Experience Service SSO configuration.
Parameter
Description
authentication.type
This must be set to openidUser when configuring the Experience Service to use SSO.
authentication.baseUrl
The URL for the ThingWorx server that is used for authentication when basic authentication is used and used for group membership synchronization regardless of the authentication type. For example, https://twx.example.com:8443.
authentication.authorization.refreshRate
This parameter determines how frequently the membership of Experience Service roles are synchronized with the membership of ThingWorx groups. The value specified is in milliseconds.
By default, this is set to 5 minutes. The fastest rate this can be set to is 30 seconds.
authentication.openid.issuer
Set this equal to the <as-base-url> parameter identified in the “SSO Configuration Parameters” section in PingFederate Configuration.
authentication.openid.clientId
Set this equal to the <es-client-id> parameter identified in the “SSO Configuration Parameters” section in PingFederate Configuration.
authentication.openid.clientSecret
Set this equal to the <es-client-secret> parameter identified in the “SSO Configuration Parameters” section in PingFederate Configuration.
authentication.openid.redirectUri
Set this equal to the <es-redirect-uri> parameter identified in the “SSO Configuration Parameters” section in PingFederate Configuration.
authentication.openid.session.maxAge
When a user authenticates with the Experience Service using OpenID Connect, a session is created for that user. This property specifies how much time must elapse before the session is invalidated and the user must re-authenticate. The default unit for this setting is milliseconds. However, other units can be specified by appending the unit name to the value. For example, "10 hours". The following units are supported:
• Seconds: seconds, s
• Minutes: minutes, m
• Hours: hours, hrs, hour, h
• Days: days, day, d
authentication.openid.externalScope
This is required to access the ThingWorx APIs using oauth2. This value should be set to the same value configured in ThingWorx for use of ThingWorx as a Resource Provider.
authentication.openid.esScope
Set this equal to the <es-scope> parameter identified in the “SSO Configuration Parameters” section in PingFederate Configuration.
authentication.openid.studioClientId
Enter the name of the Studio client ID. The default value for this field is PTC_Studio_Client_ID. However, if this has been configured to something different, that must be entered here.
authentication.openid.claimsMapping.username
Set this equal to the value of the sub attribute identified in your OpenID Connect Policy. For more information, see Step 9 in OpenID Policy Configuration.
The following is an example of the JSON that can be used to configure the Experience Service to use OpenID Connect and OAuth2:
"authentication": {
"type": "openidUser",
"baseUrl": "https://twx.example.vuforia.io:8443",
"authorization": {
"appKey": "",
"refreshRate": "300000",
"useAclDbBackend": false
},
"openid": {
"issuer": "https://twx.example.vuforia.io:8443",
"clientId": "es-client",
"clientSecret": "es-client_1234",
"session:" {
"maxAge": "2 minutes",
"secret": "0c8ad6dkhd7976986knd87ea"
},
"externalScope": "THINGWORX"
}
},
Content Stores
The Experience Service stores project and representation content on the file system. Use the following configuration parameters to configure these stores:
* 
If the Experience Service is being deployed in a cluster, ensure that the data store directories (projects.store, reps.store, and upgrade.store) are accessible by all instances running in the cluster.
Parameter
Description
projects.storePath
The path to the directory where project content is stored.
projects.staticOps.maxAge
Specifies value of the max-age header that is included with responses when project content is downloaded to a client.
reps.storePath
The path to the directory where representation repository content is stored.
reps.staticOps.maxAge
Specifies value of the max-age header that is included with responses when reps content is downloaded to a client.
upgrade.storePath
The path to the directory where migrator success files are stored. These files are used to indicate when an upgrade migrator has successfully completed its data migration task so that the migration is not repeated.
* 
The paths specified for these configuration parameters can be absolute or relative paths. Absolute paths begin with “/” and are treated as relative to the root of the file system, while relative paths begin with “./” and are treated as relative to the Experience Service installation directory.
Database
The Experience Service supports the following database software:
• SQLite
• PostgreSQL
* 
SQLite is installed with the Experience Service. PostgreSQL must be obtained and installed separately.
When the Experience Service is first started, it creates all required tables in the database. Use the following configuration parameters to configure the database that will be used by the Experience Service:
Parameter
Description
dbHandler
Set this parameter to one of the following:
• SQLiteHandler if SQLite is being used
• postgresHandler if PostgreSQL is being used
db.datafilePath
This parameter is only applicable if SQLite is being used and specifies the path to the SQLite data file. When the Experience Service is started, it creates the data file if it doesn't exist.
* 
The path specified for this configuration parameter can be absolute or relative. An absolute path begins with “/” and is treated as relative to the root of the file system, while a relative path begins with “./” and is treated as relative to the Experience Service installation directory.
On Windows, an absolute path can either begin with "/" or with a drive letter - for example "C:/". If the absolute path starts with a "/" then the path is treated as relative to the root of the drive that contains the Experience Service installation directory.
db.connectionString
This parameter is only applicable if PostgreSQL is being used and specifies the connection string used to connect to the PostgreSQL database. The format of the connection string is as follows:
postgres://<dbusername>:<dbpassword>@<host>:<port>/<database-name>
The credentials used must have sufficient permissions to create new database tables in the PostgreSQL database.
* 
If you’re using the same PostgreSQL instance that is used by the ThingWorx server then the database name and login/user name used by the Experience Service must be separate from the database name and login/user name used by the ThingWorx server.
Domain Name
In some cases, the Experience Service must know the domain name that is used to access its services. If the Experience Service is registered in the Global Experience Index (GXI), then the Experience Service domain name must be the same as the domain name that is registered in the GXI. This value is typically the fully qualified domain name (FQDN) of the host on which the Experience Service is running. However, if the Experience Service is deployed behind a proxy, then this is the FQDN of the proxy.
The value for the domain name is usually specified during installation. However, you can manually configure the domain name by setting the value of the defaultDomainName configuration parameter equal to the appropriate value.
IRS Federation
By default, the Experience Service is configured to use IRS federation. When using IRS federation, if an Experience Service receives a ThingMark query for a domain other than its own, the Experience Service forwards the request to the Experience Service that is registered with that domain. The Experience Service collects all local Experiences that have been published for that ThingMark and combine them with the results returned by the Experience Service that is registered with that domain.
Parameter
Description
enable_irs_federation
Setting this parameter to true enables IRS federation, while setting it to false disables IRS federation.
domain_id_resolver
The base URL used to query for Experiences from other Experience Services. This is only required if IRS federation is enabled. In general, the base URL for the PTC provided global experience index (GXI) must be used:
https://gxi.vuforia.io/VuforiaExperienceService/id-resolution/resolutions/
For more information, see Identity Resolution Service (IRS) Federation.
Log Files Location
The Experience Service writes log messages to stdout and stderr allowing the administrator to capture the log messages in a way that is appropriate for the deployment environment. If the log messages are captured in a file, then the Experience Service can be configured to allow those log files to be downloaded by a user with the appropriate permissions. For more information on capturing and downloading log messages, see Capture Log Messages.
Use the following configuration parameter to configure the log files location:
Parameter
Description
logsPath
The glob pattern describing the paths that correspond to log files. By default, this is set to /var/logs/thingserver.log*. This enables all files in the /var/logs with names that start with thingserver.log to be downloaded.
* 
The path specified for this configuration parameter begins with “/” and specifies a path that is relative to the root of the file system.
On Windows, an absolute path can either begin with "/" or with a drive letter - for example "C:/". If the absolute path starts with a "/" then the path is treated as relative to the root of the drive that contains the Experience Service installation directory.
Port
You can use the port configuration parameter to configure the port that the Experience Service listens on for connections.
Proxy
Deploying the Experience Service behind a proxy can impact some of the service's functionality. The trustProxy configuration property can be used to ensure that the Experience Service functions properly when it is deployed behind a proxy. Properly configuring this parameter will ensure that the Experience Service:
• Includes the correct IP address for the client that sent a request in its log messages
• Uses the correct protocol in experience URLs that are included in lists of Experiences (for example, when responding to a ThingMark query sent by Vuforia View)
The value of the trustProxy configuration property determines how the Experience Service determines the client IP address and how it determines which protocol should be used for experience URLs.
trustProxy Setting
Client IP
Protocol
false (default)
IP of the client that sent the request
Protocol of the request
true
Left-most entry in the X-Forwarded-For header
Value of the X-Forwarded-Proto header
IP filter criteria
Right-most entry in the X-Forwarded-For header after filtering that list to remove any entries that match the specified filter criteria (see below for more information on how to construct the filter criteria)
Value of the X-Forwarded-Proto header
integer (n)
The nth entry from the right in the X-Forwarded-For header
Value of the X-Forwarded-Proto header
In addition to configuring the Experience Service as described above, the proxy must be configured to send the appropriate information in the following headers:
• X-Forwarded-For
• X-Forwarded-Proto
The following options can be used to construct criteria to be used to filter IP addresses in the X-Forwarded-For header.
Filter Option
Addresses That Will Be Filtered
loopback
Any address that belongs to the following subnet:
• IPv4: 127.0.0.1/8
• IPv6: ::1/128
linklocal
Any address that belongs to the following subnet:
• IPv4: 169.254.0.0/16
• IPv6: fe80::/10
uniquelocal
Any address that belongs to one of the following subnets:
• IPv4: 10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16
• IPv6: fc00::/7
<ip address>
The specified IP address (for example, 203.0.113.13)
These options can be combined into a comma-separated list with the requirement that at least one of the subnet options are included. See the examples below for example filter criteria.
The following are examples of valid settings for the trustProxy configuration parameter.
Use Case
trustProxy Parameter Setting
Ignore the information in the X-Forwarded-* headers.
false
Treat all entries in the X-Forwarded-For header (except the left-most) as known, trusted proxies. The left-most entry is treated as the client IP.
true
Treat only the local host as a known, trusted proxy.
"loopback"
Treat the local host and the IP addresses 203.0.113.13 and 203.0.113.15 as trusted proxies.
"loopback, 203.0.113.13,203.0.113.15"
Treat the local host and any host on the local network as a known, trusted proxy
"loopback, linklocal, uniquelocal"
Realm
The installer automatically configures the realm used by the Experience Service so that it is the same as the realm used by the ThingWorx server. These instructions are included in case you need to configure the realm manually.
The Experience Service can be configured to include a realm in the WWW-Authenticate header that is included in an authentication challenge sent to a client. To configure the value that the Experience Service includes in the WWW-Authenticate header, set the realm parameter to the name of the desired realm.
By default, the authentication realm used by the Experience Service is: *.
The following are the default authentication realms used by ThingWorx:
• For ThingWorx 8.0 or earlier, the default authentication realm is: *
• For ThingWorx 8.1 and later, the default authentication realm is: ThingWorx
* 
Your ThingWorx server may have been configured to use a realm that is different from the default.
To determine the authentication realm used by ThingWorx:
1. Open a terminal and enter the following command on the command line:
curl -is https://<ThingWorx-Core-Host-Port>/ThingWorx/Things | grep -i www-authenticate
Where <ThingWorx-Core-Host-Port> should be replaced with the appropriate hostname and port number for your ThingWorx server. For example:
curl -is https://my-twx.example.com:3124/ThingWorx/Things | grep -i www-authenticate
2. The output looks like the following:
www-authenticate: Basic realm=*
The value that follows realm= is the authentication realm used by your ThingWorx server.
ThingWorx Proxy
The Experience Service requires a ThingWorx server for authenticating users and managing user group membership. In addition, the Experience Service serves as a proxy for the ThingWorx server that is used by both Vuforia Studio and Vuforia View. The installer will configure the Experience Service to proxy the ThingWorx server that you identify during installation. If necessary, you can manually configure the ThingWorx proxy using the following configuration parameters:
Parameter
Description
proxies.0.autoRewrite
If set to true, the Experience Service will change any redirect URIs provided by the ThingWorx server so that the client is redirected back through the proxy. For example, assume the Experience ServiceThingWorx proxy is located at https://es.example.com/Thingworx and the proxied ThingWorx server is located at https://twx.example.com/Thingworx. If the ThingWorx server redirects the client to https://twx.example.com/Thingworx/something, then the Experience Service rewrites this URL as https://es.example.com/Thingworx/something. If this property is set to false, then the Experience Service does not rewrite these redirect URIs.
proxies.0.protocolRewrite
This parameter identifies the protocol used when rewriting redirect URIs. For example, assume that the Experience Service is running in secure HTTPS mode but the ThingWorx server is running in insecure HTTP mode. In this case, this parameter must be set equal to HTTPS so that when the redirect URIs are rewritten they are rewritten to use the protocol used by the Experience Service proxy.
proxies.0.secure
If set to true, the Experience ServiceThingWorx proxy rejects unauthorized (self-signed) certificates used by the proxied ThingWorx server. Therefore, this parameter must be set to false if the proxied ThingWorx server is using self-signed certificates.
websocketProxies.0.autoRewrite
This parameter controls the redirect rewrite behavior for the web socket proxy in the same way the proxies.0.autoRewrite parameter controls the rewrite behavior for the HTTP proxy.
websocketProxies.0.protocolRewrite
This parameter controls the protocol that is used when rewriting redirect URIs for the web socket proxy in the same way the proxies.0.protocolRewrite parameter controls the rewrite behavior for the HTTP proxy. Valid protocol choices are ws or wss.
websocketProxies.0.secure
This parameter controls whether the web socket proxy rejects unauthorized (self-signed) certificates in the same way that the proxies.0.secure parameter controls whether the HTTP proxy rejects unauthorized (self-signed) certificates.
proxies.0.disabled
If set to true, this parameter disables the ThingWorx proxy. If set to false, it enables the proxy.
proxies.0.target
The base URL for the ThingWorx server. This URL must end in /Thingworx. For example, https://twx.acme.com:8443/Thingworx.
proxies.0.appKey
The ThingWorx application key used by the Experience Service to grant public Experiences access to ThingWorx data. For more information about public Experiences and configuring public access to ThingWorx, see Configuring Public Access to ThingWorx.
websocketProxies.0.disabled
If set to true, this parameter disables the ThingWorx web socket proxy. If set to false, it enables the proxy.
websocketProxies.0.target
The base URL used to establish a web socket between the client and the ThingWorx server. This URL must be compatible with the value specified for proxies.0.target. For example, if proxies.0.target is set to https://twx.acme.com:8443/Thingworx, then this parameter must be set to wss://twx.acme.com:8443.
* 
Do not connect Edge devices and mashups to the ThingWorx server using the Experience ServiceThingWorx proxy. Instead, a direct connection to the ThingWorx server should be used (using alternative ports, ELB, and so on). The Experience ServiceThingWorx proxy is not designed to handle the load associated with EDGE device traffic and certain Edge SDKs do not work through a proxy.
TLS Certificates
* 
If the Experience Service is being deployed in a cluster, ensure that the key and certificate file locations are accessible by all instances running in the cluster.
By default, the Experience Service uses the HTTPS protocol to encrypt communication between the service and clients.
For more information, see Transport Layer Security (TLS) Certificates.
The certificates used for encryption can be configured using the following configuration parameters:
* 
Values can be specified for the PEM properties (httpsKeyPath, httpsCrtPath and httpsCaPath) or the PCKS12 (PFX) property (httpsPfxPath), but not both.
Parameter
Description
httpsKeyPath
The path to the file that contains the PEM encoded private key.
httpsCrtPath
The path to the file that contains the PEM encoded public certificate.
httpsCaPath
The path to the certificate bundle file that contains the PEM encoded public certificates for the intermediate certificate authorities.
httpsCertPassphrase
The passphrase used to decrypt the PEM encoded private key or the PCKS12 (PFX) encoded archive file.
httpsPfxPath
The path to the file that contains the PCKS12 (PFX) encoded archive file.
* 
The paths specified for these configuration parameters can be absolute or relative paths. Absolute paths begin with “/” and are treated as relative to the root of the file system, while relative paths begin with “./” and are treated as relative to the Experience Service installation directory.
On Windows, an absolute path can either begin with "/" or with a drive letter - for example "C:/". If the absolute path starts with a "/" then the path is treated as relative to the root of the drive that contains the Experience Service installation directory.
Optional Parameters
The following optional configuration parameters can be manually added to the configuration.json file.
Parameter
Description
nohttp2
Add this parameter and set it to true in order to save images taken with the Camera widget during an experience to a repository in ThingWorx.
For example:
{
…..
"nossl":true,
"nohttp2":true
}
Advanced Model Target Parameters
The following optional configuration parameters can be manually added to the configuration.json file.
Parameter
Description
hmtg.credentials.baseUrl
URL for the Model Target service. This parameter is populated for you. The value is:
https://vws.vuforia.com
hmtg.credentials.tokenPath
HTTP request path for OAuth2 authentication. This parameter is populated for you. The value is:
oauth2/token
hmtg.credentials.amtgPath
HTTP request path for Advanced Model Target generation. This parameter is populated for you. The value is:
modeltargets/advancedDatasets
hmtg.credentials.accessKey
The value for this parameter must be obtained from PTC Technical Support. For more information, see Request Information to Enable Advanced Model Target Generation.
hmtg.credentials.secretKey
The value for this parameter must be obtained from PTC Technical Support. For more information, see Request Information to Enable Advanced Model Target Generation.
Publishing Parameters
The following optional configuration parameters can be manually added to the configuration.json file.
Parameter
Description
publicAccess
Disable or enable the ability to publish projects that have the Access field set to Public in Vuforia Studio.
For example:
{
…..
"publicAccess":{
"disabled": true
}