Active Directory Extension User Guide Version 1.0
Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. User and training guides and related documentation from PTC Inc. and its subsidiary companies (collectively PTC ) are subject to the copyright laws of the United States and other countries and are provided under a license agreement that restricts copying, disclosure, and use of such documentation. PTC hereby grants to the licensed software user the right to make copies in printed form of this documentation if provided on software media, but only for internal/personal use and in accordance with the license agreement under which the applicable software is licensed. Any copy made shall include the PTC copyright notice and any other proprietary notice provided by PTC. Training materials may not be copied without the express written consent of PTC. This documentation may not be disclosed, transferred, modified, or reduced to any form, including electronic media, or transmitted or made publicly available by any means without the prior written consent of PTC and no authorization is granted to make copies for such purposes. Information described herein is furnished for general information only, is subject to change without notice, and should not be construed as a warranty or commitment by PTC. PTC assumes no responsibility or liability for any errors or inaccuracies that may appear in this document. The software described in this document is provided under written license agreement, contains valuable trade secrets and proprietary information, and is protected by the copyright laws of the United States and other countries. It may not be copied or distributed in any form or medium, disclosed to third parties, or used in any manner not provided for in the software licenses agreement except with written prior approval from PTC. UNAUTHORIZED USE OF SOFTWARE OR ITS DOCUMENTATION CAN RESULT IN CIVIL DAMAGES AND CRIMINAL PROSECUTION. PTC regards software piracy as the crime it is, and we view offenders accordingly. We do not tolerate the piracy of PTC software products, and we pursue (both civilly and criminally) those who do so using all legal means available, including public and private surveillance resources. As part of these efforts, PTC uses data monitoring and scouring technologies to obtain and transmit data on users of illegal copies of our software. This data collection is not performed on users of legally licensed software from PTC and its authorized distributors. If you are using an illegal copy of our software and do not consent to the collection and transmission of such data (including to the United States), cease using the illegal version, and contact PTC to obtain a legally licensed copy. Important Copyright, Trademark, Patent, and Licensing Information: See the About Box, or copyright notice, of your PTC software. UNITED STATES GOVERNMENT RESTRICTED RIGHTS LEGEND PTC software products and software documentation are commercial items as that term is defined at 48 C.F.R. 2.101. Pursuant to Federal Acquisition Regulation (FAR) 12.212 (a)-(b) (Computer Software) (MAY 2014) for civilian agencies or the Defense Federal Acquisition Regulation Supplement (DFARS) at 227.7202-1(a) (Policy) and 227.7202-3 (a) (Rights in commercial computer software or commercial computer software documentation) (FEB 2014) for the Department of Defense, PTC software products and software documentation are provided to the U.S. Government under the PTC commercial license agreement. Use, duplication or disclosure by the U.S. Government is subject solely to the terms and conditions set forth in the applicable PTC software license agreement. PTC Inc., 140 Kendrick Street, Needham, MA 02494 USA
Contents Introduction and Installation... 2 Overview... 2 Installation... 2 Remote Active Directory Network Installation... 2 Configuration... 3 Configuring a Local Domain... 3 Example Local Active Directory Configuration... 5 Configuring a Remote Domain... 7 Creating the Application Key for your Remote Domain... 7 Configuring the ConfigurationLDAP.xml... 7 XML Elements and Descriptions... 9 Running the ADAgent... 9 Verifying the ADAgent is running and visible... 9 Remote Domain Installation in ThingWorx Composer... 10 Enabling Authenticator... 13 Logging Into ThingWorx via Forms Login... 13 Default Form Login Page... 13 Active Directory Group Maintenance... 15 Active Directory Management Mashup... 15 Logging In to ThingWorx via Forms Login... 16 Default Form Login Page... 16 Domain Form Login Pages... 17 Active Directory Group Maintenance... 18 Active Directory Management Mashup... 18 Troubleshooting... 21 Compatibility... 22 Document Revision History... 22 Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 1
Introduction and Installation Extensibility is a core aspect of the architecture and design of ThingWorx. Partners, third parties, and users, as well as ThingWorx can easily add new functionality into the system in a seamless manner. Extensions can be Service (function/method) libraries, Connector Templates, Widgets, and more. This document provides installation and usage instructions for the Callisto Integration Active Directory Extension. Overview The Active Directory extensions package, created by Callisto Integration, Inc., implements new ThingWorx entities, including an administrative mashup for the purposes of creating a seamless Active Directory integration within ThingWorx. The extension will additionally provide remote domain user authentication and group membership protocols. The extension provides for true active directory integration by pulling in Active Directory (AD) user group details and querying your domain controllers. This means that each organizations active directory is the authority for governance of user access to ThingWorx. This alleviates having to maintain users in both ThingWorx and AD. Therefore, the AD becomes the system of record for user group membership. This extension will create an active directory user automatically, if they belong to a connected Active Directory group that has been properly configured as a ThingWorx group inside of ThingWorx. The complete integration insures that Users who no longer belongs to a group in the connected AD will be removed from that corresponding group in ThingWorx automatically. When the ThingWorx Platform needs to connect to one of these devices, the need for a translator, or Protocol Adapter, arises. The Protocol Adapter SDK is a package provided by ThingWorx for the purposes of connecting such a device, whose firmware and/or data format is unchangeable and incompatible with ThingWorx, to the ThingWorx Platform: Installation Open Composer and click Import/Export > Import. 2. Select the ActiveDirectoryUtility_Extension and click Import. Remote Active Directory Network Installation In order to communicate with a remote domain for credential and group verification, the ADAgent will need to be installed on a remote machine that is a member of the Active Directory network in the Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 2
remote domain. To begin installation of the Remote Active Directory, copy the ADAgent folder to any location on the remote machine. The ADAgent includes the following files and folders: ActiveDirectoryAgent.jar ADAgent.exe Configfile (folder) ConfigurationLDAP.xml Configuration There are three Thing Templates that are brought in during installation the ActiveDirectoryUtilityTemplate, ActiveDirectoryRemoteUtilityTemplate, and the DomainSwitchTemplate. The ActiveDirectoryUtilityTemplate should be used for configuring access to a domain that is local to the ThingWorx server and the remote template should be used for configuring a remote domain. The DomainSwitchTemplate automatically creates a DomainSwitch Thing and is utilized by the Administrative Mashup. Configuring a Local Domain Please note that assistance from IT in getting the specific parameters for this configuration may be required. 1. Create a new Thing entity from the ActiveDirectoryUtilityTemplate Thing Template. Ensure that the name of the entity matches the name of your AD domain (remove any dot references). For instance, if the domain name is Globex.local or Globex.com, just use Globex. 2. Press Save and then click Edit. 3. Go to the Configuration page for the thing. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 3
4. Fill out the credentials and configuration information so that it matches the Server, Domain Controller, and Port of your Active Directory computer. Note that the computer hosting your ThingWorx instance (for a Local Active Directory connection) must be part of the same domain as the Active Directory to which you are trying to connect. a. For User, typically you want to choose a network user that the password doesn t change on. This account can be configured to have limited active directory rights (user validation and read access for user group membership). This user must be a configured Domain user. b. Enter your LDAP server in Server field. c. Enter your domain controller in the Domain Controller field. Using Globex.local as an example, this would typically be DC=Globex,DC=local. d. Enter in the port in the Port field. This is typically 389 for LDAP-type traffic, but it may be different. e. Enter the password in the Password field which is tied to the Username you are using. This user must be a configured Domain user. 5. Press the Save button. Refer to the screenshot below for an example configuration. You may also refer to the troubleshooting section for more assistance. 6. Click the Services tab, and press the Test button next to the service named TestActiveDirectoryConnection. Execute the service on the next page. This Service will return a value of true if your configuration parameters are valid. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 4
Example Local Active Directory Configuration The screenshots in this section show the configuration and expected results of a properly configured Local Active Directory connection. The configuration for an example Local AD Instance Connection Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 5
Successful connection to the local AD instance (shown previously), and the groups to which the user has access rights A screenshot of the User in ThingWorx, which was created automatically via the Active Directory Extension. This user has a description created which specifies that the ThingWorx user was created by the Active Directory Utility Extension. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 6
Configuring a Remote Domain Creating the Application Key for your Remote Domain For your Remote Active Directory to be able to communicate with the ThingWorx Platform, you must first set up an Application Key that the remote connection will use. This Application Key is added to the appropriate XML element in the ConfigurationLDAP.xml file located on the remote machine. Follow the steps below to create an Application Key. 1. Log in to ThingWorx Composer as a user with Administrator privileges. 2. Under the Security dropdown in the Composer, select Application Keys. 3. Select New to create a new key. 4. Configure your Application Key as follows: Name: ActiveDirectoryAppKey (this name is optional) User Name Reference: ActiveDirectoryAdministrator (this value is required) 5. Select Save. Your Application Key is generated. Configuring the ConfigurationLDAP.xml The ConfigurationLDAP.xml is what controls the connection between your remote thing and the ThingWorx platform. To set up the configuration files follow the below instructions. This file can be set up to support multiple Active Directory Domains if there happens to be multiple domains on your network that you would wish to validate against. Example ConfigurationLDAP.xml Setup <?xml version="1.0" encoding="utf-8" standalone="no"?> Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 7
<things> <domains> <domain> <name>globex</name> <password>your Password in Plain Text Here</Password> <encrypted-password></encrypted-password> </domain> </domains> <client> <name>globexclient</name> <url>ws://globex-vm:443/thingworx/ws</url> <appkey>46ad9fed-4291-470f-a294-3e14c4cafeb5</appkey> <scanrate>1000</scanrate> <reconnectinterval>15</reconnectinterval> </client> </things> Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 8
XML Elements and Descriptions Element <domain> <name> <password> <encrypted-password> <client> <name> <url> <appkey> <scanrate> <reconnectinterval> Description Each instance of your Active Directory Domain. The name of your AD Domain. This must resemble the prefix for your local domain. Example: If your network is DC=Globex,DC=Com then the name would be Globex. Plain text password that your Active Directory lookup user will use. Once ADAgent.exe is started, the application will convert your plain text password into a hashed secure password so it is not in plain text. Hashed password (created after ADAgent.exe executes). Note: If you wish to change the password of the Active Directory user, you need to place a new plain text password in the <password> element and run ADAgent.exe again. Information used by the ThingWorx Platform to communicate with this remote thing. Name of your client. Set this to your domain with Client at the end. Example: GolbexClient This is the address of your ThingWorx Platform. Change the IP address and port to match that of your ThingWorx server. Example: ws://<yourip>:<port>/thingworx/ws Application Key that was created in the section Creating the Application Key for your Remote Domain. Copy it to this element. How frequently (number of milliseconds) the thing will look for changes in configuration from the ThingWorx Platform. How often (number of seconds) this remote thing will attempt to reconnect to the ThingWorx Platform if disconnected. Running the ADAgent To run the configured ADAgent, double-click the executable. Verifying the ADAgent is running and visible To verify that the ADAgent is running and visible to the ThingWorx Platform, do the following: 1. Run the ADAgent.exe on your remote location. 2. Log in to the ThingWorx Platform with an Administrator user. 3. Select Monitoring on the header bar of the Composer. 4. Select Remote Things under Status. 5. In the ThingWorxMonitor select Unbound. If everything was set up correctly, the page will show your Remote AD. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 9
Remote Domain Installation in ThingWorx Composer Now that your remote Active Directory has been setup and is currently running on its remote location, you can begin setting up the thing inside the Composer, as explained below. 1. Log in to the ThingWorx Composer as a user with Administrator privileges. 2. Under the Visualization dropdown in the Composer, select Mashups. 3. Select to open the Active Directory Management Mashup. 4. Select View Mashup. The mashup is shown. Your unbound domain appears in the Unbound Remote Domains section of the mashup.. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 10
5. Select your unbound domain and click Create Things. This executes a service that finds this currently active remote domain (as long as it s currently running on your remote location) and creates the base configuration of your Thing Entity. After you click Create Things, you ll see that domain disappear from the list. 6. Navigate to the Composer Home screen. 7. Under the Modeling dropdown, select Things. You will see your new thing listed here, as well as an accompanying organization entity. For example, if your remote domain is named ACME, then the thing and organization that are created will share that same name. The name of this thing can also be found on the remote location in the ConfigurationLDAP.xml file. 8. Open your newly created Thing for editing. 9. Select the Configuration tab under Entity Information. 10. Configure your remote thing by filling in the User, Server, Domain Controller, and Port fields with the proper information to connect to your AD instance. An example configuration is shown in the following figure: Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 11
Note: Your Username may include the domain as a prefix as well, depending on your configuration. To include the domain in your User field (for this example), enter it with the following format: ACME\ACMEADUser for a domain of ACME and a username of ACMEADUser. 11. Select Save. 12. Navigate to the Services section in this Remote Thing. 13. Select Test on service testactivedirectoryconnection. 14. Select Execute Service. The result will show True if your configuration settings are correct. Troubleshooting tips for a false test result If you receive a False test result, use the following troubleshooting tips to try to resolve it. Save the thing and then try Test again. Determine if there is an issue with the configuration settings. The user in the configuration that is used to do the Active Directory lookup may require the domain to prefix the name as explained in the previous note. For example: Globex\Administrator. Make sure the Application Key is correct and included in the ConfigurationLDAP.xml file. Make sure the remote service is running on your remote domain. Check the Application Log for error messages. Once the service returns True (as shown in the following figure), it s ready to be used. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 12
Enabling Authenticator The Authenticators are located in the ThingWorx Explorer under Security. In order to use the ActiveDirectoryAuthenticator it must first be enabled. 1. Open the ActiveDirectoryAuthenticator and click Edit. 2. Select Enabled and click Save. Important: By default, the ActiveDirectoryAuthenticator comes in with the highest priority 1. If you wish to use this authenticator, the priority should not be changed. Logging Into ThingWorx via Forms Login Default Form Login Page Once this extension has been imported into the ThingWorx Platform, it will generate a default Organization called ActiveDirectoryLogin. This organization is the generic login point for ThingWorx. In this login page, you can access and log in as any user in the Platform (that is, ThingWorx default Administrator ). Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 13
The special case in this instance is that if you wish to use this page to log in to one of your domains, you will be required to prefix your user name with the domain you re trying to validate against. The default URL to access the ActiveDirectoryLogin page: http://<yourserverip>:<port>/thingworx/formlogin/activedirectorylogin where you replace yourserverip, port, and ActiveDirectoryLogin with your specific information. When you have successfully set up your remote domain, an Organization entity in the ThingWorx Platform will have been created. For example: If your domain is Globex then a Globex Organization entity will exist on your Platform. To access the login page for users to use, go to the following URL: http://<yourserverip>:<port>/thingworx/formlogin/activedirectorylogin where you replace yourserverip, port, and ActiveDirectoryLogin with your specific information. Note: Only users who are on this specific domain can log in to the ThingWorx Platform from this location. Domain prefix in the username is NOT required to log in here. In this example, the login username would be Globex. To log in to that user from this Form Login page, all that is required is your Username, without the Globex prefix, followed by your Active Directory Password. If you d like to add your company logo to this login page, navigate to this organization entity in the ThingWorx Composer and select a Login Image under the General Information section. Also, it should be noted that the appropriate ThingWorx Active Directory groups must first be set up in the ThingWorx Platform. If at least one group to which the user belongs in Active Directory is not configured, then that user will be denied access. Also, groups that have been added via the group Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 14
management mashup (discussed later), will need to be added to other groups that have configured permissions, or will need to have permissions configured for them. Note: A user s ability to view groups and his current AD status are only refreshed and loaded upon logging in to ThingWorx from the Form Login page. Any changes made while the user is logged in to ThingWorx will not be reflected on the ThingWorx Platform until that user s next login. Active Directory Group Maintenance The Active Directory Group Maintenance Mashup has been provided for ease of use in configuring the Active Directory groups within ThingWorx. The mashup allows users with appropriate permissions to add the Active Directory groups to ThingWorx, and, if desired, assign them to existing ThingWorx groups. Active Directory Management Mashup The Active Directory Management Mashup consists of two tree view selectors. The left-hand tree view selector contains the list of active directory groups associated with the domain (Available Active Directory Groups). The right-hand tree view contains the list of groups that have been configured for the selected domain (Configured ThingWorx Groups). All ThingWorx domain-specific group names are prefaced with the domain name in order to maintain uniqueness across domains. For instance, if the example group ACME contained an Administrators group in its Active Directory, and Globex also had an Administrators group in its Active Directory, these would be maintained uniquely and could co-exist inside the ThingWorx environment by nature of being provisioned with the domain name. To add new groups to your Platform Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 15
1. From the Available Active Directory Groups, select the active directory group. 2. From the Configured ThingWorx Groups list, select the parent group to which the active directory group should be added 3. Press the Add Group button. To remove groups from your Platform 1. From the Configured ThingWorx Groups list, select the group. 2. Press the Remove Group button. If this group does not belong to any other groups, then it will be deleted. You can also choose to filter the list of Available Active Directory Groups by typing in the text box next to the magnifying glass in the top-right (the Filter Groups List text box). After you type in the box, exit the text box to have it automatically filter the Available Active Directory Groups. ThingWorx groups may be assigned access rights to maintain all domains. Users who are members of these groups will be able to switch domains by pressing the domain name displayed in the upper left hand corner. This will then trigger the display of a domain name selector popup. Logging In to ThingWorx via Forms Login Default Form Login Page Once this extension has been imported into the ThingWorx Platform, it will generate a default organization called ActiveDirectoryLogin. This organization is the generic login point for ThingWorx. In this login page, you can access and log in as any user in the platform (that is, ThingWorx default Administrator ). Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 16
The special case in this instance is that if you wish to use this page to log in to one of your domains, you will be required to prefix your username with the domain against which you re trying to validate. Default URL to access ActiveDirectoryLogin page: http://<yourserverip>:<port>/thingworx/formlogin/activedirectorylogin where you replace yourserverip, port, and ActiveDirectoryLogin with your specific information. Domain Form Login Pages When you have successfully set up your remote domain, an organization entity in the ThingWorx Platform will have been created. For example: If your domain is Globex then a Globex Organization entity will exist on your Platform. To access the login page for users to use, go to the following URL: http://<yourserverip>:<port>/thingworx/formlogin/activedirectorylogin where you replace yourserverip, port, and ActiveDirectoryLogin with your specific information. Note: Only users that are on this specific domain can login to ThingWorx from this location. Domain prefix in the username is NOT required to login here. In this example, the login username would be Globex. To log in to that user from this Form Login page, all that is required is your Username, without the Globex prefix, followed by your Active Directory Password. If you d like to add your company logo to this login page, navigate to this organization entity in the composer and select a Login Image under the General Information section. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 17
Also, it should be noted that the appropriate ThingWorx active directory groups must first be set up in ThingWorx. If at least one group the user belongs to in the Active Directory is not configured, that user will be denied access. Also, groups that have been added via the Group Management Mashup (discussed below), will need to be added to other groups that have configured permissions, or will need to have permissions configured for them. Note: A User s ability to view groups and his current AD status are only refreshed and loaded upon logging in to ThingWorx from the Form Login page. Any changes made while the user is logged in to ThingWorx will not be reflected on the ThingWorx Platform until that user s next login. Active Directory Group Maintenance The Active Directory Group Maintenance Mashup has been provided for ease of use in configuring the Active Directory Groups within ThingWorx. The mashup allows users with appropriate permissions to add the Active Directory groups to ThingWorx, and, if desired, assign them to existing ThingWorx groups. Active Directory Management Mashup The Active Directory Management Mashup consists of two tree view selectors. The left-hand tree view selector contains the list of active directory groups associated with the domain (Available Active Directory Groups). The right-hand tree view contains the list of groups that have been configured for the selected domain (Configured ThingWorx Groups). All ThingWorx domain-specific group names are prefaced with the domain name in order to maintain uniqueness across domains. For instance, if the example group ACME had an Administrators group in its active directory, and Globex also had an Administrators group in its active directory, these would be uniquely maintained and could co-exist inside the ThingWorx environment by nature of being provisioned with the domain name. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 18
To add new groups to your Platform 1. From the Available Active Directory Groups, select the active directory group. 2. From the Configured ThingWorx Groups list, select the parent group to which the active directory group should be added 3. Press the Add Group button. To remove groups from your Platform 1. From the Configured ThingWorx Groups list, select the group. 2. Press the Remove Group button. If this group does not belong to any other groups, then it will be deleted. You can also choose to filter the list of Available Active Directory Groups by typing in the text box next to the magnifying glass in the top-right (the Filter Groups List text box). After you type in the box, exit the text box to have it automatically filter the Available Active Directory Groups. ThingWorx groups may be assigned access rights to maintain all domains. Users that are members of these groups will be able to switch domains by pressing the domain name displayed in the upper left hand corner. This will then trigger the display of a domain name selector popup. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 19
Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 20
Troubleshooting Problem 1 When testing the Active Directory Connection, the service returns False. Solution(s) 1. For local testing, verify that the computer running ThingWorx is a part of the same Domain as the Active Directory. 2. Verify that the configuration criteria are all correct. You may benefit from downloading a tool such as Softerra LDAP Administrator to assist in diagnosing incorrect configuration criteria. 3. Check the ThingWorx Application Log (Monitoring > Logs > Application Log) to narrow down LDAP connection problems. 4. If you see the following error in the application log (error code 49 80090308), it is likely your user credentials are incorrect. Confirm them and try again. 2 I am connected to my Active Directory, but no Groups are showing either on the Mashup or through the GetDomainGroups Service. 3 I cannot see any Groups, or my Active Directory Domain is not listed on the Mashup. 1. You ll need to verify that the permissions and domain membership of the user you are logged in as have access to see the groups you expect on your Active Directory instance. Contact your IT Administrator for assistance. 2. On the configuration page for your ThingWorx AD Instance, try using a username whose permissions and group membership you have confirmed are accessible to that user. 1. Verify that you are connected to the Active Directory by running the TestActiveDirectoryConnection service on your Thing entity. 2. On the Mashup, click the link next to Domain at the topleft of the screen. Following this, a pop-up window should Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 21
Problem Solution(s) appear in the center of the window with a drop-down box for choosing the correct Domain. Choose your domain if it is listed, and click OK. 3. Verify that you are able to see Active Directory groups via the Test button the services section of your thing Entity to confirm that the service works before attempting to populate them on the Mashup. Compatibility This Extension has been tested for compatibility with the following ThingWorx and PC Operating Systems: Component Description ThingWorx Platform Version ThingWorx 6.0.1 OS Windows 7, Service Pack 1 Document Revision History Revision Date Version Description of Change October 8, 2015 1.0 Initial Release Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 22