Configure OAuth Delegated Authorization
Windchill is able to participate in single sign-on (SSO) as a resource provider 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 provider (
Windchill) and the user only 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 the exchange of access tokens based on the OAuth standard in order to manage delegated authorization between product applications. Two Windchill files must be edited to enable OAuth in Windchill.
Edit securityContext.properties File
The securityContext.properties file is where you configure a connection to the central authorization server and specify what system resources are protected by access tokens and scopes. This property file is found at the following directory path: <Windchill>\codebase\WEB-INF\security\config\securityContext.properties.
When configuring this file, the following steps are required.
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), so 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 what scopes should be attached to the OAuth tokens, which provides additional granularity for controlling access to the resource.
2. Identify the endpoint for 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/token.oauth2?grant_type=urn:pingidentity.com:oauth2:grant_type:validate_bearer
3. Provide the client ID and client secret that were specified in the PingFederate (CAS) OAuth client that was created for a resource provider. 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 also need to 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 is protected by OAuth and allows access if a valid access token is presented.
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 note that 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 in order to permit passing data for /Windchill/oauth/documents resources
com.ptc.eauth.identity.oauth2.rs.InMemoryResourceScopeService.resourceScopes.
/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.
Edit Web.xml File
Two edits need to made 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 needs to 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 as long as 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:
|
|
The location of the securityContext.properties file is also referenced in securityContext.xml. If you change the directory location of securityContext.properties, then update the references to it 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>
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>
Restart Windchill and Apache Server
After editing the securityContext.properties and Web.xml files, restart Windchill and Apache server and conduct testing to verify that Windchill participates in delegated authorization with your SSO network.
