Credentials Mapping for Adapters

Advanced Customization > Info*Engine User’s Guide > Credentials Mapping > Credentials Mapping for Adapters

Credentials mapping for adapters works using the following process:

• Windchill is pre-configured to include a credentials mapping task. This task is configured through the Windchill adapter using the wt.federation.task.mapCredentials property value, which is set to /wt/federation/MapCredentials.xml. The contents of this task are dynamically generated, starting with the following file:

<Windchill>/tasks/wt/federation/MapCredentials.xml.template

using the property values found in site.xconf.

Windchill’s LDAP access for user and group information relies on this credentials mapping task, and can provide credentials to adapters based on whether the current user is an administrator or a regular user. If you would like to modify mapped credentials, you can set properties in site.xconf. For more information, read the contents of MapCredentials.xml.template and see the “Managing the Credentials Task” section below.

If you need to customize this task you should do so by modifying the MapCredentials.xml.template file. You should also keep a backup copy, because patch or maintenance release installation may overwrite your customization.

• Your Info*Engine administrator sets the configuration property named .credentialsMapper (which defines the mapping task and enables credentials mapping), and optionally sets the .credentialsTimeToLive and .credentialsFiles properties (which indicate how long the information should remain cached and if there are additional files that have mapping information in them).

• When Info*Engine is called to parse and execute a JSP page or a task that accesses an adapter, it checks to see if a credentials mapping task has been defined. If it discovers that one has been defined, it executes the specified task before executing the JSP page or task originally passed to it. The output group produced by the credentials mapping task is saved as a context group named Auth-Map.

• When Info*Engine encounters a webject that must be routed to an adapter, it checks the webject to see if DBUSER and PASSWD parameters have been explicitly specified. If they have not been specified, it uses the value of the webject INSTANCE parameter as a key to find DBUSER and PASSWD values in the Auth-Map context group. If values are found, it adds them to the webject as if they had been specified explicitly by the author of the task. Otherwise, the webject is routed to the adapter unmodified.

Creating a Credentials Mapping Task

Each element of the Auth-Map context group produced as the output group from the credentials mapping task must contain three attributes named INSTANCE, DBUSER, and PASSWD. The value of INSTANCE identifies the adapter to which the element applies. The values of DBUSER and PASSWD provide the authentication information to be passed to the adapter in cases where explicit DBUSER and PASSWD parameters are not specified on an adapter webject.

When a credentials mapping task executes, all normal context information is available to it. For example, the SERVER context group is available. If a request sent by a browser to Info*Engine has been authenticated by the web server, then the SERVER group contains an attribute named Auth-User. This attribute specifies the username that was authenticated by the web server. The credentials mapping task can use that username as a key to obtain user-specific authentication information from one or more adapter-accessible information systems. It can then create an output group from that authentication information.

The following credentials mapping task example creates a group that contains all valid username and INSTANCE name combinations with corresponding DBUSER and PASSWD values. From this group, it then selects only those elements that contain the authenticated username. These elements then make up the Auth-Map group:

<%@page language="java" session="false"%>

<%@taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>



<ie:webject name="Create-Group" type="GRP">
  <ie:param name="GROUP_OUT" data="AuthGroup"/>
  <ie:param name="CLASS" data="AuthorizationRecord"/>
  <ie:param name="DELIMITER" data=":"/>
  <ie:param name="ELEMENT" data="USERNAME=abc:INSTANCE=com.myHost.jdbcScott:
DBUSER=scott:PASSWD=tiger"/>
  <ie:param name="ELEMENT" data="USERNAME=abc:INSTANCE=com.myHost.jdbcAdapter:
DBUSER=abc:PASSWD=abc123"/>
  <ie:param name="ELEMENT" data="USERNAME=xyz:INSTANCE=com.myHost.myGateway:
DBUSER=xyz:PASSWD=xyz123"/>
  <ie:param name="ELEMENT" data="USERNAME=test:INSTANCE=com.myHost.myGateway:
DBUSER=mno:PASSWD=mno123"/>
</ie:webject>



<ie:webject name="Subset-Group" type="GRP">
  <ie:param name="GROUP_IN" data="AuthGroup"/>
  <ie:param name="FILTER" data="USERNAME='$(SERVER[]AUTH-USER[0])'"/>
  <ie:param name="CASE_IGNORE" data="TRUE"/>
  <ie:param name="GROUP_OUT" data="Auth-Map"/>
