Versions Compared

Old Version 2

changes.mady.by.user Lonnie VanZandt

Saved on

compared with

New Version Current

changes.mady.by.user Brian Miller

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Suggestion from Dev: (Fix Formatting so) file block reference (can be) moved up + Use Fixed Width formatting where appropriate + Sanitize example conf (we don't want users to have our keys & connect to our PF server!)

This process has two phases:

  1. Configuring Ping Federate at the Identity Provider (IdP) for Windchill

  2. Configuring the Syndeia Windchill Microservice for OAuth2 Device Code Grant

Table of Contents
minLevel1
maxLevel6
outlinefalse
typelist
printablefalse

Introduction

...

Introduction

PTC recommends that client applications communicate with PTC Windchill via its REST API, the Windchill REST Services (WRS). WRS supports both Basic Authentication with Windchill username and password and OAuth2 using a variety of Grant flows. This is especially true if Windchill is configured for SSO with SAML2 using Ping Federate IdP. Refer to the following link for using WRS with OAuthhttps://support.ptc.com/help/windchill_rest_services/r2.2/en/index.html#page/windchill_rest_services/oauth_for_wrs.html.

This document is a high-level overview for configuring PTC Windchill for delegated OAuth with Ping Federate such that applications can use WRS .

Part 1 - Install and Configure Ping Federate as the IdP for Windchill

...

docker compose up a PingFederate instance - which is available at Docker Hub

...

set the Server Base URL in PingFederate to be the intended corporate-internal FQDN for the PingFederate service

...

Create an IdP Adapter in PingFederate

...

Create an LDAP Data Source in PingFederate

Create an OAuth Client App in PingFederate, named “rs_client”

...

Configure the OAuth Token Manager for the rs_client OAuth Client App

...

Configure an OAuth Setting Scope Management Scope of “WINDCHILL” in PingFederate

...

Configure Access Token Mappings

...

Configure IdP Adapter Grant Mapping

...

Before doing anything more, use Postman (or equivalent REST client or cURL) to verify that it can request and receive OAuth tokens after doing user MFA Authorization-Code Grant flow with the new (or existing) PingFederate OAuth client.

Part 2 - Configuring Windchill and Ping Federate for Windchill OAuth

See the Explanation of PTC’s Windchill Authentication Architecture, below.

  1. See Configure OAuth Delegated Authorization in Tomcat Windchill

    1. Be advised that PTC formally states that all authentication choices are “customer optional” and are not formally supported.

      1. This is complex and beyond the scope of Syndeia - however if your team is at a loss of adequate SMEs, our team has done this several times and we can advise your available staff - we do not recommend leaving this complex task to generalists.

  2. The two files that you will edit on your Windchill server are

    1. <Windchill>\codebase\WEB-INF\security\config\securityContext.properties

    2. <Windchill>\codebase\WEB-INF\web.xml

Expand

titleAn Explanation of PTC's Windchill Authentication Architecture

“Windchill” is beyond a simple PLM, it is a technology stack consisting of Identity Management, Token Management, Single-sign on Session Management, Database Management, Organization Management, and, behind all that, Product Management.

Windchill delegates Oauth2 authentication for a subset of its API routes to Apache HTTPd, Tomcat Servlet Engine, Ping Federate, LDAP, and a Tomcat Spring Bean.

It is the Tomcat Spring Bean which is responsible for receiving an incoming HTTP Request from Apache HTTPd via AJP and Tomcat - it is not a substitute for PTC literature.

Table of Contents
minLevel2
maxLevel6
outlinefalse
styledefault
typelist
printablefalse

The instructions that follow assume that the IdP is Ping Federate. This assumption is made because Ping Federate is the only IdP for which PTC provides installation guidance.

...

Part 1 - Install and Configure Ping Federate as the IdP for Windchill

  1. docker compose up a PingFederate instance - which is available at Docker Hub

  2. set the Server Base URL in PingFederate to be the intended corporate-internal FQDN for the PingFederate service

  3. Create an IdP Adapter in PingFederate

  4. Create an LDAP Data Source in PingFederate

  5. Create an OAuth Client App in PingFederate, named rs_client

    1. See Solution Guide: Adding a new OAuth2 Client

  6. Configure the OAuth Token Manager for the rs_client OAuth Client App

    1. See Creating PingFederate OAuth Clients for PTC Products

  7. Configure an OAuth Setting Scope Management Scope of WINDCHILL in PingFederate

  8. Configure Access Token Mappings

  9. Configure IdP Adapter Grant Mapping

  10. Before doing anything more, use Postman (or equivalent REST client or cURL) to verify that it can request and receive OAuth tokens after doing user MFA Authorization-Code Grant flow with the new (or existing) PingFederate OAuth client.

Part 2 - Configure Windchill and Ping Federate for Windchill OAuth

See the Explanation of PTC’s Windchill Authentication Architecture, below.

  1. See Configure OAuth Delegated Authorization in Tomcat Windchill

    1. Be advised that PTC formally states that all authentication choices are “customer optional” and are not formally supported.

      • This is complex and beyond the scope of Syndeia - however if your team is at a loss of adequate SMEs, our team has done this several times and we can advise your available staff - we do not recommend leaving this complex task to generalists.

  2. The two files that you will edit on your Windchill server are

    1. <Windchill>\codebase\WEB-INF\security\config\securityContext.properties

    2. <Windchill>\codebase\WEB-INF\web.xml

Expand
titleAn Explanation of PTC's Windchill Authentication Architecture

“Windchill” is beyond a simple PLM, it is a technology stack consisting of Identity Management, Token Management, Single-sign on Session Management, Database Management, Organization Management, and, behind all that, Product Management.

Windchill delegates Oauth2 authentication for a subset of its API routes to Apache HTTPd, Tomcat Servlet Engine, Ping Federate, LDAP, and a Tomcat Spring Bean.

It is the Tomcat Spring Bean which is responsible for receiving an incoming HTTP Request from Apache HTTPd via AJP and Tomcat that has an HTTP Authorization Bearer token and for then performing the token introspection with the Ping Federate service to determine if the token is valid and to extract the effective Windchill user identity from the token before forwarding that HTTP Request on into the Windchill application.

PTC delivers their technology stack as a complex and complicated collection of template deployments, property files, XML configuration files, and Ant scripts.

During installation of the Windchill stack, the installing administrator executes several ant scripts to weave configuration properties into the template files to yield the eventual effective configuration files which inform the running HTTPd and Tomcat services.

A Tomcat servlet ecosystem consists of a web server (like Apache HTTPd) and one or more Tomcat “engines” (or instances) each of which may have multiple “hosts” where each “host” runs multiple “contexts”. Each “context” can be configured to offer service from multiple servlet contexts.

(Modern microservices developers can think of a “servlet context” as a “microservice” - except for the difference that modern microservices are supposed to be more pure in limiting their scope than was the practice for servlets.)

The Windchill PDMLink application is a Tomcat servlet context that is found in <WINDCHILL<WINDCHILL_DRIVE>DRIVE>/Windchill/codebase/WEB-INF .

The servlet filter in this servlet context that is responsible to receive an Oauth2-token-bearing HTTP Request, to extract the token, to verify the token with the Token Server (PingFederate), to extract the effective Windchill user id, and to forward the request into Windchill is found in the security folder of this WEB-INF directory. There is a securityContext.xml file and a securityContext.properties file.

Because PTC does not assume that all its customers will offer OAuth2 access for their Windchill APIs, the servlet’s Context’s configuration file, web.xml, does not include the necessary filter, filter-mapping, servlet, and servlet-mapping elements.

Installation involves adding the necessary property strings to the securityContext.properties file and then adding the missing XML fragments to the web.xml file in the right locations to assure that incoming HTTP requests flow through the right filter chains and are routed to the right servlets by the right servlet-mapping elements.

PTC documentation states how to configure the Windchill servlet context for OAuth2 authentication. (The advice above merely explains which Tomcat configuration to modify and is intended to explain why the modifications are made).

Part 3 -

...

Configure Windchill OAuth Client in Ping Federate for Device Code Auth Grant Flow

Assuming that Windchill already has Ping Federate as its IdP:

...

Note: The “Device Code" OAuth grant type is based on specific users and not on just a known single specific application-client to enforce the user-specific permissions and access controls as they connect to Windchill from the same specific application-client (“Syndeia”).

...

Intercax selected a Device Code Grant Flow has been chosen both for its industry support, for high user “user ability”, and for cybersecurity controls - it is the only Grant Flow which supports offers authentication for both users using web browsers and for scripts making API calls while assuring that all such service requests are traced directly to the specific user making those requests and not to a single “application” identity or to a some “digital service account”.

We can advise your cybersecurity staff in understanding the necessities here.

Part 4 -

...

Configure Syndeia Cloud Windchill Service

Step 1: Configure the Syndeia Cloud windchill-impl application

  1. Log into the Syndeia Service

  2. Code Block
    ssh MySyndeiaServer.company.com

  3. Alter its Windchill conf/application.conf according to the example file in the expansion region below

    this list

    1. Code Block
      cd /opt/icx/syndeia-cloud-current/windchill-impl-*/conf && sudo vi application.conf

       

  4. Restart the Syndeia Windchill microservice

    1. sudo systemctl restart sc-windchill

    2. Note that it is web-gateway that offers the frontend code, you must also redeploy that service but the prep-step (0) above accomplishes that

    3. Contact Intercax.com/help if your team needs assistance in editing configuration files for specific microservices

...

titleApplication.conf Properties for a Windchill OAuth2 IdP

...

    1. (see file below, edit, then exit vi with :wq)

Expand
titleApplication.conf Properties for a Windchill OAuth2 IdP
Code Block
# This section is used to provide OAuth configurations for Windchill repositories integrated with this Syndeia deployment
# It is possible to add OAuth configuration for more than one Windchill repository,
# for example, the section below contains OAuth configuration for two Windchill repositories - "http://wc11.example.com/Windchill" and "http://wc12.example.com/Windchill"
# The repository url of the Windchill repository, enclosed in double quotes (""), acts as the key of the OAuth configuration for that Windchill repository
# for example, "http://wc11.example.com/Windchill" is the key of one of the two OAuth configurations provided in the below section
external.auth.oauth {
  # windchill repository url
  "http://wc11.example.com/Windchill" {
    # device code endpoint configured in IdP
    deviceCodeEndpoint = "https://my.idp.example.com:9031/as/device_authz.oauth2"

    # token endpoint configured in IdP
    tokenEndpoint = "https://my.idp.example.com:9031/as/token.oauth2"

    # an identifier for Syndeia configured in IdP
    client_id = "example_client_id"

    # client secret for Syndeia configured in IdP
    client_secret = "example_client_secret"

    # scope of the access to Windchill server to be requested by Syndeia
    scope = "EXAMPLE_SCOPE"
  }
  "http://wc12.example.com/Windchill" {
    # device code endpoint configured in IdP
    # deviceCodeEndpoint = "https://my.another.idp.example.com:9031/as/device_authz.oauth2"
    deviceCodeEndpoint = "https://pingMyPing-federate.intercaxdomain.comtld:9031/as/device_authz.oauth2"

    # token endpoint configured in IdP
    # tokenEndpoint = "https://my.another.idp.example.com:9031/as/token.oauth2"
    tokenEndpoint = "https://pingMyPing-federate.intercaxdomain.comtld:9031/as/token.oauth2"

    # an identifier for Syndeia configured in IdP
    # client_id = "example_client_id"
    client_id = "rs_client"

    # client secret for Syndeia configured in IdP
    # client_secret = "example_client_secret"
    client_secret = "SJfj4TrHgG7pGPkpODzavnf6TiuPp6DGSTQTotGR8kyZV06QgOoCmjr99TvrTFkTSJfj4TrHgG7pGPkpODwirqf6TiuPp6DGSTQTotGR8kyZV06QgOoCmjr99TvrTFkT"

    # scope of the access to Windchill server to be requested by Syndeia
    # scope = "EXAMPLE_SCOPE"
    scope = "WINDCHILL"
  }
  # add oAuth configuration for more windchill repositories here ...
}

(0) Receive the deliverables, deploy the deliverables to containerization platforms, assess routine operation - before attempting to exercise new capabilities.

...

(If necessary) Install and Configure an instance of PingFederate as the IdP for Windchill

  1. docker compose up a PingFederate instance - which is available at Docker Hub

  2. set the Server Base URL in PingFederate to be the intended corporate-internal FQDN for the PingFederate service

  3. Create an IdP Adapter in PingFederate

  4. Create an LDAP Data Source in PingFederate

  5. Create an OAuth Client App in PingFederate, named “rs_client”

    1. See Solution Guide: Adding a new OAuth2 Client

  6. Configure the OAuth Token Manager for the rs_client OAuth Client App

    1. See Creating PingFederate OAuth Clients for PTC Products

  7. Configure an OAuth Setting Scope Management Scope of “WINDCHILL” in PingFederate

  8. Configure Access Token Mappings

  9. Configure IdP Adapter Grant Mapping

  10. Before doing anything more, use Postman to verify that it can request and receive OAuth tokens after doing user MFA Authorization-Code Grant flow with the new (or existing) PingFederate OAuth client.

...

(If necessary) Configuring Windchill and Ping Federate for Windchill OAuth

  1. See the Explanation of PTC’s Windchill Authentication Architecture, below

  2. See Configure OAuth Delegated Authorization in Tomcat Windchill

    1. Be advised that PTC formally states that all authentication choices are “customer optional” and are not formally supported.

      1. This is complex and beyond the scope of Syndeia - however if your team is at a loss of adequate SMEs, our team has done this several times and we can advise your available staff - we do not recommend leaving this complex task to generalists.

  3. The two files that you will edit on your Windchill server are

    1. <Windchill>\codebase\WEB-INF\security\config\securityContext.properties

    2. <Windchill>\codebase\WEB-INF\web.xml

...

Assuming that Windchill already has Ping Federate as its IdP:

  1. Configure the “Oauth Client” in Ping Federate for Windchill with the additional “OAuth / Device Code Auth Grant Flow”

    1. The least necessary change is just “ALLOWED GRANT TYPE :: Device Authorization Grant (YES)”

    2. See the “Allowed Grant Types” figure below

  2. However, IF Lockheed has not yet configured Windchill for OAuth (with PingFederate)

    1. Then Lockheed should have their Windchill Team configure their Windchill service for delegated access control through PingFederate (See Step 2)

Configure the Syndeia Cloud windchill-impl application

Alter its conf/application.conf according to the expansion region below this list

Code Block
languagebash
cd /opt/icx/syndeia-cloud-current && sudo vi application.conf

...

Restart the Syndeia Windchill microservice

  1. sudo systemctl restart sc-windchill

  2. Note that it is web-gateway that offers the frontend code, you must also redeploy that service but the prep-step (0) above accomplishes that

  3. Contact Intercax.com/help if your team needs assistance in editing configuration files for specific microservices

Expand
titleApplication.conf Properties for a Windchill OAuth2 IdP
Code Block
# This section is used to provide OAuth configurations for Windchill repositories integrated with this Syndeia deployment
# It is possible to add OAuth configuration for more than one Windchill repository,
# for example, the section below contains OAuth configuration for two Windchill repositories - "http://wc11.example.com/Windchill" and "http://wc12.example.com/Windchill"
# The repository url of the Windchill repository, enclosed in double quotes (""), acts as the key of the OAuth configuration for that Windchill repository
# for example, "http://wc11.example.com/Windchill" is the key of one of the two OAuth configurations provided in the below section
external.auth.oauth {
  # windchill repository url
  "http://wc11.example.com/Windchill" {
    # device code endpoint configured in IdP
    deviceCodeEndpoint = "https://my.idp.example.com:9031/as/device_authz.oauth2"

    # token endpoint configured in IdP
    tokenEndpoint = "https://my.idp.example.com:9031/as/token.oauth2"

    # an identifier for Syndeia configured in IdP
    client_id = "example_client_id"

    # client secret for Syndeia configured in IdP
    client_secret = "example_client_secret"

    # scope of the access to Windchill server to be requested by Syndeia
    scope = "EXAMPLE_SCOPE"
  }
  "http://wc12.example.com/Windchill" {
    # device code endpoint configured in IdP
    # deviceCodeEndpoint = "https://my.another.idp.example.com:9031/as/device_authz.oauth2"
    deviceCodeEndpoint = "https://ping-federate.intercax.com:9031/as/device_authz.oauth2"

    # token endpoint configured in IdP
    # tokenEndpoint = "https://my.another.idp.example.com:9031/as/token.oauth2"
    tokenEndpoint = "https://ping-federate.intercax.com:9031/as/token.oauth2"

    # an identifier for Syndeia configured in IdP
    # client_id = "example_client_id"
    client_id = "rs_client"

    # client secret for Syndeia configured in IdP
    # client_secret = "example_client_secret"
    client_secret = "SJfj4TrHgG7pGPkpODzavnf6TiuPp6DGSTQTotGR8kyZV06QgOoCmjr99TvrTFkT"

    # scope of the access to Windchill server to be requested by Syndeia
    # scope = "EXAMPLE_SCOPE"
    scope = "WINDCHILL"
  }
  # add oAuth configuration for more windchill repositories here ...
}

Expand
titleAn Explanation of PTC's Windchill Authentication Architecture

“Windchill” is beyond a simple PLM, it is a technology stack consisting of Identity Management, Token Management, Single-sign on Session Management, Database Management, Organization Management, and, behind all that, Product Management.

Windchill delegates Oauth2 authentication for a subset of its API routes to Apache HTTPd, Tomcat Servlet Engine, Ping Federate, LDAP, and a Tomcat Spring Bean.

It is the Tomcat Spring Bean which is responsible for receiving an incoming HTTP Request from Apache HTTPd via AJP and Tomcat that has an HTTP Authorization Bearer token and for then performing the token introspection with the Ping Federate service to determine if the token is valid and to extract the effective Windchill user identity from the token before forwarding that HTTP Request on into the Windchill application.

PTC delivers their technology stack as a complex and complicated collection of template deployments, property files, XML configuration files, and Ant scripts.

During installation of the Windchill stack, the installing administrator executes several ant scripts to weave configuration properties into the template files to yield the eventual effective configuration files which inform the running HTTPd and Tomcat services.

A Tomcat servlet ecosystem consists of a web server (like Apache HTTPd) and one or more Tomcat “engines” (or instances) each of which may have multiple “hosts” where each “host” runs multiple “contexts”. Each “context” can be configured to offer service from multiple servlet contexts.

(Modern microservices developers can think of a “servlet context” as a “microservice” - except for the difference that modern microservices are supposed to be more pure in limiting their scope than was the practice for servlets.)

The Windchill PDMLink application is a Tomcat servlet context that is found in <WINDCHILL_DRIVE>/Windchill/codebase/WEB-INF.

The servlet filter in this servlet context that is responsible to receive an Oauth2-token-bearing HTTP Request, to extract the token, to verify the token with the Token Server (PingFederate), to extract the effective Windchill user id, and to forward the request into Windchill is found in the security folder of this WEB-INF directory. There is a securityContext.xml file and a securityContext.properties file.

Because PTC does not assume that all its customers will offer OAuth2 access for their Windchill APIs, the servlet’s Context’s configuration file, web.xml, does not include the necessary filter, filter-mapping, servlet, and servlet-mapping elements.

Installation involves adding the necessary property strings to the securityContext.properties file and then adding the missing XML fragments to the web.xml file in the right locations to assure that incoming HTTP requests flow through the right filter chains and are routed to the right servlets by the right servlet-mapping elements.

PTC documentation states how to configure the Windchill servlet context for OAuth2 authentication. (The advice above merely explains which Tomcat configuration to modify and is intended to explain why the modifications are made).

Note: The “Device Code" OAuth grant type is based on specific users and not on just a known single specific application-client to enforce the user-specific permissions and access controls as they connect to Windchill from the same specific application-client (“Syndeia”).

...

Be informed that a Device Code Grant Flow has been chosen both for its high user “user ability” and for cybersecurity controls - it is the only Grant Flow which supports both users using web browsers and scripts making API calls while assuring that all such service requests are traced directly to the specific user making those requests and not to a single “application” identity or to a “digital service account”.

...

Step 2: Restart the Syndeia Windchill & Web-gateway microservices

  1. Code Block
    languagebash
    sudo systemctl restart sc-windchill sc-webgateway

After you have configured Windchill and Ping Federate and after you have configured Syndeia’s windchill microservice for OAuth, you likely will want to add a Windchill Repository instance using the Syndeia Web Dashboard. Read Adding a Windchill Repository using OAuth for that guide.

Contact Intercax.com/help if your team needs assistance in editing any configuration files for specific microservices