Configure ThingWorx as a Resource Server
You can configure ThingWorx as a Resource Server to allow ThingWorx URI requests via OAuth2 protocol.
Service providers may use the response from the Resource Server to render and show data stored in ThingWorx.
ThingWorx as a Resource Server is responsible for validating the access token and scopes on each resource request.
The following sections describe the configuration steps required to enable ThingWorx as a Resource Server in ThingWorx. You may need to consult with other PTC product administrators and identity provider administrators in your organization to configure other applications that are configured for this purpose.
Process Overview
Follow this process to configure ThingWorx as a Resource Provider:
1. Configure Single Sign-On. This is a prerequisite to this process.
 |
It is highly recommended that the Service Provider to Resource Server communication channel is SSL.
|
For some of the settings used in these configuration steps, you need to obtain values from your PingFederate installation.
Configure the resourceServerSettings.json File
1. Create the resourceServerSettings.json file in the same directory as sso-settings.json.
The following is a sample structure of the resourceServerSettings.json file:
{
"ResourceServerSettings": {
"accessTokenServicesSettings": {
"userAuthenticationConverterClassName": "com.ptc.eauth.identity.oauth2.rs.IntrospectionUserAuthenticationConverter",
"userAuthenticationConverterUserNameAttribute": "See information in the table below",
"oauthTokenEndPoint": "https://<pingfed.server>:9031/as/token.oauth2",
"checkTokenEndpointUrl": "https://<pingfed.server>:9031/as/introspect.oauth2",
"clientId": "See information in the table below",
"clientSecret": "See information in the table below",
"chainedGrantType": "password"
},
"globalScopes": "THINGWORX",
"uriScopes": [
{
"uri": "See information in the table below",
"scopes": "See information in the table below",
"method": "See information in the table below"
}
]
}
"ResourceServerSettings": {
"accessTokenServicesSettings": {
"userAuthenticationConverterClassName": "com.ptc.eauth.identity.oauth2.rs.IntrospectionUserAuthenticationConverter",
"userAuthenticationConverterUserNameAttribute": "See information in the table below",
"oauthTokenEndPoint": "https://<pingfed.server>:9031/as/token.oauth2",
"checkTokenEndpointUrl": "https://<pingfed.server>:9031/as/introspect.oauth2",
"clientId": "See information in the table below",
"clientSecret": "See information in the table below",
"chainedGrantType": "password"
},
"globalScopes": "THINGWORX",
"uriScopes": [
{
"uri": "See information in the table below",
"scopes": "See information in the table below",
"method": "See information in the table below"
}
]
}
2. Ensure that you edit the value of every parameter as per your requirement. Your implementation may vary depends on several factors, such as the security policies of your organization and the CAS for your federation. Use the information in the following tables as guidance to set values for different parameters.
|
Parameter
|
Description
|
Value
|
|---|---|---|
|
userAuthenticationConverterClassName
|
Internal utility.
|
com.ptc.eauth.identity.oauth2.rs.IntrospectionUserAuthenticationConverter
|
|
userAuthenticationConverterUserNameAttribute
|
Optional. Defines field name that contains user ID. If the property is not set, the default value is username.
|
|
|
oauthTokenEndPoint
|
Specifies the PingFederate’s OAuth Token Endpoint (see image below).
|
https://<pingfed.server>:<pingfed.port>/as/token.oauth2
|
|
checkTokenEndpointUrl
|
Specifies the PingFederate’s OAuth Token Introspection Endpoint (see image below).
|
https://<pingfed.server>:<pingfed.port>/as/introspect.oauth2
|
|
clientId
|
Specifies the client identifier to use for validation access tokens from the Auth server.
|
|
|
clientSecret
|
Client secret value.
|
|
|
chainedGrantType
|
Reserved for future use.
|
password
|
Parameter | Description | Examples |
|---|---|---|
globalScopes | List of comma-separated global scopes. Includes the minimum set of scopes required to access any resource. If this parameter is missing or empty, THINGWORX is set as a default global scope. Do not to leave this parameter empty. If there is no dedicated scope, then set THINGWORX as a value. | "globalScopes": "THINGWORX" "globalScopes": "THINGWORX_APP1,THINGWORX_APP2" |
Parameter | Description | Example | ||
|---|---|---|---|---|
uri | URI pattern. Defines the resource or resource group that requires additional scope(s) to the global scope(s). | /Things/** - control all Things /Things/Thing1 – control Thing1 | ||
scopes | Comma-delimited list of additional scopes. Only the user that has grants to all listed scopes (including global) is allowed to get resource. | |||
method | Optional. Defines the URI method that the scope will be applied to.
| Possible values are any methods allowed in REST protocol, such as GET or POST. |
If there are scopes defined for an URI, then the global scopes plus the defined URI scopes must be granted to access that resource. If there is more than one URI rule applicable for the requested resource, then all relevant scopes must be granted to access that resource. To avoid access to restricted resources, add URIscope to these REST end points with a scope that does not exist in the Authorization server (e.g PingFed). In addition to scope protection, ThingWorx has its own user-based permissions that will also be applied on top of the scopes. For example, in a case where User A requests a resource with the correct scopes but does not have permission, the request fails with a 403 error.
Examples
The example below is a relevant pattern from the resourceServerSettings.json configuration:
"globalScopes": "THINGWORX",
"uriScopes": [
{
"uri": "/Things/**",
"scopes": "THINGWORX_THING_READ"
},
{
"uri": "/Things/WriteThing",
"scopes": "THINGWORX_THING_WRITE"
"method": "POST"
}
]
| | In each use case in the table below, if the required grants are not given by the user, ThingWorx will not provide the resource. |
URI Request | Required Grants | Notes |
|---|---|---|
GET /Thingworx/Mashups/Mashup1 | THINGWORX | The URI request does not match any uriScopes rule. THINGWORX globalScope rule is applied. |
GET /Thingworx/Things/WriteThing | THINGWORX, THINGWORX_THING_READ | THINGWORX globalScope plus first uriScope rule are applied. |
POST /Thingworx/Things/WriteThing | THINGWORX, THINGWORX_THING_READ, THINGWORX_THING_WRITE | THINGWORX globalScope plus first rule plus second uriScope rule are applied. |
Create PingFederate Connections: OAuth Client for ThingWorx as Resource Provider
The OAuth client is a connection point for PingFederate to provide access tokens to ThingWorx. Service Providers use these access tokens to request OAuth-protected resources from ThingWorx.
1. In PingFederate, search for Clients. Open the search result > and click Add Client.
2. In the CLIENT ID field, enter a value. Use the same value you used for the ResourceServerSettings.accessTokenServicesSettings.clientId parameter when you configured the resourceServerSettings.json file.
3. In the NAME field, enter a value. This is displayed in the PingFederate clients list.
4. In the DESCRIPTION field, enter a description.
5. In the CLIENT AUTHENTICATION section, select CLIENT SECRET and enter a client secret value. Use the same value you used for the ResourceServerSettings.accessTokenServicesSettings.clientSecret parameter when you configured the resourceServerSettings.json file.
6. Keep the REDIRECT URIS section empty.
7. In the ALLOWED GRANT TYPES section, select Resource Owner Password Credentials and Access Token Validation (Client is a Resource Server).
8. In the DEFAULT ACCESS TOKEN MANAGER section, select Default.
9. In the PERSISTENT GRANTS MAX LIFETIME section, select Use Global Setting.
10. In the REFRESH TOKEN ROLLING POLICY section, select Roll.
11. Click Save.
Scope Management in PingFederate
1. In PingFederate, append all scopes mentioned in the resourceServerSettings.json file to the Scope Management page in the OAuth Settings section, including globalScopes. Repeat the following steps for every scope:
1. Add a scope in the Scope Value field.
2. Add a scope description in the Scope Description field.
3. Click Add.
4. Click Save.
Every time a set of scopes is modified in the resourceServerSettings.json, you must update this list accordingly. It is also recommended to update this list before reloading the resourceServerSettings.json in ThingWorx.
| | If a scope was not defined in the resourceServerSettings.json file under ResourceServerSettings.globalScopes, then the THINGWORX scope must be added here (in PingFederate) as THINGWORX in the default global scope. |
Updating ThingWorx with the Modified resourceServerSettings.json File
After updating the resourceServerSettings.json file, you must restart Tomcat.
If you are modifying only scopes (both globalScopes and uriScopes section), you do not need to restart Tomcat. Instead, perform the following steps:
1. Log in to Composer as Administrator.
2. Go to Authenticators and open ThingworxSSOAuthenticator.
3. Open Services.
4. Execute the ReloadResourceProviderScopes service.