</ie:webject>

If this task runs when the authenticated user is “abc,” then the resulting elements in the Auth-Map group would be:

USERNAME	INSTANCE	DBUSER	PASSWD
abc	com.myHost.jdbcScott	scott	tiger
abc	com.myHost.jdbcAdapter	abc	abc123

Then, using the webject INSTANCE parameter, Info*Engine determines which DBUSER and PASSWD parameter values to add.

Creating Credential Mapping Files

Credential mapping files provide a way of setting an initial DBUSER and PASSWD parameter for individual users. Each file name is the name of a user. In the file for a specific user, enter one or more lines, where each line has the following format:

instance:dbuser:passwd

where:

instance specifies the name of an Info*Engine adapter.

dbuser specifies the username to be set in the DBUSER parameter of the webject.

passwd specifies the password that corresponds with the username. It is the value to be set in the PASSWD parameter of the webject.

The resulting file contains the usernames and passwords that can be used to access information systems.

The path to a directory containing credentials files can be configured using the wt.property of wt.federation.mapCredentials.files. If this property is not set, credentials mapping files are not used.

To activate credentials mapping through credentials mapping files, you must validate the request information by setting a secret in the task processor .secret.text or .secret.text2 property.

If both the wt.federation.mapCredentials.files and the wt.federation.task.mapCredentials properties are set, file-based mapping is performed first, then the credentials mapping task is executed. This allows some base or default mapping information to be specified using files then augmented or overridden by the task.

Managing the Credentials Task

The MapCredentials.xml file is used to specify a username and password for a specific Info*Engine adapter. This file is updated and managed using the xconfmanager, and should not be manually edited. If manually edited, when the propagation operation is performed the xconfmanager overwrites those values using values obtained from the site.xconf file. For more information, see About the xconfmanager Utility.

There are two variations of the property used to set username and password credentials. The mapcredentials.admin.adapters property is used when Windchill accesses the adapter on behalf of a Windchill administrator (a user with administrative privileges). And mapcredentials.nonprivileged.adapters is used when Windchill accesses an adapter on behalf of a user who does not have administrative privileges.

Using the xconfmanager utility, you can commands similar to the following to set these properties:

xconfmanager -p -s "mapcredentials.admin.adapters=<adapter name>^
<privileged User>^<privileged user password>"
-t "codebase/WEB-INF/mapCredentials.txt"

To set credentials for a Windchill administrator, use the following command:

mapcredentials.admin.adapters=<unique name of the adapter>^<username>^<password>

To set credentials for a user without Windchill administration privileges, use the following command:

mapcredentials.nonprivileged.adapters=<unique name of the adapter>^<username>^<password>

Both variations of this property are multivalued, and no default is defined. Use the -add command in the xconfmanager to add additional adapter definitions, and use -set to remove them.

For example, during installation the following xconfmanager commands are executed to define the credentials for the various JNDI adapters:

xconfmanager -p --set "mapcredentials.admin.adapters=com.ptc.ptcnet.LDAP^cn=manager,
0=ptc^admin"
-t "codebase/WEB-INF/mapCredentials.txt"

xconfmanager -p --add "mapcredentials.admin.adapters=com.ptc.ptcnet.EnterpriseLdap^
cn=manager^admin"
-t "codebase/WEB-INF/mapCredentials.txt"

xconfmanager -p --add "mapcredentials.admin.adapters=com.ptc.ptcnet.Ldap-Pending^
cn=manager^admin"
-t "codebase/WEB-INF/mapCredentials.txt"

To add non-privileged adapters:

xconfmanager -p --set "mapcredentials.nonprivileged.adapters=enterpriseAdapter1^
cn=nonprivuser1,o=ptc^password1"
-t "codebase/WEB-INF/mapCredentials.txt"

To remove an adapter:

xconfmanager -p --remove "mapcredentials.nonprivileged.adapters=enterpriseAdapter1^
cn=nonprivuser1,o=ptc^encrypted.enterpriseAdapter1.cn=nonprivuser1,o=ptc"
-t "codebase/WEB-INF/mapCredentials.txt"

To reset the MapCredentials task, clearing all definitions of a specified type:

xconfmanager -p --reset "mapcredentials.nonprivileged.adapters"
-t "codebase/WEB-INF/mapCredentials.txt"

xconfmanager -p --reset "mapcredentials.admin.adapters"
-t "codebase/WEB-INF/mapCredentials.txt"