Transcription
Integrator's GuideOpenIDM 3Anders AskåsenPaul BryanMark CraigAndi EgloffLaszlo HordosMatthias TristlLana FrostMike JangDaly ChikhaouiForgeRock AS201 Mission St., Suite 2900San Francisco, CA 94105, USA 1 415-599-1100 (US)www.forgerock.com
Copyright 2011-2017 ForgeRock AS.AbstractGuide to configuring and integrating OpenIDM into identity management solutions. TheOpenIDM project offers flexible, open source services for automating management of theidentity life cycle.This work is licensed under the Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License.To view a copy of this license, visit https://creativecommons.org/licenses/by-nc-nd/3.0/ or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.ForgeRock and ForgeRock Identity Platform are trademarks of ForgeRock Inc. or its subsidiaries in the U.S. and in other countries. Trademarks are the property of their respective owners.UNLESS OTHERWISE MUTUALLY AGREED BY THE PARTIES IN WRITING, LICENSOR OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE WORK, EXPRESS,IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENTOR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCHEXCLUSION MAY NOT APPLY TO YOU.EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARYDAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.DejaVu FontsBitstream Vera Fonts CopyrightCopyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera is a trademark of Bitstream, Inc.Permission is hereby granted, free of charge, to any person obtaining a copy of the fonts accompanying this license ("Fonts") and associated documentation files (the "Font Software"), to reproduce and distribute the FontSoftware, including without limitation the rights to use, copy, merge, publish, distribute, and/or sell copies of the Font Software, and to permit persons to whom the Font Software is furnished to do so, subject to the followingconditions:The above copyright and trademark notices and this permission notice shall be included in all copies of one or more of the Font Software typefaces.The Font Software may be modified, altered, or added to, and in particular the designs of glyphs or characters in the Fonts may be modified and additional glyphs or characters may be added to the Fonts, only if the fonts arerenamed to names not containing either the words "Bitstream" or the word "Vera".This License becomes null and void to the extent applicable to Fonts or Font Software that has been modified and is distributed under the "Bitstream Vera" names.The Font Software may be sold as part of a larger software package but no copy of one or more of the Font Software typefaces may be sold by itself.THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULARPURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE ORINABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.Except as contained in this notice, the names of Gnome, the Gnome Foundation, and Bitstream Inc., shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Font Software without priorwritten authorization from the Gnome Foundation or Bitstream Inc., respectively. For further information, contact: fonts at gnome dot org.Arev Fonts CopyrightCopyright (c) 2006 by Tavmjong Bah. All Rights Reserved.Permission is hereby granted, free of charge, to any person obtaining a copy of the fonts accompanying this license ("Fonts") and associated documentation files (the "Font Software"), to reproduce and distribute the modificationsto the Bitstream Vera Font Software, including without limitation the rights to use, copy, merge, publish, distribute, and/or sell copies of the Font Software, and to permit persons to whom the Font Software is furnished to do so,subject to the following conditions:The above copyright and trademark notices and this permission notice shall be included in all copies of one or more of the Font Software typefaces.The Font Software may be modified, altered, or added to, and in particular the designs of glyphs or characters in the Fonts may be modified and additional glyphs or characters may be added to the Fonts, only if the fonts arerenamed to names not containing either the words "Tavmjong Bah" or the word "Arev".This License becomes null and void to the extent applicable to Fonts or Font Software that has been modified and is distributed under the "Tavmjong Bah Arev" names.The Font Software may be sold as part of a larger software package but no copy of one or more of the Font Software typefaces may be sold by itself.THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULARPURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL TAVMJONG BAH BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANYGENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR INABILITY TO USE THE FONTSOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.Except as contained in this notice, the name of Tavmjong Bah shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Font Software without prior written authorization from Tavmjong Bah.For further information, contact: tavmjong @ free . fr.FontAwesome CopyrightCopyright (c) 2017 by Dave Gandy, http://fontawesome.io.This Font Software is licensed under the SIL Open Font License, Version 1.1. This license is available with a FAQ at: http://scripts.sil.org/OFL
Table of ContentsPreface . vii1. Who Should Use this Guide . vii2. Formatting Conventions . vii3. Accessing Documentation Online . viii4. Using the ForgeRock.org Site . viii1. Architectural Overview . 11.1. OpenIDM Modular Framework . 21.2. Infrastructure Modules . 21.3. Core Services . 31.4. Secure Commons REST Commands . 41.5. Access Layer . 52. Starting and Stopping OpenIDM . 62.1. To Start and Stop OpenIDM . 62.2. Specifying the OpenIDM Startup Configuration . 72.3. Obtaining Information About an OpenIDM Instance . 92.4. Verifying the Health of an OpenIDM System . 112.5. Displaying Information About Installed Modules . 132.6. Starting OpenIDM in Debug Mode . 153. OpenIDM Command-Line Interface . 173.1. configexport . 183.2. configimport . 193.3. configureconnector . 203.4. encrypt . 213.5. keytool . 233.6. validate . 244. OpenIDM User Interface . 254.1. Overview of the Default User Interface . 254.2. Configuring the Default User Interface . 274.3. Managing User Accounts With the User Interface . 324.4. Managing Workflows From the User Interface . 354.5. Changing the UI Theme . 364.6. Using an External System for Password Reset . 394.7. Providing a Logout URL to External Applications . 394.8. Changing the UI Path . 394.9. Disabling the UI . 405. Configuring OpenIDM . 415.1. OpenIDM Configuration Objects . 415.2. Changing the Default Configuration . 425.3. Configuring an OpenIDM System for Production . 435.4. Configuring OpenIDM Over REST . 435.5. Using Property Value Substitution in the Configuration . 485.6. Adding Custom Endpoints . 505.7. Default and Custom Configuration Directories . 566. Accessing Data Objects . 58Integrator's Guide OpenIDM 3 (2018-01-24T14:53:44.257)Copyright 2011-2017 ForgeRock AS. All rights reserved.iii
6.1. Accessing Data Objects by Using Scripts . 586.2. Accessing Data Objects by Using the REST API . 596.3. Defining and Calling Queries . 597. Managing Users, Groups, and Roles . 647.1. Working with Managed Users . 647.2. Working With Managed Groups . 647.3. Configuring Custom Roles . 658. Using Policies to Validate Data . 818.1. Configuring the Default Policy . 818.2. Extending the Policy Service . 858.3. Disabling Policy Enforcement . 868.4. Managing Policies Over REST . 879. Configuring Server Logs . 9110. Connecting to External Resources . 9210.1. About OpenIDM and OpenICF . 9210.2. Accessing Remote Connectors . 9310.3. Configuring Connectors . 9510.4. Installing and Configuring Remote Connector Servers . 10310.5. Connectors Supported With OpenIDM 3.0.0 . 11210.6. Creating Default Connector Configurations . 13310.7. Checking the Status of External Systems Over REST . 13710.8. Adding Attributes to Connectors . 14011. Configuring Synchronization . 14211.1. Types of Synchronization . 14211.2. Flexible Data Model . 14511.3. Basic Data Flow Configuration . 14611.4. Managing Reconciliation Over REST . 15411.5. Restricting Reconciliation by Using Queries . 16111.6. Restricting Reconciliation to a Specific ID . 16311.7. Querying the Reconciliation Audit Log . 16411.8. Configuring the LiveSync Retry Policy . 17511.9. Synchronization Situations and Actions . 17811.10. Asynchronous Reconciliation . 18711.11. Configuring Case Sensitivity for Data Stores . 18811.12. Reconciliation Optimization . 18911.13. Correlation Queries . 19111.14. Advanced Data Flow Configuration . 19211.15. Scheduling Synchronization . 19512. Scheduling Tasks and Events . 19812.1. Scheduler Configuration . 19812.2. Configuring Persistent Schedules . 20212.3. Schedule Examples . 20312.4. Managing Schedules Over REST . 20412.5. Scanning Data to Trigger Tasks . 20813. Managing Passwords . 21413.1. Enforcing Password Policy . 21413.2. Password Synchronization . 219Integrator's Guide OpenIDM 3 (2018-01-24T14:53:44.257)Copyright 2011-2017 ForgeRock AS. All rights reserved.iv
14. Managing Authentication, Authorization and Role-Based Access Control .14.1. OpenIDM Users .14.2. Authentication .14.3. Using Delegated Authentication .14.4. Supported Authentication Modules .14.5. Roles and Authentication .14.6. Authorization .14.7. Building Role-Based Access Control (RBAC) .15. Securing & Hardening OpenIDM .15.1. Accessing the Security Management Service .15.2. Security Precautions for a Production Environment .16. Integrating Business Processes and Workflows .16.1. BPMN 2.0 and the Activiti Tools .16.2. Setting Up Activiti Integration With OpenIDM .16.3. Using Custom Templates for Activiti Workflows .16.4. Managing Workflows Over the REST Interface .16.5. Example Activiti Workflows With OpenIDM .16.6. Workflow Use Cases .17. Using Audit Logs .17.1. Audit Log Types .17.2. Audit Log File Formats .17.3. Audit Configuration .17.4. Generating Reports .18. Configuring OpenIDM to Work in a Cluster .18.1. Configuring an OpenIDM Instance as Part of a Cluster .18.2. Managing Scheduled Tasks Across a Cluster .18.3. Managing Nodes Over REST .19. Sending Email .19.1. Sending Mail Over REST .19.2. Sending Mail From a Script .20. Accessing External REST Services .20.1. Invocation Parameters .20.2. Support for Non-JSON Responses .21. OpenIDM Project Best Practices .21.1. Implementation Phases .22. Troubleshooting .22.1. OpenIDM Stopped in Background .22.2. Internal Server Error During Reconciliation or Synchronization .22.3. The scr list Command Shows Sync Service As Unsatisfied .22.4. JSON Parsing Error .22.5. System Not Available .22.6. Bad Connector Host Reference in Provisioner Configuration .22.7. Missing Name Attribute .23. Advanced Configuration .23.1. Advanced Startup Configuration .A. File Layout .B. Ports Used .Integrator's Guide OpenIDM 3 (2018-01-24T14:53:44.257)Copyright 2011-2017 ForgeRock AS. All rights v
C. Data Models and Objects Reference .C.1. Managed Objects .C.2. Configuration Objects .C.3. System Objects .C.4. Audit Objects .C.5. Links .D. Synchronization Reference .D.1. Object-Mapping Objects .D.2. Links .D.3. Queries .D.4. Reconciliation .D.5. REST API .E. REST API Reference .E.1. URI Scheme .E.2. Object Identifiers .E.3. Content Negotiation .E.4. Supported Operations .E.5. Conditional Operations .E.6. Supported Methods .E.7. REST Endpoints and Sample Commands .E.8. HTTP Status Codes .F. Scripting Reference .F.1. Scripting Configuration .F.2. Examples .F.3. Function Reference .F.4. Places to Trigger Scripts .F.5. Variables Available in Scripts .F.6. Debugging OpenIDM JavaScripts .G. Router Service Reference .G.1. Configuration .G.2. Example .H. Embedded Jetty Configuration .H.1. Using OpenIDM Configuration Properties in the Jetty Configuration .H.2. Jetty Default Settings .H.3. Registering Additional Servlet Filters .I. Release Levels & Interface Stability .I.1. ForgeRock Product Release Levels .I.2. ForgeRock Product Interface Stability .OpenIDM Glossary .Index .Integrator's Guide OpenIDM 3 (2018-01-24T14:53:44.257)Copyright 2011-2017 ForgeRock AS. All rights 18419419421421424424425426428vi
PrefaceThis guide shows you how to integrate OpenIDM as part of a complete identity management solution.1. Who Should Use this GuideThis guide is written for systems integrators building identity management solutions based onOpenIDM services. This guide describes OpenIDM, and shows you how to set up OpenIDM as part ofyour identity management solution.You do not need to be an OpenIDM wizard to learn something from this guide, though a backgroundin identity management and building identity management solutions can help.2. Formatting ConventionsMost examples in the documentation are created in GNU/Linux or Mac OS X operating environments.If distinctions are necessary between operating environments, examples are labeled with theoperating environment name in parentheses. To avoid repetition file system directory names areoften given only in UNIX format as in /path/to/server, even if the text applies to C:\path\to\server aswell.Absolute path names usually begin with the placeholder /path/to/. This path might translate to /opt/,C:\Program Files\, or somewhere else on your system.Command-line, terminal sessions are formatted as follows: echo JAVA HOME/path/to/jdkCommand output is sometimes formatted for narrower, more readable output even though formattingparameters are not shown in the command.Program listings are formatted as follows:class Test {public static void main(String [] args) {System.out.println("This is a program listing.");}}Integrator's Guide OpenIDM 3 (2018-01-24T14:53:44.257)Copyright 2011-2017 ForgeRock AS. All rights reserved.vii
3. Accessing Documentation OnlineForgeRock publishes comprehensive documentation online: The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practicalarticles that help you deploy and manage ForgeRock software.While many articles are visible to community members, ForgeRock customers have access to muchmore, including advanced information for customers using ForgeRock software in a mission-criticalcapacity. ForgeRock product documentation, such as this document, aims to be technically accurate andcomplete with respect to the software documented. It is visible to everyone and covers all productfeatures and examples of how to use them.4. Using the ForgeRock.org SiteThe ForgeRock.org site has links to source code for ForgeRock open source software, as well as linksto the ForgeRock forums and technical blogs.If you are a ForgeRock customer, raise a support ticket instead of using the forums. ForgeRocksupport professionals will get in touch to help you.Integrator's Guide OpenIDM 3 (2018-01-24T14:53:44.257)Copyright 2011-2017 ForgeRock AS. All rights reserved.viii
Architectural OverviewChapter 1Architectural OverviewThe following figure provides an overview of the OpenIDM architecture, which is covered in moredetail in subsequent sections of this chapter.Integrator's Guide OpenIDM 3 (2018-01-24T14:53:44.257)Copyright 2011-2017 ForgeRock AS. All rights reserved.1
Architectural OverviewOpenIDM Modular Framework1.1. OpenIDM Modular FrameworkThe OpenIDM framework is based on OSGi.OSGiOSGi is a module system and service platform for the Java programming language thatimplements a complete and dynamic component model. For a good introduction, see the OSGisite. While OpenIDM services are designed to run in any OSGi container, OpenIDM currently runsin Apache Felix.ServletThe optional Servlet layer provides RESTful HTTP access to the managed objects and services.While the Servlet layer can be provided by many different engines, OpenIDM embeds Jetty bydefault.1.2. Infrastructure ModulesOpenIDM infrastructure modules provide the underlying features needed for core services.BPMN 2.0 Workflow EngineOpenIDM
Integrator's Guide OpenIDM 3 Anders Askåsen Paul Bryan Mark Craig Andi Egloff Laszlo Hordos Matthias Tristl Lana Frost Mike Jang Daly Chikhaoui ForgeRock AS 201 Mission St., Suite 2900 San Francisco, CA 94105, USA 1 415-599-1100 (US) www.forgerock.com
