Services Standard Build User Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 50
| Download | |
| Open PDF In Browser | View PDF |
Services Standard Build User Guide SSB v6, July 2018 This document is intended to be a user-friendly guide explaining how to set-up the Services Standard Build, as well as its applications. Document Revision History Revision Date February 2013 March 2013 April 2013 June 2013 August 2013 January 2015 June 2016 September 2016 October 2016 December 2016 January 2017 February 2017 June 2017 December 2017 July 2018 Written/Edited By Comments Blake Bowen Initial Creation (Current IdentityIQ version: 6.0) Tina Timmerman Brendon Jones Blake Bowen Blake Bowen Blake Bowen Blake Bowen Paul Wheeler 1st Revision 2nd Revision Final Revision for SSB 1.2, posted to Compass Updated Compass links to new Compass Updated with version 1.5 features, new Compass links, and further clarification. Updated Compass link to point to SSD get started page Updated with new features added in v2. Paul Wheeler Minor corrections for revision 2.0.1. Paul Wheeler Example custom script file names modified so that they do not execute unless renamed. Support for environment-specific build.properties files clarified. Minor restructure and updates for SSB v3 release Paul Wheeler Paul Wheeler Justin Choponis, Paul Wheeler Paul Wheeler Paul Wheeler Services Standard Build User Guide Formatting and structure changes. Updates for SSB v4 release Added plugin build information for SSB v5, added Deprecation Scanner in the Build Checks. Added functionality for subset builds, IdentityIQ keystore file deployment and “secret” target.properties files for SSB v6. Expansion of efixes in timestamp order. Additional Build Check for Workflow trace setting. Added information on the Dependency Check utility. Page 2 of 50 © Copyright 2018 SailPoint Technologies, Inc., All Rights Reserved. SailPoint Technologies, Inc. makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. SailPoint Technologies shall not be liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance, or use of this material. Restricted Rights Legend. All rights are reserved. No part of this document may be photocopied, reproduced, or translated to another language without the prior written consent of SailPoint Technologies. The information contained in this document is subject to change without notice. Use, duplication or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 for DOD agencies, and subparagraphs (c) (1) and (c) (2) of the Commercial Computer Software Restricted Rights clause at FAR 52.227-19 for other agencies. Regulatory/Export Compliance. The export and reexport of this software is controlled for export purposes by the U.S. Government. By accepting this software and/or documentation, licensee agrees to comply with all U.S. and foreign export laws and regulations as they relate to software and related documentation. Licensee will not export or reexport outside the United States software or documentation, whether directly or indirectly, to any Prohibited Party and will not cause, approve or otherwise intentionally facilitate others in so doing. A Prohibited Party includes: a party in a U.S. embargoed country or country the United States has named as a supporter of international terrorism; a party involved in proliferation; a party identified by the U.S. Government as a Denied Party; a party named on the U.S. Government's Entities List; a party prohibited from participation in export or reexport transactions by a U.S. Government General Order; a party listed by the U.S. Government's Office of Foreign Assets Control as ineligible to participate in transactions subject to U.S. jurisdiction; or any party that licensee knows or has reason to know has violated or plans to violate U.S. or foreign export laws or regulations. Licensee shall ensure that each of its software users complies with U.S. and foreign export laws and regulations as they relate to software and related documentation. Trademark Notices. Copyright © 2018 SailPoint Technologies, Inc. All rights reserved. SailPoint, the SailPoint logo, SailPoint IdentityIQ, and SailPoint Identity Analyzer are trademarks of SailPoint Technologies, Inc. and may not be used without the prior express written permission of SailPoint Technologies, Inc. All other trademarks shown herein are owned by the respective companies or persons indicated. Services Standard Build User Guide Page 3 of 50 Table of Contents Services Standard Build Overview ......................................................................................................... 7 SSB Components ........................................................................................................................... 7 Apache Ant ................................................................................................................................. 7 Ant Contrib .................................................................................................................................. 8 Catalina-Ant ................................................................................................................................ 8 Custom Ant Tasks ....................................................................................................................... 8 Process Overview .............................................................................................................................. 9 Downloading the Services Standard Build ........................................................................................ 10 Folder Structure ............................................................................................................................ 10 .keep Files .................................................................................................................................... 13 Exporting Custom Objects ................................................................................................................ 13 Running the Export Script ............................................................................................................. 14 Build Structure Set-up ...................................................................................................................... 17 Configuration Objects ................................................................................................................... 17 IdentityIQ Product Files................................................................................................................. 17 Plugins.......................................................................................................................................... 17 Build/Compilation of Plugins ...................................................................................................... 17 Automatic Deployment of Plugins .............................................................................................. 18 JDBC Drivers ................................................................................................................................ 19 Build Configuration ........................................................................................................................... 20 Configuring the build.properties file ............................................................................................... 20 Supporting multiple platforms (Windows/Linux/Unix) for different environments ........................ 25 Non-default spadmin password and importing artifacts ............................................................. 26 Setting up environment-specific properties files ............................................................................ 26 Configuring iiq.properties files ................................................................................................... 26 Configuring target.properties files .............................................................................................. 28 Configuring “secret” target.properties files for storing sensitive token values ............................. 29 Configuring Subset Builds with includefiles.properties files ....................................................... 30 Configuring ignorefiles.properties files ....................................................................................... 31 Configuring log4j.properties files ............................................................................................... 31 Configuring deployment of encryption keys for each environment ............................................. 32 Setting the environment name for a build .................................................................................. 33 Services Standard Build User Guide Page 4 of 50 Using the SPTARGET environment variable to specify the build environment ....................... 33 Setting the target variables by editing servers.properties ....................................................... 33 Executing the Build .......................................................................................................................... 34 Executing a Repeatable, Initial Build of IdentityIQ with SSB ......................................................... 35 Initial Build Prerequisites ........................................................................................................... 35 Initial Build Target Chaining....................................................................................................... 37 Installation ............................................................................................................................. 37 Removal ................................................................................................................................ 37 Dev targets explained....................................................................................................................... 38 No target (just entering “build” into a windows terminal or “./build.sh” into a Linux terminal) .......... 38 main.............................................................................................................................................. 38 clean ............................................................................................................................................. 38 cleanWeb ..................................................................................................................................... 38 createdb ....................................................................................................................................... 39 cycle ............................................................................................................................................. 39 dropdb .......................................................................................................................................... 39 dist ................................................................................................................................................ 40 dependency-check........................................................................................................................ 40 deploy ........................................................................................................................................... 40 document ...................................................................................................................................... 40 down ............................................................................................................................................. 40 extenddb ....................................................................................................................................... 41 export ........................................................................................................................................... 41 import-all ....................................................................................................................................... 41 import-custom ............................................................................................................................... 41 import-lcm ..................................................................................................................................... 42 import-stock .................................................................................................................................. 42 import (deprecated) ...................................................................................................................... 42 importcycle ................................................................................................................................... 42 importdynamic .............................................................................................................................. 43 importjava ..................................................................................................................................... 43 initial-build..................................................................................................................................... 43 patchdb......................................................................................................................................... 43 Services Standard Build User Guide Page 5 of 50 runSql ........................................................................................................................................... 43 runUpgrade................................................................................................................................... 44 up ................................................................................................................................................. 45 war ............................................................................................................................................... 45 Build Checks .................................................................................................................................... 45 Controlling Build Checks ............................................................................................................... 45 Available Build Checks ................................................................................................................. 45 Checks after SSB Build Expansion Phase................................................................................. 45 Checks after SSB Token Substitution Phase ............................................................................. 46 Project-Specific Build Checks ....................................................................................................... 47 Build Check Output ....................................................................................................................... 47 OWASP Dependency Check Vulnerability Detection ........................................................................ 48 The Dependency Check Utility ...................................................................................................... 48 Running the Dependency Check Utility ......................................................................................... 48 The suppressions.xml File ............................................................................................................ 49 Updating the Dependency Check Utility ........................................................................................ 49 Further Information on the Dependency Check Utility ................................................................... 50 Services Standard Build User Guide Page 6 of 50 Services Standard Build Overview A build process is critical to the smooth deployment to production of a configured IdentityIQ environment. A build process helps streamline the process of promoting an IdentityIQ installation’s configuration objects through the development, test and production environments so that all three contain the same custom objects like applications, rules, task definitions and identity mappings. It also allows for new custom objects and custom Java code to be integrated into IdentityIQ with a simple, manageable set of commands that can be easily automated. The Services Standard Build (SSB) is a set of artifacts developed by the SailPoint Services team to support the build process for IdentityIQ deployments. These tools were designed with the following goals in mind: • • • • • • Automate effort of generating deployments for various environments such as development, testing, UAT, and production. Reduce time frame for new team members to become familiar with project structure and customizations. Reduce likelihood of errors due to improper deployment of patches, efixes, and configurations. Accelerate the software development process with useful methods and tools that make configuring IdentityIQ more efficient. Enable the SailPoint support team to quickly replicate IdentityIQ environments. Provide a build structure that is familiar to J2EE and servlet application developers that appeals to a broad audience. The SSB tools should be configured directly after installing IdentityIQ in the first development environment for a project. The SSB is a subset of what is known as the Services Standard Deployment (SSD). The SSB can be downloaded as a standalone build tool, but downloading the SSD will incorporate all elements of the SSB with some additional artifacts to help with deployment, known as the Services Standard Frameworks (SSF), Services Standard Test (SST) and Services Standard Performance (SSP). Configuration and use of the larger SSD and these other components is available on Compass but is outside the scope of this document. SSB Components SSB scripts (build.xml, scripts/build.dev.xml, etc.) utilize Apache Ant 1.8.2, along with antcontrib 1.0b3 and catalina-ant (for Tomcat 7.x). Apache Ant This is the main build tool using XML documents as build instructions. You don’t have to do anything special to start using Ant when using the SSB – it’s bundled right along with the other SSB artifacts (in the lib/ant folder)! See the project page at: https://ant.apache.org/. There is a user guide for 1.9.x and 1.10.x – these are largely the same content that applies to the 1.8.x version used in SSB. Services Standard Build User Guide Page 7 of 50 Ant Contrib This has extensions for Ant and custom Ant tasks (likeblocks). See the project page for more information: https://sourceforge.net/projects/ant-contrib/files/ant-contrib/. Catalina-Ant If using Apache Tomcat, Ant has extensions to manage certain aspects of the servlet container generally this will only be used by those with more advanced SSB requirements. While this included jar is technically part of Tomcat 7, it should work with later versions of Tomcat. If there is any doubt, the catalina-ant.jar file can always be replaced with one for your version of Tomcat ( /lib). See the project page for more details if appropriate (Tomcat 8.0 example link): https://tomcat.apache.org/tomcat-8.0-doc/api/org/apache/catalina/ant/. Custom Ant Tasks There are also custom Ant task extensions created by SailPoint that are bundled with the SSB that support the build scripts. These are in servicestools/sailpoint/services/tools/ant and should not be modified (unless there is a specific reason to do so). For more information about custom Ant task development see: https://ant.apache.org/manual/develop.html. Services Standard Build User Guide Page 8 of 50 Process Overview Before beginning, please ensure you have the following: 1. Access to SailPoint’s Compass (community) website: https://community.sailpoint.com/ 2. Command-line access to your development and/or test servers. a. These are the servers where IdentityIQ’s servlet container (web application server) runs. b. This may be JBoss, Tomcat, WebSphere, or WebLogic, depending on the environment. c. Note that command line access to your production servers is only necessary if you will be installing IdentityIQ and migrating custom code to your production servers. 3. Ability to create a directory in the WEB-INF/bin folder of your Identity IQ installation directory on your development server. 4. Ability to stop and start your web application server (Tomcat, JBoss, WebLogic, WebSphere, etc.). 5. Ability to copy a directory from your development server to your test and/or production server. The steps you will perform to complete this process are as follows: 1. Download the Services Standard Build from Compass. 2. Export the custom objects from your development environment. a. If this is a new IdentityIQ installation, there won’t be any objects to export. 3. Set up the directory structure of the build. 4. Configure the build. 5. Run the build command. Services Standard Build User Guide Page 9 of 50 Downloading the Services Standard Build First, download the latest version of the standalone Services Standard Build or the full Services Standard Deployment from Compass. Download the zip file with the latest version and unzip it into a file directory accessible to the development environment. This will create the base build structure. Make note of the directory where you have un-zipped the services standard build files; this directory will be called the “SSB Install Directory” throughout the remainder of this guide, and you will return to it repeatedly throughout the build process. Folder Structure This is the high-level folder structure of the build. The top-level directories should not be modified, though objects will be placed into these folders, either directly or in subfolders, to be used in the build process. • base - Contains binaries distributed by SailPoint. You can download these from Compass. o efix - Contains any efix archives sorted by directory name where the directory name follows the naming convention . If there is no patch level it will just have the version number. Because efix solutions only work with the specific product version they were designed for, you must make a unique directory for each version and patch level you want to build against. If a properly named efix directory is not found, the build will generate one. Efix files in .jar and .zip formats are supported. Efixes will be expanded in order of the creation timestamp on the zip or jar file; files with an earlier Services Standard Build User Guide Page 10 of 50 o creation timestamp will be expanded first. In the case of filesystems that do not have creation timestamps (Unix/Linux), the last modified timestamp will be used to define the order of expansion. ga - Contains the SailPoint GA release binary. You can have as many GA release binaries as you want to build against and the appropriate one will be selected using the values you set in the build.properties file. Example: /base/ga/identityiq-7.1.zip o patch - Contains the SailPoint patch binaries. You can have as many patch binaries as you want to build against and the appropriate patch will be selected using the values you set in the build.properties file. Example: /base/patch/identityiq-7.1p1.jar • • • • config - Contains all your custom XML configuration objects sorted by folders where each sub directory is named by the type of top level SailPoint object it holds. In the provided example Application, Rule, TaskDefinition and TaskSchedule directories are shown. In general, as you customize more object types, you should add a directory to contain that object. While writing code, try to make the separation of object types as granular as possible such that it is easy to view all objects of a particular type. For example, instead of inserting a rule directly into a TaskDefinition, a reference to that rule should be created and the Rule itself would live in its own file in the Rule directory. The idea is to separate and encapsulate. o Note: While we recommend there just be objects in directories named for that object type (Application, Bundle, etc), there is nothing special about the directory names under the config directory. All files under config whose names end with a ‘.xml’ suffix will be transformed through the build and tokenization and prepared for import into IdentityIQ. Files with other kinds of name extensions (.txt, .old, etc.) under config are ignored by the build process. db - Contains customized database scripts. lib - Contains libraries used by the build process. It contains Java code the Ant build scripts use, but it does not get added to your installation of IdentityIQ. Do not put additional jars here. Put them in the web/WEB-INF/lib directory. scripts - Except for the master build.xml file in the root directory, all other build files are contained in this directory. Shipped and supported build files are read-only and follow the name convention build.*.xml. If you customize the build process you must declare your customizations in build files that follow the naming convention build.custom.*.xml. o Three example scripts are provided illustrate how to extend the build process with sitespecific custom scripts. ▪ scripts/example.build.custom.Extend-idAttrs.xml (Configure extended searchable Identity attributes using the ExtendedPropertyAccessor class) ▪ scripts/example.build.custom.Modify-WEB-XML.xml (Example of generic replacement of text in the web.xml file) ▪ scripts/example.build.custom.modify-web_xml_timeout.xml (Modify the timeout value in web.xml) o Custom Ant scripts can inject their own site-specific logic in one of three places: Services Standard Build User Guide Page 11 of 50 ▪ • • • The clean target, which allows the custom Ant script take whatever actions are necessary when resetting the builds to a clean or blank state. ▪ The post.expansion.hook target, which allows the custom Ant script to implement site-specific logic after the build has expanded the stock IdentityIQ war file into the build/extract directory. This is an opportunity to transform files or alter what will end up in the finished .war file. ▪ The post.war.hook target, which allows the custom script to take any action after the war file has been zipped together into a single file. This is commonly used for automated copying or deployment of the war file to a file server or repository. o The example scripts provide guidance in their comments for readers interested in using them as templates to create their own site-specific build script functionality. They will not execute during the build process unless their names are changed to the build.custom.*.xml format. o Readers interested in learning more about how Ant works are encouraged to review Apache Ant documentation: (http://ant.apache.org/manual/). servicestools - Contains the source code and an Ant project to build the services-tools.jar which is placed in the lib directory of the build. Code compiled and placed into the servicestools.jar is responsible for creating sp.init-custom.xml. Calling import sp.initcustom.xml from the iiq console is an additional way to push custom objects from your /config folder into your IdentityIQ database. src - Contains all your custom Java files. Note this Java will be compiled and placed in a jar file, which will be placed in the main IdentityIQ installation’s WEB-INF/lib directory. It will be named based on the customer property in build.properties. The jar will become identityiqCustomizations.customer.jar. You should NOT "clone and own" SailPointshipped classes in this area. Since they will be placed in the classpath at the same level as the shipped classes, you may get behavior you do not expect. If you absolutely must modify a core class, you will have to define a build.custom.*.xml file to handle layout of these files as you are effectively defining your own efix. By default, the SSB will not acknowledge with this practice; it is discouraged. web - Contains content that will be directly overlaid on the IdentityIQ folder structure. Examples include: custom graphics/branding, xhtml, jsp, custom message catalogs, and additional jar libraries. Under web you will need to create the folder structure for the location where these files are normally stored. For information on custom branding for your enterprise, go here: https://community.sailpoint.com/docs/DOC-7952. o Example: to include custom changes to the Hibernate XML configuration file for identity extended attributes, put your customized version of IdentityExtended.hbm.xml in this directory nested in the full directory path: web/WEBINF/classes/sailpoint/object/IdentityExtended.hbm.xml. Services Standard Build User Guide Page 12 of 50 Figure 1 - Example of using "web" in the SSB folder structure .keep Files There are .keep files in several areas of the SSB folder structure. These are to preserve an empty folder structure if git is used for source control (which is increasingly common). While SVN preserves empty folders upon a check-in, git does not. Thus, a .keep file is a common way to make an empty folder a trackable object in git. The .keep files are stripped out of build directory of the SSB project so they are not deployed to the web application server. If you are not using git, these placeholder files can be removed from the core folders, but leaving them does no harm. Exporting Custom Objects This section assumes that IdentityIQ has been successfully installed into a development environment and that object definitions (e.g., applications, rules) have been created. If IdentityIQ has not been installed in at least your development environment, please do this first. If there are no custom object definitions to export now, skip this step and add them to the build’s \config folder as they are created. No out of the box objects need to be added to your build directory; they are all added to the IdentityIQ database when running import init.xml, and if implementing the Lifecycle Manager functionality of IdentityIQ, import init-lcm.xml. However, if you change an out-of-the-box object (ObjectConfig-“Identity” is an example of a common out of the box object that changes when configuring identity mappings), this does need to be added to your build’s config folder. This will ensure those changes migrate from environment to environment. For further information on the object types that should be managed in your build, see the “Best Practices: Deployment, Migration, Upgrade, and Artifact Management” document on Compass here: https://community.sailpoint.com/docs/DOC-2264. Note that there are several ways to export XML objects to the filesystem. The SailPoint Services team now recommends using the Object Exporter task (available in the SSD or separately on Compass) and/or the IdentityIQ Deployment Accelerator (also on Compass). However, the information below covers the Export Script, an older method of exporting XML objects which is detailed here for reference. Services Standard Build User Guide Page 13 of 50 Running the Export Script The SSB includes an export script (called Export Script.txt), which tells IdentityIQ to export some of the most common object classes. It exports all objects of each object type into a separate file per object type. For example, one line of the export script is export -clean exports/CurrentApplicationExported.xml Application. This line exports all the Application objects into a file called CurrentApplicationExported.xml. These objects must be exported from the development environment and included in the build directory tree to be included in the build process. (Note: The -clean argument will tell the exporter to strip the object of all Hibernate-generated IDs. This is important for porting objects between environments) Use the iiq console command line utility to see the configuration objects your environment has by type: 1. Navigate to the WEB-INF\bin folder within your IdentityIQ installation directory from a command prompt. Enter the command iiq console once inside this directory. 2. Enter the command list to see all the object types or classes. 3. Enter list to see all the objects of that type in your environment. If your environment has configuration object types not covered in the object classes listed in the export script, edit the file to add more export commands, following the syntax of the provided lines: export -clean exports/CurrentObjectClassNameExported.xml Copy the ExportScript.txt from the directory you unzipped earlier. Paste this text file into the WEB-INF\bin folder of your IdentityIQ installation directory. Also, create a folder called exports in the WEB-INF\bin folder. Services Standard Build User Guide Page 14 of 50 Navigate back to the WEB-INF\bin folder within your IdentityIQ installation directory from a command prompt. Launch the console by entering the command iiq console. When you see the > prompt, enter the command source ExportScript.txt. This will run the export script and export all your environment’s configuration objects into the exports folder you just created. Many installations choose to split the export files into multiple files, storing each individual object in its own XML file. This practice is recommended, but not required. This makes it easier in the future to track exactly which objects have been changed between releases. Services Standard Build User Guide Page 15 of 50 There is a Perl script on Compass that will perform the object separation. It is located here: https://community.sailpoint.com/docs/DOC-2103. To split the objects up manually, copy an object’s entire definition into a separate file, wrapped in the following header, opening, and closing tags: Place each xml object into its respective class folder. The recommended naming convention for each of these object files is ObjectType-Name.xml. For example, CurrentApplicationExported.xml would be split into Application-ActiveDirectory.xml and Application-PeopleSoft.xml, etc. Services Standard Build User Guide Page 16 of 50 Build Structure Set-up Configuration Objects For the build process, all your environment’s configuration objects should be placed into the config directory. Inside of this config folder, create a folder for every object class you exported. Folders for some objects -- Application, LocalizedAttribute, Rule, TaskDefinition, and TaskSchedule already exist as examples. Place your exported xml files into their respective folders. For example, place the exported Application files into the \config\Application folder. IdentityIQ Product Files The build process will rebuild IdentityIQ for deployment into the target environment, merging the product zip files, patch jar files, and your custom artifacts. So next, you must put the desired product version zip files and patch jar files into the build directory tree. Copy the zip file for the IdentityIQ version you are using into the \base\ga folder. Zip files can be downloaded from Compass if needed. NOTE: Multiple IdentityIQ zip files can coexist in this directory; a variable in the build.properties file for each environment determines which .zip file the build process will use. If you are running a patched version of IdentityIQ, place the patch .jar file for your installation into the \base\patch folder. Again, multiple patch jar files can coexist in this directory and the build.properties file specifies which to use in the build (with the IIQPatchLevel variable). All patch .jar files can be downloaded from Compass as well. If you have any efixes for your current patch, be certain to copy those to an appropriate efix directory and remember to check them into your revision control system if you are using one on your project. Plugins The SailPoint Plugin Framework is an extension framework model for IdentityIQ which enables third parties to develop rich application and service-level enhancements to the core SailPoint platform. For supported versions of IdentityIQ (7.1 and higher), plugins may be added to the build so that they will be built and/or automatically installed or uninstalled. Build/Compilation of Plugins The SSB build process can build and compile plugins automatically from the plugin source code. This requires that the plugins are placed under the pluginsrc folder at the root of the SSB, under a subfolder named for each plugin. In addition, the components of the plugin must be located in specific subfolders as shown in the table below. Services Standard Build User Guide Page 17 of 50 Subfolder pluginsrc/ /db pluginsrc/ /import pluginsrc/ /lib pluginsrc/ /src pluginsrc/ /ui pluginsrc/ /manifest.xml Description Contains the database scripts for the plugin (within install, uninstall and upgrade subfolders) Contains the XML artifacts to be imported Contains any extra jar files that will ship with the plugin Contains the source code for the plugin (in package subfolders) Contains the UI elements of the plugin (such as images, CSS files, HTML templates, and JavaScript) Mandatory file that defines plugin parameters For more information on each of these components, please refer to the Plugin Developer Guide for IdentityIQ at https://community.sailpoint.com/docs/DOC-7562. Plugins configured correctly under the pluginsrc folder will be built and compiled by the SSB. When building plugins with the SSB there is no need for the separate build.xml or build.properties files described in the Developer Guide. Plugins will be built to the build/plugins folder when the main build is executed. The plugin zip file will be located in the build/plugins/ /dist folder. It will also be copied to the web/plugins/system/SSB/install folder in the IdentityIQ build for automatic deployment (see below). Automatic Deployment of Plugins Automatic deployment of plugins relies on the presence of a ServiceDefinition xml file to be imported with the build, and a Jar file which contains a service that manages plugin installation and removal. The files are in the following locations in the SSB: config/ServiceDefinition/SSB_PluginImporterService.xml web/WEB-INF/lib/ssb-plugin-importer.jar In addition, the deployPluginImporter property in the build.properties file must be set to true. If the plugin is not being compiled as part of the build process (see above) and you already have a plugin packaged in a zip archive file, you can automatically deploy it by placing the zip file in the correct location. If the plugin is being compiled by the build process, the zip file will automatically be created and deployed. To have IdentityIQ install a plugin, place the plugin archive in the web/plugins/system/SSB/install folder of your SSB build. The following points apply for installing plugins in this way: • • • Installation of any plugins in the install folder of the deployed build will be attempted on server start and thereafter once per day If the plugin is already installed it will not be reinstalled If the version of the plugin in the install folder is newer that the existing installed plugin it will be upgraded. Services Standard Build User Guide Page 18 of 50 To have IdentityIQ uninstall a plugin, place the plugin archive that matches the installed plugin version in the web/plugins/system/SSB/uninstall folder of your SSB build. The following points apply for uninstalling plugins in this way: • • • An attempt will be made to uninstall any plugins in the uninstall folder of the deployed build on server start and thereafter once per day If the plugin is not currently installed it will be ignored If the installed plugin is a different version than the plugin present in the uninstall folder the plugin will not be uninstalled. The frequency at which the install and uninstall folders are searched for plugins can be varied by modifying the number of seconds defined in the interval property of the PluginImporter ServiceDefinition object. JDBC Drivers A common practice with any IdentityIQ deployment is to update the JDBC driver used specific to your database management system. This can help to avoid issues with performance and with vulnerabilities associated with outdated versions of the driver. A guide on Compass outlines this procedure: https://community.sailpoint.com/docs/DOC-4111. Note when a JDBC driver is put in the SSB project folder area web/WEB-INF/lib, the developer should check to remove the out-of-the-box JDBC driver by having the older jar deleted at build. This will ensure that a deploy includes only the latest JDBC jar specific to your environment. First, get your updated JDBC driver and place it in the web/WEB-INF/lib area of the SSB project. For SQL Server, this might be sqljdbc42.jar. Run a build clean main target set and check the build/extract/WEB-INF/lib folder for legacy jar files for your database system. In this example, that may be sqljdbc4.jar (the default SQL Server driver that comes with IdentityIQ 7.0). Take note of the jar file (generally is only one) and adjust the main target in build.xml. Add a line to the main target (near top of target, there are a few of them already) like this: In this example sqljdbc4.jar was used – each installation may differ. This is one exception where modifying the default SSB build file makes sense – usually the default targets and build files should not be modified. Services Standard Build User Guide Page 19 of 50 Build Configuration Configuring the build.properties file The build.properties file is a crucial configuration file that specifies many important configuration arguments, like the version of IdentityIQ you are running, the Customer name, and the path to your IdentityIQ installation. Without this information, the build cannot run successfully. Now configure the build.properties file found in the . Use your favorite text editor to edit this file. Services Standard Build User Guide Page 20 of 50 Set properties in the build.properties as described in the table below. Variable Description Required? IIQVersion IIQPatchLevel IIQHome customer jdk.home runCustomScripts runCodeChecks codeCheck.namingConvention application.server.host application.server.port Services Standard Build User Guide Specify the base version of IdentityIQ that you are building, e.g. 6.0, 6.1, 6.2, 6.3, 6.4, 7.0, 7.1 If you want to deploy a patch version, specify what level with pX syntax, e.g. p1 or p6. If you are deploying only the GA version, leave this blank. The home directory of the IdentityIQ web application in your sandbox/development environment. When using the deploy build target, the IIQHome property tells the build where to deploy your custom IdentityIQ installation. The name of the client or project phase. The build will create a .jar file, compiling all .java code in the build’s src folder and name that jar identityIqCustomizations.C ustomer.jar. The path on your system to the Java Development Kit (jdk) you want to use to compile any custom Java code you may have developed as part of your IdentityIQ configuration. As with all system paths, if there are spaces in your jdk path, put the entire path in double quotes. In lieu of this, you can set the JAVA_HOME environment variable for your OS. (true/false) Generally, the default SSB build scripts are not meant to be modified directly. The main build has two hook points after file layout and after war creation where you can execute customized build scripts. This flag indicates if these customizations should be executed. If set to true, checks as defined in the Build Checks section of this document are performed. Defines a naming convention used by the checks described in the Build Checks section of this document. The IP address of your application server in your sandbox/development environment The port the application server is running on. For example, 8080 is the Tomcat default. Yes No, only if deploying a patch version No, only when using deploy target Yes No Yes, leave as false if unsure No No No, only when using cycle or importcycle build targets No, only when using cycle or importcycle build targets Page 21 of 50 application.server.start application.server.stop db.url db.userid db.password db.driver iiq.path db.type db.name Services Standard Build User Guide Script to start the application server. Since there are so many different application servers we leave it to you to write a script that starts and stops the server, sets up JVM parameters etc. Many application servers already ship with these but you can specify which ones you want to use here. This script (and the stop script below) is used in development targets that include steps to cycle the application server for you. Script to stop the application server. The JDBC URL to your local database. Database user with create and drop schema privileges (e.g. root on MySQL). NOTE: Supply this parameter only for low-risk, nonproduction environments (e.g. sandbox/development), as it is not designed for production environment use at this time. The password for the root DB user. Not supported as an IdentityIQencrypted string at this time. NOTE: Supply this parameter only for lowrisk, non-production environments (e.g. sandbox/development), as it is not designed for production environment use at this time. The class of the JDBC driver to use for SQL connections. This is the same value you would put in your iiq.properties file, as instructed in the IdentityIQ Installation Guide. The installation directory within the application server directory of the IdentityIQ application. Usually /iiq or /identityiq One of these values: db2, mysql, oracle, sqlserver; used to pick which database scripts to run Name of the IdentityIQ database No, only when using cycle, importcycle, up, or down targets No, only when using cycle, importcycle, up, or down targets No, only when using targets createdb, dropdb, extenddb, initial-build, etc. No, only when using targets createdb, dropdb, extenddb, initial-build, etc. No, only when using targets createdb, dropdb, extenddb, initial-build, etc. No, only when using targets createdb, dropdb, extenddb, initial-build, etc. Yes No, only when using targets createdb, dropdb, extenddb, initial-build, etc. No, only when using targets createdb, dropdb, extenddb, initial-build, etc. Page 22 of 50 db.userName Name of user account that will be created using the DB script db.userPassword Password of user account that will be created using the DB script. Not supported as an IdentityIQencrypted string at this time. NOTE: Supply this parameter only for lowrisk, non-production environments (e.g. sandbox/development), as it is not designed for production environment use at this time. SQL Server setting that defines whether Windows password policy should be checked when creating a login for SQL authentication. Default is off. SQL Server has an additional item created in the script for the Login name, which is separate from the user name. Specify that here. db.sqlserver.checkpolicy db.sqlserver.loginName plugin.db.sqlserver.loginName db.db2.databaseName db.db2.bufferpool db.db2.tableSpaceName db.oracle.createUser db.oracle.createTableSpace db.oracle.tableSpaceName db.oracle.tableSpacePath db.oracle.useFastDropScript installJavaMelody override.safety.prompts installDate manager.url Services Standard Build User Guide IdentityIQ 7.1 and SSB v4 added the plugin.db.sqlserver.loginN ame for the plugin DB. DB2 requires a separate database name and file/bufferpool for its scripts. Specify those values here. For the createdb/dropdb scripts for Oracle, we have the option to uncomment the lines that create the tablespace and user, as well as removing them. These variables need to be set to enable that. If using JavaMelody, set this to true to gather SQL statistics in Oracle Certain dangerous build targets like dropdb will prompt the user for confirmation before executing. If you are using the build to make test cases you may want to turn off these prompts. For the export target, the original install date string that we can use to determine new or changed objects. URL to the tomcat manager script interface; Prior to Tomcat Version 6 the URL is usually /manager but post Version 6 it is /manager/text. No, only when using targets createdb, dropdb, extenddb, initial-build, etc. No, only when using targets createdb, dropdb, extenddb, initial-build, etc. No, only when using targets createdb, dropdb, extenddb, initial-build, etc. No, only when using targets createdb, dropdb, extenddb, initial-build, etc. No, only when using targets createdb, dropdb, extenddb, initial-build, etc. No, only when using targets createdb, dropdb, extenddb, initial-build, etc. No, only when using targets createdb, dropdb, extenddb, initial-build, etc. Yes, leave as false if unsure No, only if using the export target Only if deploying using Tomcat application server Page 23 of 50 manager.login manager.pw tomcat.home usingLcm console_user console_pass updateLog4jLoggers usingDbSchemaExtensions Services Standard Build User Guide A user who has the managerscript role in the Tomcat manager application. For information on how to set this up check out: http://tomcat.apache.org/tomcat7.0-doc/managerhowto.html#Executing_Manager_C ommands_With_Ant The password for the above account. Set this to the value of CATALINA_HOME you want to use when starting and stopping Tomcat If your implementation includes Lifecycle Manager, you can ensure that it is included in your project build by setting the usingLcm property to true. This will insure that init- lcm.xml is imported if the target import-lcm is called directly or indirectly. Username used by importdynamic (and other targets utilizing import functionality) to access the console. Encrypted password used by importdynamic (and other targets utilizing import functionality) to access the console. If set to true, the log4j.properties file in WEBINF/classes will be updated during the build process with a line for every logger that is found in BeanShell code in the XML files or in custom Java source code. These lines will be commented out. This helps during troubleshooting when a logger needs to be enabled but the name of the logger is not known without looking it up in the code. To enable a logger the appropriate line just needs to be uncommented in log4j.properties and set to the required log level before refreshing the logging configuration in IdentityIQ. This switch enables the extenddb target to be run. It would be enabled (true) if IdentityExtended.hbm.xml (or Only if deploying using Tomcat application server Only if deploying using Tomcat application server Only if deploying using Tomcat application server Yes See section: Non-default spadmin password and importing artifacts See section: Non-default spadmin password and importing artifacts No Only if you plan to use the extenddb or initial-build targets Page 24 of 50 plugin.db.name plugin.db.userName plugin.db.userPassword deployPluginImporter similar object hbm.xml) was customized with named columns and placed in web/WEBINF/classes/sailpoint AND ObjectConfig for a matching object was customized. Default is false. These mirror the “normal” db.name and similar settings. These were introduced in SSB v4 to handle the IdentityIQ 7.1 plugin DB. The password is not supported as an IIQ-encrypted string at this time. NOTE: Supply these parameters only for low-risk, non-production environments (e.g. sandbox/development), as they are not designed for production environment use at this time. If set to true and the version of IdentityIQ being deployed is 7.1 or higher, the PluginImporter ServiceDefinition object will be deployed, enabling plugins to be automatically installed from the filesystem. No, only when using targets createdb, dropdb, extenddb, initial-build, etc. No Note that there are also some other variables in the build.properties file that start with deploy, such as deploySSF, deployGenericImporter and deployObjectExporter. These are only used in the full SSD to define which of the SSD components and tools should be deployed in the build. In the standalone SSB they are not used. Supporting multiple platforms (Windows/Linux/Unix) for different environments If your installation uses different operating systems for different stages of IdentityIQ development – for example, Windows for sandboxes and Linux for Test and Production servers – you must configure multiple build.properties files. The generic build.properties file described above loads the defaults for the build with respect to the path to Java binaries, IdentityIQ version and other details. These can be overridden on a per-server or per-environment basis by specifying another properties file with properties that just apply to one server or one environment. Each server or environment used in development and testing can override the settings in build.properties by using its own .build.properties or .build.properties file. For example, if your host is named sailsandbox then the properties file unique to that server would be called sailsandbox.build.properties. Or if your environment (SPTARGET) is called dev you could have dev.build.properties. The server or environment’s properties file has exactly the same format and fields as the build.properties file described in the previous section and only has to specify the fields that it wants to override with values that are different from the default build.properties file’s values. If you are running a build on a Services Standard Build User Guide Page 25 of 50 server that has its own server-specific version of build.properties for an environment that has its own environment-specific version, the server-specific values override the environment-specific values, which in turn override the generic build.properties file. If you have servers or environments with identical build.properties, do not create server-specific or environment-specific files. Put those values in build.properties. The build will recognize that there is no file specific to the server or environment, and will use build.properties as the default. Note: Prior to version 4 of the SSB build.properties. or build.properties. were supported. Note those naming conventions, while still supported, have been deprecated and may be removed in a future release of the SSB. This has been done to further standardize the naming convention of various SSB host- and environment-specific artifacts. This also means the .properties extension is recognized by various properties-aware editors. Non-default spadmin password and importing artifacts The default spadmin username and encrypted password are set using the console_user and console_pass properties in build.properties. # Username and encrypted password used by importdynamic to access the console. # This can be removed, in which case the user will be prompted for credentials. console_user=spadmin console_pass=1:p+qvPBo4Rig8PYlNWbr3Zg== These can be used to inject credentials when targets using console iiqBeans are employed. This may involve several targets like: import-custom, import-stock, import-lcm, import-all, importdynamic, deploy, importcycle, etc. Use the console command iiq encrypt to get the encrypted value of your password to use here. Alternatively, the console_user and console_pass lines can be removed from build.properties, which will force the user to enter them each time importdynamic (or a similar target using import functionality) is run. Setting up environment-specific properties files The goal of the build process is to create a uniform Identity IQ distribution process for all environments (development, test, and production), but each environment will need many different parameters that are specific to that environment, such as login usernames, IP addresses, passwords, database connection strings etc. It is important that the build process can perform substitution of these values for each environment, as well as ensuring connection to the right IdentityIQ database and, where necessary, including or excluding files from an environment-specific build. Configuring iiq.properties files The iiq.properties file contains properties used by IdentityIQ for connecting to and interacting with its own database. Your build environment can specify different iiq.properties files for the build to use for deploying to each target environment. Create separate .iiq.properties files Services Standard Build User Guide Page 26 of 50 for each environment by copying and editing the product iiq.properties, and place them in the build directory (wherever you unzipped the SSB). 1. 2. 3. 4. Download the product image Expand the idenitityiq- .zip Expand the identityiq.war Copy the iiq.properties to the SSB .iiq.properties file. a. For example Copy WEB-INF/classes/iiq.properties to sandbox.iiq.properties For example, if your environments are sandbox, test, UAT and prod, you would have four files each containing the iiq.properties that know how to connect to the database server in that environment. This way you can support different properties for different environments, such as having a direct connection in sandbox and test while having a JNDI named connection in UAT and production. When creating these .iiq.properties files, use the iiq.properties file that ships with your IdentityIQ version’s .zip file and edit as appropriate for the environment. Example file names: sandbox.iiq.properties test.iiq.properties UAT.iiq.properties prod.iiq.properties Example test.iiq.properties file (yours may differ due to IdentityIQ version changes): ##### iiq.properties ##### # # (c) Copyright 2008 SailPoint Technologies, Inc., All Rights Reserved. # # This file contains configuration settings for IdentityIQ. For your unique # environment, you will need to adjust the username and password properties on # the dataSource below and uncomment the applicable database settings. # ##### Data Source Properties ##### dataSource.maxWait=10000 dataSource.maxActive=50 dataSource.minIdle=5 #dataSource.minEvictableIdleTimeMillis=300000 #dataSource.maxOpenPreparedStatements=-1 dataSource.username=root dataSource.password=root ##### MySQL 5 ##### ## URL Format: dataSource.url=jdbc:mysql:// : / ?useServerPrepStmts=true&tin yInt1isBit=true&useUnicode=true&characterEncoding=utf8 dataSource.url=jdbc:mysql://localhost/identityiq?useServerPrepStmts=true&tinyInt1is Bit=true&useUnicode=true&characterEncoding=utf8 dataSource.driverClassName=com.mysql.jdbc.Driver sessionFactory.hibernateProperties.hibernate.dialect=org.hibernate.dialect.MySQL5In noDBDialect Services Standard Build User Guide Page 27 of 50 # # Setting for the BSFManagerPool set on the ruleRunner # bsfManagerFactory.maxManagerReuse=100 bsfManagerPool.maxActive=30 bsfManagerPool.minEvictableIdleTimeMillis=900000 bsfManagerPool.timeBetweenEvictionRunsMillis=600000 ##### Debug Settings ##### # Uncomment to send all SQL queries to std out. This provides a lot of output # and slows down execution, so use it wisely. #sessionFactory.hibernateProperties.hibernate.show_sql=true # Hibernate Transaction Isolation Levels # 1 = Read Uncommitted, 2 = Read Committed, 4 = Repeatable Read, 8 = Serializable #sessionFactory.hibernateProperties.hibernate.connection.isolation=1 Configuring target.properties files It is important to configure environment-specific properties files that the SSB can use to do token string replacements in the objects during the build process. The SSB will automatically look for tokenized strings in your custom configuration XML and substitute the appropriate values per environment. A target.properties file should be created for each environment, containing key/value pairs for token substitution during build time. The name of each target.properties file should be in the format .target.properties. Examples: sandbox.target.properties test.target.properties UAT.target.properties prod.target.properties Each file is just a list of key/value pairs. The build’s convention is that the keys follow a %%KEYNAME%% pattern. For example, you may have an Active Directory application configuration that looks like this:
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.7 Linearized : No Page Count : 50 Language : en-US Tagged PDF : Yes XMP Toolkit : 3.1-701 Producer : Microsoft® Word 2016 Creator Tool : Microsoft® Word 2016 Create Date : 2018:07:25 17:03:58+00:00 Modify Date : 2018:07:25 17:03:58+00:00 Document ID : uuid:B1FC6E7D-95A9-41DE-A4E4-67A88D75E0F2 Instance ID : uuid:B1FC6E7D-95A9-41DE-A4E4-67A88D75E0F2 Creator : Microsoft® Word 2016EXIF Metadata provided by EXIF.tools