Configure OAuth Delegated Authorization
Windchill can participate in a single sign-on (SSO) as a resource server to applications and mashups built on the ThingWorx platform. In this use case, a user can sign in to an SSO-enabled ThingWorx-based application and authorize the application they are interfacing with to access their Windchill data. This implementation of SSO is known as delegated authorization because the user authorizes the service provider (application) to act on their behalf to retrieve their information from the resource server (Windchill), and the user needs to log in once. For a full description of supported SSO use cases and the configuration steps required for setting up a PTC product SSO federation, refer to the PTC Product Platform Single Sign-on Guide.
The PTC product platform SSO solution relies on the exchange of access tokens based on the OAuth standard to manage delegated authorization between product applications. Two Windchill files, securityContext.properties file and Web.xml, must be edited to enable OAuth in Windchill.
Configurations Common to any OAuth Delegated Authorization
• Update the property wt.oauth2.token.userNameAttribute value to the user attribute name that is specified in the IDP configuration. For example, if pingfederate is the IDP, then the value is Username.
• Update the property wt.oauth2.token.tokenType to switch the token validation between OPAQUE and JWT. ThedDefault value is OPAQUE.
• Update the property wt.oauth2.token.scopeAttribute to configure the scope attribute for both OPAQUE and JWT token. The default value is scope.
OAuth Delegated Authorization Configuration for an OPAQUE Token
To configure a connection to the central authorization server and specify what system resources are protected by access tokens and scopes, edit the securityContext.properties file as described below. The path to the property file is <Windchill>\codebase\WEB-INF\security\config\securityContext.properties.
1. Identify what resources should be protected by OAuth 2 tokens. Protected resources will require a valid OAuth 2 token from a service provider for access to be granted to it. To do this, list the resources in an ant-style pattern after the following string: com.ptc.eauth.identity.oauth2.rs=/oauth/**
For example, to protect Windchill documents, the string would be configured like this:
com.ptc.eauth.identity.oauth2.rs=/oauth/documents/**
Only a single pattern, that is, only one line can be specified in the properties file. Therefore, you need to define a top-level URL that sufficiently encompasses all of the resources that you want protected by OAuth 2 tokens. In step 4 you will specify the scopes that should be attached to the OAuth tokens, which provides additional granularity for controlling access to the resource.
2. Identify the endpoint for the token validation. This value should be set to the CAS server that will be validating access tokens.
org.springframework.security.oauth2.provider.token.RemoteTokenServices.checkTokenEndpointUrl=https://{cas-server}
.ptc.com:9031/as/introspect.oauth2
.ptc.com:9031/as/introspect.oauth2
3. Provide the client ID and client secret specified in the PingFederate (CAS) OAuth client that was created for a resource server. Contact your CAS administrator for information about the OAuth client for Windchill.
org.springframework.security.oauth2.provider.token.RemoteTokenServices.clientId=rs_client
org.springframework.security.oauth2.provider.token.RemoteTokenServices.clientSecret={client secret}
4. Add at least one property that pairs the WINDCHILL_READ scope with the Windchill resources that you want made available to a service provider.
To configure the resources that are exposed by the WINDCHILL_READ scope, you must add properties defining this access to the securityContext.properties file. In Windchill, configuring a single scope is supported. Testing was conducted with a scope named WINDCHILL_READ. Scopes that are registered in this file must also be registered in the central authorization server that manages the exchange of access tokens in your SSO network, and in the service provider application that will be requesting the data.
Each scope property is composed of the following parts
◦ A URL prefix that indicates the resource protected by OAuth and allows access if a valid access token is presented. For example:
com.ptc.eauth.identity.oauth2.rs.InMemoryResourceScopeService.resourceScopes.
◦ A directory path to the resources that will be exposed. For example, /Windchill/oauth/documents.
◦ An Ant-style path pattern. For example, /** exposes resources from all directories under the path provided before the task.
◦ The scope value (name). For example, =WINDCHILL_READ. Scope values cannot contain spaces. Spaces are used to separate multiple scope values; however, multiple scope scenarios are not currently supported.
The following is a sample scope property to require an OAuth access token to have the WINDCHILL_READ scope to permit passing data for /Windchill/oauth/documents resources
com.ptc.eauth.identity.oauth2.rs.InMemoryResourceScopeService.resourceScopes.
/Windchill/oauth/documents=WINDCHILL_READ
/Windchill/oauth/documents=WINDCHILL_READ
Incoming requests must have an access token that has the required scopes that are defined in properties for a given resource. These properties are additive, meaning if you define additional scopes for the same resource, then incoming requests for the protected data must contain all of the scopes that have been defined for that resource. For example, if you create a second property in addition to the example above that requires the scope “ABC” for /Windchill/oauth/documents resources, then an incoming access token would need to have the scopes “WINDCHILL_READ” and “ABC” to gain access to the resource.
OAuth Authorization Configuration for the JWT Token
For configuring an OAuth authorization for Microsoft Entra ID using the JWT token, follow these steps:
1. Add the following properties in wt.properties file through site.xconf:
|
wt.jwt.oauth2.token.keytype
|
The value can be symmetric or asymmetric. The default value is asymmetric.
|
|
wt.jwt.oauth2.token.certificateLocation
|
The location of the certificate that is used to sign the JWT token. This property is required when wt.jwt.oauth2.token.kidUrl property is not specified and wt.jwt.oauth2.token.keytype=asymmetric.
|
|
wt.jwt.id.token.extraClaimsToBeValidated
|
The value can be one or multiple values from these: iss, aud, exp, sub, typ. This takes the list of default mandatory claims as the value. This property is used to validate the extra claims from JWT token such asiat, nbf.
For PingFederate JWT, this property is not required.
|
|
wt.jwt.oauth2.token.issueAtTime
|
The time at which the JWT access token was issued. This can be used to determine the age of the JWT access token. The default value is 900000 millisecond/15min.
|
|
wt.jwt.oauth2.token.azure.tenantId
|
The Tenant ID that is a globally unique identifier (GUID) and is other than your organization name or domain.
|
|
wt.jwt.oauth2.token.audience
|
The client ID.
|
|
wt.jwt.oauth2.token.tokenIssuer
|
The value is https://sts.windows.net/<tenant_id>/.
|
|
wt.jwt.oauth2.token.algorithm
|
Supported algorithms:
• For symmetric keys: HS256, HS384, HS512. The default value is HS256.
• For asymmetric (certificate) keys: RS256, RS384, RS512. The default value is RS256.
|
|
wt.jwt.oauth2.token.kidUrl
|
The value is https://login.microsoftonline.com/<tenant_id>/discovery/v2.0/keys.
For PingFederate, set the value is https://<Ping Federate host>:9031/ext/oauth/jwks.
|
2. The default value of the property wt.jwt.oauth2.token.jwtIdpType is DEFAULT_JWT_IDP. Update the value of this property to the supported third-party identifier in securityContext.properties file. This validates only the standard JWT claims. For AzureAD as IDP, set the property to wt.jwt.oauth2.token.jwtIdpType = azure .
3. Add the symmetric key configuration in Windchill. For details, refer to addValueToKeyStore Target. Add the symmetric key in WTKeystore using the EncryptPasswords.xml utility provided by Windchill, as mentioned in the example below:
ant -f EncryptPasswords.xml addValueToKeyStore
-DpropertyName=<property> -Dpassword=<password_value>
-Dwt.home=<Windchill_location>
-DpropertyName=<property> -Dpassword=<password_value>
-Dwt.home=<Windchill_location>
ant -f EncryptPasswords.xml addValueToKeyStore -DpropertyName=wvs -Dpassword=hwmLrHtgOBSS0qiEeiGVtsRS1hy7IA7ovSWdlu9YVPk=
-Dwt.home="/opt/ptc/Windchill"
◦ propertyName—The kid claim value for PingFederate. For other IDPs, this value changes.
◦ password—The value of the symmetric key used for the JWT token signing. This value should be non-encrypted.
Editing the Web.xml file
Perform two edits to the Web.xml file:
1. Add the location of the securityContext.properties file to the WEB-INF/web.xml file.
The WEB-INF/web.xml file must reference the securityContext.properties file. The Web.xml file is located at <Windchill install location>/Codebase/WEB-INF/Web.xml.
Add the location to the parameter value for the location of the Spring root web application context. The following example is valid if you have kept the securityContext.properties file saved in its default directory. Add the path WEB-INF/security/config/securityContext.xml to <param-value>config/mvc/applicationContext.xml</param-value>. The structure of the context parameter should be the following:
<context-param>
<description>Location of Spring root web application context</description>
<param-name>contextConfigLocation</param-name>
<param-value>config/mvc/applicationContext.xml
WEB-INF/security/config/securityContext.xml
</param-value>
</context-param>
<description>Location of Spring root web application context</description>
<param-name>contextConfigLocation</param-name>
<param-value>config/mvc/applicationContext.xml
WEB-INF/security/config/securityContext.xml
</param-value>
</context-param>
 |
The location of the securityContext.properties file is also referenced in securityContext.xml. If you changed the directory location of securityContext.properties, then you must update the references to the new location in Web.xml and securityContext.xml.
|
2. Add a SpringSecurityFilterChain code snippet.
Locate the first <filter-mapping> tag within the Web.xml file and add the following code before that tag:
<filter>
<filter-name>springSecurityFilterChain</filter-name>
<filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
</filter>
<filter-mapping>
<filter-name>springSecurityFilterChain</filter-name>
<url-pattern>/oauth/*</url-pattern>
</filter-mapping>
<filter-name>springSecurityFilterChain</filter-name>
<filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
</filter>
<filter-mapping>
<filter-name>springSecurityFilterChain</filter-name>
<url-pattern>/oauth/*</url-pattern>
</filter-mapping>
Locate the first <servlet-mapping> tag within the Web.xml file, and add the following code before that tag:
<servlet>
<description>Bridge Servlet for Oauth Access</description>
<servlet-name>OauthAuthBridgeServlet</servlet-name>
<servlet-class>wt.servlet.AuthBridgeServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>OauthAuthBridgeServlet</servlet-name>
<url-pattern>/oauth/*</url-pattern>
</servlet-mapping>
<description>Bridge Servlet for Oauth Access</description>
<servlet-name>OauthAuthBridgeServlet</servlet-name>
<servlet-class>wt.servlet.AuthBridgeServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>OauthAuthBridgeServlet</servlet-name>
<url-pattern>/oauth/*</url-pattern>
</servlet-mapping>
Restart Windchill and Apache Server
After editing the securityContext.properties and Web.xml files, restart the Windchill and Apache servers and test to verify that Windchill participates in delegating the authorization with your SSO network.