NetIQ JDBC Fan-Out Identity Manager driver Implementation Guide

NetIQ Identity Manager
Driver for JDBC Fan-Out Implementation Guide
March 2016
www.netiq.com/documentation
Legal Notice
NetIQ Product Name is protected by United States Patent No(s): nnnnnnnn, nnnnnnnn, nnnnnnnn.
THIS DOCUMENT AND THE SOFTWARE DESCRIBED IN THIS DOCUMENT ARE FURNISHED UNDER AND ARE
SUBJECT TO THE TERMS OF A LICENSE AGREEMENT OR A NON-DISCLOSURE AGREEMENT. EXCEPT AS
EXPRESSLY SET FORTH IN SUCH LICENSE AGREEMENT OR NON-DISCLOSURE AGREEMENT, NETIQ
CORPORATION PROVIDES THIS DOCUMENT AND THE SOFTWARE DESCRIBED IN THIS DOCUMENT "AS IS"
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. SOME STATES DO NOT
ALLOW DISCLAIMERS OF EXPRESS OR IMPLIED WARRANTIES IN CERTAIN TRANSACTIONS; THEREFORE, THIS
STATEMENT MAY NOT APPLY TO YOU.
For purposes of clarity, any module, adapter or other similar material ("Module") is licensed under the terms and conditions of
the End User License Agreement for the applicable version of the NetIQ product or software to which it relates or interoperates
with, and by accessing, copying or using a Module you agree to be bound by such terms. If you do not agree to the terms of
the End User License Agreement you are not authorized to use, access or copy a Module and you must destroy all copies of
the Module and contact NetIQ for further instructions.
This document and the software described in this document may not be lent, sold, or given away without the prior written
permission of NetIQ Corporation, except as otherwise permitted by law. Except as expressly set forth in such license
agreement or non-disclosure agreement, no part of this document or the software described in this document may be
reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, or otherwise,
without the prior written consent of NetIQ Corporation. Some companies, names, and data in this document are used for
illustration purposes and may not represent real companies, individuals, or data.
This document could include technical inaccuracies or typographical errors. Changes are periodically made to the information
herein. These changes may be incorporated in new editions of this document. NetIQ Corporation may make improvements in
or changes to the software described in this document at any time.
U.S. Government Restricted Rights: If the software and documentation are being acquired by or on behalf of the U.S.
Government or by a U.S. Government prime contractor or subcontractor (at any tier), in accordance with 48 C.F.R. 227.72024 (for Department of Defense (DOD) acquisitions) and 48 C.F.R. 2.101 and 12.212 (for non-DOD acquisitions), the
government’s rights in the software and documentation, including its rights to use, modify, reproduce, release, perform, display
or disclose the software or documentation, will be subject in all respects to the commercial license rights and restrictions
provided in the license agreement.
© 2016 NetIQ Corporation. All Rights Reserved.
For information about NetIQ trademarks, see https://www.netiq.com/company/legal/.
Contents
About NetIQ Corporation
About This Guide
About this Book and the Library
5
7
9
1 Overview
1.1
1.2
1.3
1.4
1.5
1.6
1.7
1.8
11
Components for Fan-Out Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Data Transfer Between Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Supported Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.3.1
Password Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.3.2
Data Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Installing and Configuring the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Supported Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Supported Third-Party JDBC Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Driver Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Database Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2 Installing the Fan-Out Driver Components
2.1
2.2
2.3
2.4
2.5
2.6
17
Prerequisites for Installing the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Updating the Identity Manager Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Adding the Fan-Out Driver Files to the Identity Vault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Installing ActiveMQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Setting Up ActiveMQ Startup Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.5.1
Enabling the ActiveMQ Service on Linux. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.5.2
Enabling the ActiveMQ Service on Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Installing the Fan-Out Agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3 Configuring the Fan-Out Agent
3.1
3.2
3.3
3.4
21
Generating the Default Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Starting the Fan-Out Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Managing the Fan-Out Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Enabling Auditing for the Fan-Out Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4 Creating New Fan-Out Driver
4.1
4.2
27
Creating a Fan-Out Driver Object in Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.1.1
Importing the Driver Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.1.2
Installing the Driver Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.1.3
Configuring the Driver Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.1.4
Configuring the Database Connections for the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.1.5
Deploying the Driver Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.1.6
Starting the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.1.7
Managing the Connection Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Activating the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Contents
3
5 Securing Fan-Out Driver Communication
5.1
5.2
5.3
5.4
Creating a Keystore and a Truststore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Enabling SSL for ActiveMQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Enabling SSL for the Fan-Out Driver Shim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Enabling SSL for the Fan-Out Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
6 Troubleshooting the Driver
6.1
6.2
6.3
6.4
6.5
6.6
39
Mismatch in Driver Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Fan-Out Driver and the Fan-Out Agent Time Out When ActiveMQ and Fan-Out Agent are
Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
ActiveMQ May Display Exception Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Cannot Run Two Instances of the Fan-Out Agent Using the Same Queue Names. . . . . . . . . . . . . . 39
Unable to Update the Parameters Using the setConfig Command . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Troubleshooting Driver Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
7 Managing the Driver
41
A Known Issues and Limitations
43
A.1
A.2
Known Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
B Driver Properties
B.1
B.2
45
Driver Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
B.1.1
Driver Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
B.1.2
Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
B.1.3
Startup Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
B.1.4
Driver Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
B.1.5
ECMA Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
B.1.6
Global Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Global Configuration Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
B.2.1
Global Configuration Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
B.2.2
Managed System Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
B.2.3
Entitlements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
B.2.4
Account Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
B.2.5
Password Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
B.2.6
JDBC Fan-Out Common . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
C REST Endpoints
4
35
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
55
About NetIQ Corporation
We are a global, enterprise software company, with a focus on the three persistent challenges in your
environment: Change, complexity and risk—and how we can help you control them.
Our Viewpoint
Adapting to change and managing complexity and risk are nothing new
In fact, of all the challenges you face, these are perhaps the most prominent variables that deny
you the control you need to securely measure, monitor, and manage your physical, virtual, and
cloud computing environments.
Enabling critical business services, better and faster
We believe that providing as much control as possible to IT organizations is the only way to
enable timelier and cost effective delivery of services. Persistent pressures like change and
complexity will only continue to increase as organizations continue to change and the
technologies needed to manage them become inherently more complex.
Our Philosophy
Selling intelligent solutions, not just software
In order to provide reliable control, we first make sure we understand the real-world scenarios in
which IT organizations like yours operate — day in and day out. That's the only way we can
develop practical, intelligent IT solutions that successfully yield proven, measurable results. And
that's so much more rewarding than simply selling software.
Driving your success is our passion
We place your success at the heart of how we do business. From product inception to
deployment, we understand that you need IT solutions that work well and integrate seamlessly
with your existing investments; you need ongoing support and training post-deployment; and you
need someone that is truly easy to work with — for a change. Ultimately, when you succeed, we
all succeed.
Our Solutions
Š Identity & Access Governance
Š Access Management
Š Security Management
Š Systems & Application Management
Š Workload Management
Š Service Management
About NetIQ Corporation
5
Contacting Sales Support
For questions about products, pricing, and capabilities, contact your local partner. If you cannot
contact your partner, contact our Sales Support team.
Worldwide:
www.netiq.com/about_netiq/officelocations.asp
United States and Canada:
1-888-323-6768
Email:
[email protected]
Web Site:
www.netiq.com
Contacting Technical Support
For specific product issues, contact our Technical Support team.
Worldwide:
www.netiq.com/support/contactinfo.asp
North and South America:
1-713-418-5555
Europe, Middle East, and Africa:
+353 (0) 91-782 677
Email:
[email protected]
Web Site:
www.netiq.com/support
Contacting Documentation Support
Our goal is to provide documentation that meets your needs. The documentation for this product is
available on the NetIQ web site in HTML and PDF formats on a page that does not require you to log
in. If you have suggestions for documentation improvements, click comment on this topic at the
bottom of any page in the HTML version of the documentation posted at www.netiq.com/
documentation. You can also email [email protected]. We value your input and
look forward to hearing from you.
Contacting the Online User Community
NetIQ Communities, the NetIQ online community, is a collaborative network connecting you to your
peers and NetIQ experts. By providing more immediate information, useful links to helpful resources,
and access to NetIQ experts, NetIQ Communities helps ensure you are mastering the knowledge you
need to realize the full potential of IT investments upon which you rely. For more information, visit
http://community.netiq.com.
6
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
About This Guide
This guide explains how to install and configure the Identity Manager JDBC Fan-Out Driver. The
guide includes the following information:
Audience
This guide is intended for administrators implementing Identity Manager, application server
developers, Web services administrators, and consultants. You should also have an understanding of
DSML/SPML, and HTML.
Feedback
We want to hear your comments and suggestions about this manual and the other documentation
included with this product. Please use the User Comments feature at the bottom of each page of the
online documentation, or go to www.novell.com/documentation/feedback.html and enter your
comments there.
Documentation Updates
For the most recent version of this document, see the Identity Manager Drivers Documentation Web
site (http://www.netiq.com/documentation/idm45drivers/index.html).
Additional Documentation
For information on Identity Manager, see the Identity Manager Documentation Web site (http://
www.netiq.com/documentation/idm45drivers).
About This Guide
7
8
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
About this Book and the Library
The Identity Manager Java Database Connectivity (JDBC) Fan-Out Driver for Implementation Guide
provides a generic solution for synchronizing data between an Identity Vault and multiple databases.
This guide provides an overview of the driver’s technology as well as configuration instructions.
Intended Audience
This book provides information for individuals responsible for understanding administration concepts
and implementing a secure, distributed administration model.
Other Information in the Library
The library provides the following information resources:
Installation Guide
Provides detailed planning and installation information.
Help
Provides context-sensitive information and step-by-step guidance for common tasks, as well as
definitions for each field on each window.
About this Book and the Library
9
10
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
1
Overview
1
The Identity Manager Java DataBase Connectivity (JDBC) Fan-Out driver supports the fan-out
capability at the driver level. The Fan-Out driver provisions users and password to multiple databases
with minimal effort. This eliminates the need for the Identity Manager administrator to configure
multiple JDBC drivers using the same policies to provision multiple databases of the same type. You
can centrally manage user accounts and have them automatically created, configured, maintained,
and removed when appropriate. This saves cost and time associated with managing the Identity
Manager environment. In this configuration, the synchronization is unidirectional, from the Identity
Vault to the connected database.
The Fan-Out driver supports the following features:
Š Synchronizes users and groups from the Identity Vault to the target databases
Š Synchronizes passwords from the Identity Vault to the target databases
Š Provisions or deprovisions user accounts in the target databases based on entitlements
Š Assigns or revokes user permissions in the target databases based on entitlements
IMPORTANT
Š The Fan-Out driver is a Subscriber channel only driver.
Š The Remote Loader options do not apply to the Fan-Out driver. This driver uses the Fan-Out
agent component to create multiple JDBC Fan-Out driver instances.
1.1
Components for Fan-Out Configuration
The Fan-Out driver relies on the following independent components. Figure 1-1 shows how these
components work together.
Š Fan-Out Driver Shim: The Fan-Out driver shim is a Java-based interface driver. The driver
shim virtually connects to the Fan-Out agent through ActiveMQ.
Š ActiveMQ: The Fan-Out driver and the Fan-Out agent use ActiveMQ for transferring the
Subscriber events, configuration data, and the queries. The Fan-Out agent creates a separate
queue for each JDBC driver instance. The JDBC driver instances wait for the events in their
respective queues. For information about installing ActiveMQ, see Section 2.4, “Installing
ActiveMQ,” on page 19. To manage the ActiveMQ queues, launch the URL: http://<ActiveMQ IP
Address>:8161/admin/queues.jsp.
Š Fan-Out Agent: The Fan-Out agent is a standalone Java process that works independently of
the Identity Vault. The Fan-Out agent loads the JDBC driver instances based on the
configuration of the connection objects in the Fan-Out driver. For more information about the
connection objects, see Section 1.7, “Driver Concepts,” on page 15.
The Fan-Out agent provides an interface through REST endpoints for performing basic
monitoring and management tasks. To ease the initial deployment, the Fan-Out agent autoinitializes with the default configuration values when it is started for the first time. To change the
default settings, use the REST endpoints. For more information about REST endpoints
supported for the driver, see Appendix C, “REST Endpoints,” on page 55. The driver installation
Overview
11
folder contains sample scripts that you can run to manage the Fan-Out agent. The sample
scripts internally use the REST endpoints. For more information, see Section 3.3, “Managing the
Fan-Out Agent,” on page 24.
Alternatively, you can manually edit the configuration file. This method requires you to restart the
Fan-Out agent for the changes to take effect. However, this is not required for all the changes
made through the REST endpoints. To understand which changes need a restart of the Fan-Out
agent, see Section 3.1, “Generating the Default Configuration File,” on page 21.
Figure 1-1 Fan-Out Driver Configuration
2
Fan-Out Driver
JDBC
JDBC
JDBC
Fan-Out Driver
Fan-Out Agent
Identity
Manager
ActiveMQ
3
Fan-Out Agent
1
JDBC
JDBC
JDBC
Fan-Out Agent
Fan-Out Driver
JDBC
JDBC
JDBC
Blocks #1,#2 and #3 are process bounderies. Process identification is required between each of them before events and configurations
can be delivered reliably. Fan-Out Driver should be hosted on IDM.
The fan-out process works as follows:
1 The Identity Vault stores the connection object configuration. The configuration includes
connection, authentication, and trace information.
2 The Fan-Out driver receives the initialization document from the engine.
3 The Fan-Out driver and the Fan-Out agent perform a handshake to establish a connection. This
signals the start of the communication between the agent and the driver. The handshake is done
through challenge-response sets.
4 The Fan-Out driver queries the Identity Vault for the connection objects associated with this
driver and creates multiple initialization documents based on the content in the connection
objects.
5 The Fan-Out driver sends the initialization documents to the Fan-Out agent through ActiveMQ.
6 The Fan-Out agent loads the JDBC driver instances.
12
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
7 The Fan-Out driver sends the events to the Fan-Out agent through ActiveMQ.
8 The Fan-Out agent determines which JDBC driver instances this event should be sent to.
9 The JDBC driver processes the event and sends the status of the event to the Fan-Out driver
through ActiveMQ.
10 The Fan-Out driver sends this status to the Identity Manager engine.
NOTE: Only one flavour of database can be managed per agent. For example: all Oracle, all MSSQL,
and so on.
1.2
Data Transfer Between Systems
The data is transferred between the Identity Vault and the Fan-Out driver only on the Subscriber
channel.
The Subscriber channel performs the following activities:
Š Watches for changes to the Identity Vault objects.
Š Makes changes to the target databases to reflect those changes.
1.3
Supported Operations
The Fan-Out driver supports the following operations on the Subscriber channel:
Š Section 1.3.1, “Password Synchronization,” on page 13
Š Section 1.3.2, “Data Synchronization,” on page 13
1.3.1
Password Synchronization
The Fan-Out driver supports password set and check operations on the Subscriber channel. The
driver does not support bidirectional password synchronization.
1.3.2
Data Synchronization
The Fan-Out driver supports direct and indirect data synchronization models.
Model
Association
Description
Direct
Usually associated with views
Views provide the abstraction mechanism that
facilitates integration with existing customer tables.
Indirect
Usually associated with tables
Customer tables may not match the structure required
by the driver. Therefore, you should create
intermediate staging tables that match the structure
that the driver requires.
For more information about data synchronization models see Supported Data Synchronization
Models in the NetIQ Identity Manager Driver for JDBC Implementation Guide.
Overview
13
1.4
Installing and Configuring the Driver
For information about installing and configuring the Fan-Out driver, see Chapter 2, “Installing the FanOut Driver Components,” on page 17 and Chapter 3, “Configuring the Fan-Out Agent,” on page 21.
1.5
Supported Databases
The driver supports the following databases:
Table 1-1 Supported Databases
Database
Version
Microsoft SQL Server 2005
Service Pack 1 or later
Microsoft SQL Server 2008
Microsoft SQL Server 2008 R2
Microsoft SQL Server 2012
Microsoft SQL Server 2014
MySQL 5
5.6.x or later
Oracle 10g
Release 1 (10.0.2) or later
Oracle 11ig
Release 1 (11.1) or later
Oracle 12 C
You can use the JDBC driver with other databases or database versions. However, NetIQ does not
support them. To interoperate with the JDBC driver, a database must meet the following
requirements:
Š Support the SQL-92 entry level grammar.
Š Be JDBC-accessible.
1.6
Supported Third-Party JDBC Drivers
The Fan-Out driver supports the following third-party JDBC drivers:
Š MySQL Connector/J
Š Oracle Thin Client
Š Oracle OCI
Š jTDS
For more information, see Third-Party JDBC Drivers in the NetIQ Identity Manager Driver for JDBC
Implementation Guide.
14
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
1.7
Driver Concepts
Š Connection Objects: Connection objects are instances of the DirXML-Resource class. Each
connection object holds authentication information of the server or database you are connecting
to and the trace information for the instances that the Fan-Out agent configures and loads. For
more information, see DirXML-Data.
The Fan-Out driver uses the following attributes of the connection object to determine the status
of the connection object:
Š DirXML-ContentType: The driver uses this attribute to determine if it is a connection object
or any other driver resource. To qualify for a connection object, this attribute should have
one of the following values:
Š application/vnd.novell.dirxml.fanout+xml: This MIME value signals that the current
connection object is disabled.
Š application/vnd.novell.dirxml.fanout-enabled+xml: This MIME value signals that
the current connection object is enabled.
Enabled connection objects are loaded by the Fan-Out agent.
Š DirXML-Data: This attribute contains the connection and trace information for the JDBC
driver instance. The following is a sample of the XML document that DirXML-Data contains:
<?xml version="1.0" encoding="UTF-8"?>
<connection>
<authentication-info>
<server>jdbc:jtds:sqlserver://111.111.1.1:1433/idm</server>
<user>idm</user>
</authentication-info>
<trace-info>
<driverTraceFile>/home/sqlserver2.log</driverTraceFile>
<driverTraceLevel>5</driverTraceLevel>
<driverTraceFileSize />
</trace-info>
<connection-password-ref display-name="Connection Password"
name="com.fanout.conn.passwd">
<value>fanout.connection_2.passwd</value>
</connection-password-ref>
</connection>
Š Filter: The driver filter includes two additional classes: DirXML-Resource and DirXML-Driver to
allow you to handle dynamic changes to the connection objects. The changes made to the
connection objects do not require you to restart the Fan-Out driver. Depending on the changes
made to the connection objects, the Fan-Out agent restarts or stops the JDBC driver instances.
For more information about the general concepts of the JDBC driver, see Introducing the Identity
Manager Driver for JDBC in the NetIQ Identity Manager Driver for JDBC Implementation Guide.
1.8
Database Concepts
For more information about the database concepts, see Database Concepts in the NetIQ Identity
Manager Driver for JDBC Implementation Guide.
Overview
15
16
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
2
Installing the Fan-Out Driver
Components
2
The Fan-Out driver needs to be on the same server where you install the Identity Manager engine.
This section guides you through the process of installing and configuring the fan-out components.
Š Section 2.1, “Prerequisites for Installing the Driver,” on page 17
Š Section 2.2, “Updating the Identity Manager Engine,” on page 18
Š Section 2.3, “Adding the Fan-Out Driver Files to the Identity Vault,” on page 18
Š Section 2.4, “Installing ActiveMQ,” on page 19
Š Section 2.5, “Setting Up ActiveMQ Startup Service,” on page 19
Š Section 2.6, “Installing the Fan-Out Agent,” on page 20
2.1
Prerequisites for Installing the Driver
Before installing the driver, ensure that you install the following software in your Identity Manager
environment:
Š Identity Manager 4.5 Service Pack 2 Hotfix1.
For download and installation instructions, see “NetIQ Identity Manager 4.5 Service Pack 2
Release Notes”.
For Identity Manager 4.5 prerequisites and installation information, see Considerations and
Prerequisites for Installation in the NetIQ Identity Manager Setup Guide.
Š Designer 4.5 Service Pack 2 Hotfix2.
Identity Manager Designer 4.5 Service Pack 2 Hotfix 2 includes the necessary software to create
and configure the Fan-Out driver. NetIQ recommends that you apply this hotfix to your Designer
before attempting to create the driver.
Š JDBC Driver shim
Š ActiveMQ 5.12.1
Download ActiveMQ 5.12.1 from the Apache Download Website.
Š Download the NIdM_Driver_4.5_JDBCFanout.zip file from the Download Web site.
The zipped file includes the following content:
Š Agent.zip
Š FanoutDriverShim.jar
Š NovellAudit (Platform Agent)
Š vcredist_x64.exe
Š iManager Plug-In for Identity Manager version 4.5.2.1
Š Fan-Out Driver Packages
Š Fanout Common - NETQFOUTCOMM
Installing the Fan-Out Driver Components
17
Š Fanout Password Synchronization Common - NETQFOPWDSYN
Š JDBC Fanout Account Tracking - NETQJFOACTRK
Š JDBC Fanout Common - NETQJFOCOMON
Š JDBC Fanout Data Collection - NETQJFODACLN
Š JDBC Fanout Entitlement Support - NETQJFOENTIS
Š JDBC Fanout Managed System Information Support - NETQJFOMNSIS
Š JDBC Fanout Password Synchronization - NETQJDBCFOPS
Š Oracle Fanout Base - NETQFOCLBASE
Š Oracle Fanout Indirect Synchronization - NETQFOCLINSY
Š Oracle Fanout Direct Synchronization - NETQFOCLDISY
Š SQL Server Fanout Base - NETQFSQSBASE
Š SQL Server Fanout Indirect Synchronization - NETQFSQSINSY
Š SQL Server Fanout Direct Synchronization - NETQFSQSDISY
Š MySQL Fanout Base - NETQFOMYBASE
Š MySQL Fanout InnoDB Engine Indirect Synchronization - NETQFIMYINSY
Š MySQL Fanout MyISAM Engine Indirect Synchronization - NETQFMMYINSY
Š MySQL Fanout MyISAM Engine Direct Synchronization - NETQFMMYDISY
Download the packages from the Package Update Channel.
Š Identity Manager Driver for Managed System Gateway version 4.0.2
This driver is required for Data Collection to work with Fan-Out driver. Download the driver patch
from the Download Web site.
Š Identity Manager Driver for Data Collection Services version 4.0.1 with base package
2.3.0.20151207151321.
Š Identity Manager Collector for auditing version 2011.1r3
Š Third-party JDBC Driver
For connecting to the target database.
2.2
Updating the Identity Manager Engine
This section provides information about updating the Identity Manager 4.5 engine to Identity Manager
4.5 Service Pack 2 Hotfix1. This hotfix contains the necessary software for creating the Fan-Out
driver. For more information about applying the hotfix, see Hotfixing the Identity Manager Engine and
Remote Loader in the NetIQ Identity Manager Setup Guide.
2.3
Adding the Fan-Out Driver Files to the Identity
Vault
This section provides information about adding the Fan-Out driver files to the Identity Manager server.
The NIdM_Driver_4.5_JDBCFanout.zip file contains the Fan-Out driver files. Ensure that you have
downloaded this file from the Identity Manager 4.5 Downloads page.
18
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
To add the Fan-Out driver files to the Identity Vault:
1 Copy and extract the NIdM_Driver_4.5_JDBCFanout.zip file to a temporary location on the
Identity Manager server.
2 Stop eDirectory.
3 Copy the Fan-Out driver shim to your Identity Manager installation folder from the temporary
location.
Š Linux: Copy the FanoutDriverShim.jar file to the /opt/novell/eDirectory/lib/
dirxml/classes/ folder.
Š Windows: Copy the FanoutDriverShim.jar to the
C:\NetIQ\IdentityManager\NDS\lib folder.
4 Unzip the Agent.zip file and copy the activemq file from the lib folder of the extracted file to
your Identity Manager installation folder.
Š Linux: Copy the activemq-all-5.12.1.jar to /opt/novell/eDirectory/lib/dirxml/
classes/ directoy.
Š Windows: Copy the activemq-all-5.12.1.jar to C:\NetIQ\IdentityManager\NDS\lib
folder.
5 Start eDirectory.
2.4
Installing ActiveMQ
NetIQ recommends that you install ActiveMQ on a server other than the Identity Manager server. If
you install ActiveMQ on the Identity Manager server, ActiveMQ installed by the User Application and
ActiveMQ used by the Fan-Out agent attempt to use the same default port (61616). To avoid this
situation, change the port number to any available port number. This consideration is also applicable
for Sentinel server.
1 Download ActiveMQ 5.12.1 from the Apache Download Website.
2 Unzip the archive to any preferred location in your computer.
3 Navigate to the <AMQ Installation Directory>/bin folder.
4 Start an ActiveMQ instance.
Š Linux: Run the./activemq start command.
Š Windows: Run the.activemq.bat start command.
2.5
Setting Up ActiveMQ Startup Service
This section provides details about setting up ActiveMQ as a startup service.
Š Section 2.5.1, “Enabling the ActiveMQ Service on Linux,” on page 19
Š Section 2.5.2, “Enabling the ActiveMQ Service on Windows,” on page 20
2.5.1
Enabling the ActiveMQ Service on Linux
1 Set the path for the JAVA_HOME environment variable.
2 Set the path for the ACTIVEMQHOME environment variable in the /root/.profile file to the
location where ActiveMQ is extracted (<AMQ Installation Directory>). The /root/
.profile file needs to be created if it does not exist.
Installing the Fan-Out Driver Components
19
3 Download and extract the NIdM_Driver_4.5_JDBCFanout.zip file to a temporary location on
your server.
4 Unzip the Agent.zip file from the extracted file and copy the activemqdxml file from the linux
folder to /etc/init.d.
5 Navigate to the Linux folder of the extracted file and run activemqAddSvc by executing the
following command:
./activemqAddSvc
6 To start the ActiveMQ service, execute the following command:
/etc/init.d/activemqdxml start
To stop the ActiveMQ service, execute the following command:
/etc/init.d/activemqdxml stop
2.5.2
Enabling the ActiveMQ Service on Windows
To add the ActiveMQ service to the Windows services list, navigate to ACTIVEMQ_HOME/bin/win64
and run InstallService.bat.
This creates the ActiveMQ service in the Windows service list. This service automatically starts when
the system reboots.
To remove the ActiveMQ service from the Windows services list, run UninstallService.bat.
2.6
Installing the Fan-Out Agent
You can install the Fan-Out agent on the Identity Manager server or any other server that meets the
Identity Manager system requirements.
1 Download and extract the NIdM_Driver_4.5_JDBCFanout.zip file to a temporary location on
your server.
2 Extract the Agent.zip file.
3 Perform the fan-out configuration. For more information, see Chapter 3, “Configuring the Fan-
Out Agent,” on page 21.
20
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
3
Configuring the Fan-Out Agent
3
After the Fan-Out agent is installed, configure the agent to suit your environment by using the scripts
provided in the Fan-Out installation folder:
Š Linux: <FanoutAgent Installation Location>/linux
Š Windows: <FanoutAgent Installation Location>/windows
The following sections provide instructions to configure the Fan-Out agent:
Š Section 3.1, “Generating the Default Configuration File,” on page 21
Š Section 3.2, “Starting the Fan-Out Agent,” on page 23
Š Section 3.3, “Managing the Fan-Out Agent,” on page 24
Š Section 3.4, “Enabling Auditing for the Fan-Out Agent,” on page 26
3.1
Generating the Default Configuration File
When you run the Fan-Out agent without any options, the agent creates the default configuration file
and then stops running. Execute one of the following commands based on your platform:
Š Linux: ./startAgent
Š Windows: startAgent.bat
The Fan-Out agent creates the following directories in the <FanoutAgent Installation Location>
folder:
Š config: This directory contains the default configuration file for the Fan-Out agent. Table 3-1 lists
the parameters contained in the default configuration file. Except
netiq.fanoutagent.connection.url, you can leave other parameters unchanged. Specify the
URL of the ActiveMQ instance in this parameter.
NOTE: If you run the Fan-Out agent without any options after customizing the default
configuration file, it will overwrite the changes that you made to the parameters. NetIQ
recommends that you rename the configuration file to a different name to avoid overwriting the
file and use the renamed file for subsequent operations.
Š logs: This directory contains the trace files.
Š tmp: This directory contains the temporary files created by the Fan-Out agent.
Table 3-1 Default Configuration Parameters
Parameter
Description
netiq.fanoutagent.trace.level
Fan-Out Agent trace level. Range 1-5. Setting the
value of this parameter to 3 provides most of the XML
and operation traces.
netiq.fanoutagent.trace.file
Path of the Fan-Out agent trace file.
Configuring the Fan-Out Agent
21
Parameter
Description
netiq.fanoutagent.instance.name
Name of the Fan-Out agent instance.
netiq.fanoutagent.connection.url
Connection URL of the ActiveMQ instance.
netiq.fanoutagent-config.recv.queue
Configuration queue to receive the initialization
parameters.
netiq.fanoutagent-config.snd.queue
Configuration queue to query specific configurations.
netiq.fanoutagent-query.in.recv.queue
Query-in queue to receive query responses from the
Identity Vault.
netiq.fanoutagent-query.in.send.queue
Query-in queue to send queries to the Identity Vault.
netiq.fanoutagent-sub.event.recv.queue
Subscriber event queue to receive the Subscriber
events.
netiq.fanoutagent-sub.event.send.queue
Subscriber event queue to send the Subscriber event
status.
netiq.fanoutagent-sub.delayed.event.send.queue
Subscriber event queue to send the status of the
delayed event.
netiq.fanoutagent-query.out.recv.queue
Query-out queue to receive the query for the agent.
netiq.fanoutagent-query.out.send.queue
Query-out queue to send the query response.
netiq.fanoutagent.cmd.trace.level
Trace level for the Fan-Out command server.
netiq.fanoutagent.cmd.srv.ip
IP address to which the command server establishes
connection with. This helps you to restrict the
command server to listen to a specific interface.
netiq.fanoutagent.cmd.srv.port
Port number on which the command server listens.
netiq.fanoutagent.cmd.trace.file.count
Number of trace files available for the command
server. After the limit is reached, the older file are
automatically deleted.
netiq.fanoutagent.cmd.allow.http
Parameter to disable https on the command server.
netiq.fanoutagent.cmd.trace.file.size
The size of the Fan-Out agent command server trace
files in MB.
netiq.fanoutagent.cmd.keystore.file
The path to the keystore used by the command server.
netiq.fanoutagent.cmd.trace.dir
The directory where the Fan-Out agent command
server traces are created.
netiq.fanoutagent.connection.truststore.file
The path to the truststore file used for mutual
authentication for a secure connection.
netiq.fanoutagent.connection.keystore.file
The path to the keystore file used for mutual
authentication for a secure connection.
netiq.fanoutagent-sub.event.max.retry
The maximum limit for retrying an event. The default
value is -1.
You can change the default configuration of the Fan-Out agent to suit your requirement. Changes are
dynamically reflected in some parameters. For changes to take effect in other parameters, restart the
Fan-Out agent. The following parameters are dynamically reflected:
Š netiq.fanoutagent.trace.level
22
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
Š netiq.fanoutagent.trace.file
Š netiq.fanoutagent.cmd.trace.level
Š netiq.fanoutagent.cmd.trace.file.count
Password changes are dynamically reflected. For example, agent password values is changed
dynamically. For future commands, you must use the new agent password.
NOTE: For multiple Fan-Out agents, you require equal number of ActiveMQs. In case the same
ActiveMQ is used for multiple Fan-Out agents, manually clean the ActiveMQ queues before using a
different Fan-Out agent.
3.2
Starting the Fan-Out Agent
You can start the Fan-Out agent by passing the startAgent command in the command prompt or by
using the startup script, which enables the agent as a startup service.
Before starting the Fan-Out agent, ensure that your server meets the following requirements:
Š ActiveMQ is running.
Š The Java and CURL must be present in the system path of your operating system to manage the
Fan-Out agent. If CURL is not present in your environment, download the SSL version of the
CURL binary from Releases and Downloads.
Š Copy the appropriate third-party JDBC connector (for example, ojdbc6.jar) to the
<FanoutAgent Installation Location>/lib folder. For more information, see the Driver
Information table in “Section 13.3.9, Oracle Thin Client JDBC Driver” in the NetIQ Identity
Manager Driver for JDBC Implementation Guide.
To start the Fan-Out Agent in the command prompt:
1 Open a command prompt.
2 Run the startAgent command and pass the default configuration file name as a parameter in
the command.
startAgent –config <FanoutAgent Installation Location>/config/fanoutagentconfig.properties
3 (Optional) To change the agent and the shim passwords, use the setPassword command.
The default passwords are netiq. For more information, see Section 3.3, “Managing the Fan-Out
Agent,” on page 24.
4 (Optional) To change the keystore password, use the setKSPassword command.
The default password for the keystore is netiq123.
5 (Optional) To change the encryption key, use the setEncryptionKey command.
The default value for the key is netiq.
6 (Optional) Establish a secure connection between the Fan-Out agent and ActiveMQ. For more
information, see Chapter 5, “Securing Fan-Out Driver Communication,” on page 35.
IMPORTANT: Ensure that you specify the same values for these parameters during Fan-Out driver
configuration.
To enable the Fan-Out agent service to automatically start with the system start, perform the following
actions for your platform:
Configuring the Fan-Out Agent
23
Linux:
1 Set the JAVA_HOME environment variable.
2 Copy the fanoutdxml file from <FanoutAgent Installation Location>/linux to /etc/
init.d.
3 Run the fanoutAgentAddSvc file from <FanoutAgent Installation Location>/linux by
executing the following command:
./fanoutAgentAddSvc
4 Start the Fan-Out agent service by executing the following command:
/etc/init.d/fanoutdxml start
To stop the Fan-Out agent service, execute the following command:
/etc/init.d/fanoutdxml stop
Windows:
1 Set the JAVA_HOME environment variable.
2 Run vcredist_x64.exe file from the NIdM_Driver_4.5_JDBCFanout.zip file.
3 Install the Fan-Out agent service by executing the following command:
<FanoutAgent Installation Location>\Windows\FanoutAgentSvc.exe –i
The display name of the service is Fanout Agent Service.
NOTE: If both ActiveMQ and Fan-Out agent services are running on the same server, ensure
that ActiveMQ service starts before the Fan-Out agent service. To set the Fan-Out agent service
to a delayed start, run the following command on Windows:
sc config FanoutAgent start= delayed-auto
4 Start the Fan-Out agent service.
To remove the Fan-Out agent service on Windows, execute the following command:
<FanoutAgent Installation Location>\Windows\FanoutAgentSvc.exe –u
IMPORTANT: You can run only one Fan-Out agent instance on a specific server as a service.
However, if you run a Fan-Out agent as an application, Identity Manager allows you to run multiple
instances of the Fan-Out agent on the same server by using separate configuration files.
The Fan-Out agent service loads the configuration properties only from <FanoutAgent
Installation Location>/config/ path. Ensure that the configuration properties file name is
fanoutagent-config.properties (this is the default file name).
A Fan-Out agent instance that is started as a service must be stopped as a service only. This means
that you should not stop the agent using the stopAgent command or REST endpoint if it is started as
a service.
3.3
Managing the Fan-Out Agent
You can manage the Fan-Out agent by using the scripts from the agent installation directory Table 32 lists the commands to manage the Fan-Out agent. To view the help, invoke the command with -–
help option.
24
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
Table 3-2 Commands to Manage the Fan-Out Agent
Command
Description
Example
startAgent
Starts the Fan-Out agent instance
startAgent –config <FanoutAgent
Installation Location>/config/
fanoutagent-config.properties
stopAgent
Stops the Fan-Out Agent instance
stopAgent –config <FanoutAgent
Installation Location>/config/
fanoutagent-config.properties netiq
getservices
Fetches the status of the JDBC driver instances getServices –config <FanoutAgent
loaded by the Fan-Out agent and writes the
Installation Location>/config/
status to a file.
fanoutagent-config.properties 0 ./
services.txt netiq
startService
Starts the specified JDBC driver instance. You
can get the JDBC driver instance name from the
output file generated by the getServices
command.
startService –config <FanoutAgent
Installation Location>/config/
fanoutagent-config.properties
serviceName netiq
stopService
Stops the specified JDBC driver instance. You
can get the JDBC driver instance name from the
output file generated by the getServices
command.
stopService –config <FanoutAgent
Installation Location>/config/
fanoutagent-config.properties
serviceName netiq
setPassword
Sets the agent and shim passwords for the Fan- setPassword -config <FanoutAgent
Out agent instance.
Installation Location>/config/
fanoutagent-config.properties netiq
microfocus netiq microfocus
setAMQKSPasswo Sets the Keystore password used for mutual
rd
authentication with ActiveMQ when SSL is
enabled
setAMQKSPassword -config
<FanoutAgent Installation Location>/
config/fanoutagent-config.properties
netiq microfocus
setAMQTSPasswo Sets the Truststore password used for mutual
rd
authentication with ActiveMQ when SSL is
enabled.
setAMQTSPassword -config
<FanoutAgent Installation Location>/
config/fanoutagent-config.properties
netiq microfocus
setKSPassword
Sets the Keystore password of the Fan-Out
agent instance.
setKSPassword -config <FanoutAgent
Installation Location>/config/
fanoutagent-config.properties netiq123
novell microfocus
setConfig
Changes the configuration options as specified
in the input file.
setConfig -config <FanoutAgent
Installation Location>/config/
fanoutagent-config.properties ./
sample_cfg.json netiq
setEncryptionKey
Sets the encryption key. You can use this key to setEncryptionKey -config config/
encrypt/decrypt ActiveMQ messages.
fanoutagent-config.properties netiq
netiq
Configuring the Fan-Out Agent
25
3.4
Enabling Auditing for the Fan-Out Agent
The Fan-Out agent supports both XDAS and legacy auditing solutions.
To enable the legacy auditing, install the Platform Agent on the server where you installed the FanOut agent. The Platform Agent installation files are provided under the NovellAudit folder in the
NIdM_Driver_4.5_JDBCFanout.zip file.
For more information about configuring the auditing, seeConfiguring the Platform Agent Text File in
the NetIQ Identity Manager Reporting Guide for Sentinel.
To enable XDAS auditing, navigate to the <FanoutAgent Installation Location>/config folder
and rename the xdasconfiguration.properties.template file to
xdasconfiguration.properties. For more information about configuring XDAS, see Configuring
the NetIQ XDASv2 Text File in the NetIQ Identity Manager Reporting Guide for Sentinel.
For more information about XDAS auditing, see XDASv2 Administration Guide.
NOTE: The Fan-Out agent does not support XDAS event caching.
26
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
4
Creating New Fan-Out Driver
4
After the Fan-Out driver files are installed on the server where you want to run the driver object, you
can create a driver object in the Identity Vault. Creating a driver object consists of installing the driver
packages and then modifying the driver configuration to suit the environment.
Š Section 4.1, “Creating a Fan-Out Driver Object in Designer,” on page 27
Š Section 4.2, “Activating the Driver,” on page 34
You must install the fan-out components before configuring a new Fan-Out driver object. For more
information, see Chapter 2, “Installing the Fan-Out Driver Components,” on page 17.
4.1
Creating a Fan-Out Driver Object in Designer
Creating the driver includes installing the Fan-Out driver packages and then modifying the
configuration to suit your environment.
Š Section 4.1.1, “Importing the Driver Packages,” on page 27
Š Section 4.1.2, “Installing the Driver Packages,” on page 28
Š Section 4.1.3, “Configuring the Driver Object,” on page 30
Š Section 4.1.4, “Configuring the Database Connections for the Driver,” on page 31
Š Section 4.1.5, “Deploying the Driver Object,” on page 33
Š Section 4.1.6, “Starting the Driver,” on page 33
Š Section 4.1.7, “Managing the Connection Objects,” on page 34
4.1.1
Importing the Driver Packages
You can update the driver packages at any time.The driver packages are stored in the Package
Catalog. Packages are initially imported into the Package Catalog when you create, import, or
convert a project. Ensure that you import the latest packages into the Package Catalog before
installing the driver.
To verify the latest packages in the Package Catalog:
1 Open Designer.
2 In the toolbar, click Help > Check for Package Updates.
3 Click OK to import the package updates.
If prompted to restart Designer for the changes to take effect, click Yes, save your project, and
then wait for the Designer to restart.
or
Click OK if there are no package updates.
4 Continue with Section 4.1.2, “Installing the Driver Packages,” on page 28.
Creating New Fan-Out Driver
27
4.1.2
Installing the Driver Packages
1 In Designer, open your project.
2 In the Modeler, drag and drop a supported JDBC database from the Designer palette.
For example, Oracle. For information about supported databases, see Section 1.5, “Supported
Databases,” on page 14.
3 Select the Fan-Out Base from the list of available base packages, then click Next.
4 Select the Synchronization Mode. For more information, see Section 1.3.2, “Data
Synchronization,” on page 13.
5 Select the optional features to install for the Fan-Out driver, then click Next.
All options are selected by default. The options are:
Š Entitlements Support: These packages contain the policies that provision the user
accounts on the connected database. For more information, see the NetIQ Identity Manager
Entitlements Guide.
Š Data Collection: These packages contain the policies that enable the driver to collect data
for reports. If you are using the Identity Reporting Module, ensure that this option is
selected. For more information, see Using Identity Manager 4.5 Reports.
Š Account Tracking: These packages contain the policies that enable account tracking
information for reports. If you are using the Identity Reporting Module, ensure that this
option is selected. For more information, see Using Identity Manager 4.5 Reports.
The Account Tracking feature is introduced with the NetIQ Compliance Management
Platform. The Compliance Management Platform helps you mitigate risk, simplify business
governance, and ensure compliance throughout the enterprise. The platform enables you to
provision users based on secure web and client applications by granting access to users
based upon provisioning policy, and monitor and validate user and system activity in real
time with automated policy-based corrective actions for non-compliant activities. For more
information, see the NetIQ Compliance Management Platform product page (http://
www.novell.com/products/compliancemanagementplatform/).
6 (Conditional) If there are package dependencies for the packages you selected to install for this
driver, you must install them to install the selected package. Click OK to install the package
dependency listed.
7 (Conditional) If more than one type of package dependency is installed, Designer displays
separate configuration pages for each package. Click OK to install any additional package
dependencies.
8 (Conditional) The Common Settings page is displayed only when the Common Settings package
is installed as a dependency. On the Install Common Settings page, specify the common settings
for User and Group containers:
Š User Container: Select the Identity Vault container where the user accounts will be added
in the Identity Vault. This value becomes the default for all drivers in the driver set.
Š Group Container: Select the Identity Vault container where the groups will be added in the
Identity Vault. This value becomes the default for all drivers in the driver set.
9 Click Next.
When all dependencies are installed, you must configure the components.
10 On the Driver Information page, specify a name for the driver that is unique within the driver set,
and then click Next.
28
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
11 On the Application Authentication page, fill in the following information:
Š Connection Information: Specify the URL of the ActiveMQ instance to which this driver
connects to. For example, tcp://111.1.1.1:61616.
Š Synchronization Filter: Select the synchronization filter. For more information, see
“Database Scoping Parameters” from the NetIQ Identity Manager Driver for JDBC
Implementation Guide.
Š Synchronization Model: Select the synchronization model based on the synchronization
mode specified in Step 4.
12 Do not change the default values of the remaining parameters on this page, then click Next.
13 On the Entitlements Information page, specify a name for the Account Entitlement Value field,
then click Next.
14 (Conditional) This page is displayed only if you selected to install the Data Collection and
Account Tracking groups of packages. On the Managed System Information page, fill in the
following fields to define your connected database application:
Š Name: Specify a descriptive name for the connected database application. The name is
displayed in reports.
Š Description: Specify a brief description for the connected database application. The
description is displayed in reports.
Š Location: Specify the physical location of the connected database application. The location
is displayed in reports.
Š Vendor: Specify the vendor of the connected database application. This information is
displayed in reports.
Š Version: Specify the version of the connected database application. The version is
displayed in reports.
15 Click Next.
16 (Conditional) This page is displayed only if you selected to install the Managed System packages
and the Account Tracking packages. On the Install Managed System Information page, fill in the
following fields to define the classification of the connected database application. This
information is displayed in the reports. The options are:
Š Classification: Select the classification of the connected database application. This
information is displayed in the reports. Your options are:
Š Mission-Critical
Š Vital
Š Not-Critical
Š Other
If you select Other, you must specify a custom classification for the JDBC system.
Š Environment: Select the type of the connected database application environment. The
options are:
Š Development
Š Test
Š Staging
Š Production
Creating New Fan-Out Driver
29
Š Other
If you select Other, you must specify a custom classification for the database
application.
Click Next.
17 (Conditional) This page is displayed only if you selected to install the Data Collection and
Account Tracking groups of packages. Fill in the following fields to define the ownership of the
connected database application:
Š Business Owner: Select a user object in the Identity Vault that is the business owner of the
database application. This can only be a user object, not a role, group, or container.
Š Application Owner: Select a user object in the Identity Vault that is the application owner
of the database application. This can only be a user object, not a role, group, or container.
Click Next.
18 (Conditional) This page is displayed only if you selected to install the Account Tracking groups of
packages. On the Account Tracking Initial Configuration page, fill in the following fields:
Š Fanout Database Type: Select the required database. The Fan-Out supports databases
such as, MySQL, SQL Server, and Oracle.
Š Synchronization Model: Specify the mode of data synchronization.
Š User Table: This field is populated based on your selection in the Synchronization Model.
Specify the table or view in the connected database for which account tracking is enabled.
By default, the value is usr.
Š Realm: Specify the name of the realm that uniquely identifies the location of user accounts
in the connected database. For example, mysql.indirect.usr, where mysql is the
database name with the indirect data synchronization model, and user is the table or view in
the connected database for which account tracking is enabled.
Click Next.
19 Review the summary of tasks that will be completed to create the driver, then click Finish.
The driver is now created. To modify the configuration settings, proceed to the Section 4.1.3,
“Configuring the Driver Object,” on page 30.
4.1.3
Configuring the Driver Object
After importing the packages and creating the driver object, configure the driver to make it
operational. Many settings are available to help you customize and optimize the driver. However, you
should first configure the driver parameters located on the Driver Configuration page.
1 In Designer, open your project.
2 In the Modeler, right-click the driver icon or the driver line, then select Properties.
3 Click Driver Configuration and select the Driver Parameters tab.
4 In the Driver Options tab, specify the queue names in the Transport parameters. The different
queues are:
Š Subscriber Event Queues (SEND/RECV/DELAYED): The driver uses these queues to
send the Subscriber events to the Fan-Out agent and receive the status of these events.
Š Configuration Queues (SEND/RECV): The driver uses these queues for sending the
driver initialization documents and exchanging the handshake documents with the Fan-Out
agent.
Š Query-In Queues (SEND/RECV): The driver uses these queues to receive the queries
from the Fan-Out agent and sends the response of the queries to the Fan-Out agent.
30
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
Š Query-Out Queues (SEND/RECV): The driver uses these queues to send the queries to
the Fan-Out agent and receive the response of the queries from the Fan-Out agent.
NOTE: If you specified a different name for the queues in these parameters, ensure that the
same queue name is used during Fan-Out agent configuration.
5 In the Fanout Agent Configuration Parameters, fill in the following information:
Š Fanout Shim Password: Click Set Password to specify the Fan-Out shim password.
Š Fanout Agent Password: Click Set Password to specify the Fan-Out agent password.
The Fan-Out driver uses these passwords for performing handshake with the Fan-Out
agent.
Š Encryption Key: Click Set Password to specify the key to encrypt or decrypt the sensitive
data before sending the data to the message queues.
NOTE: Ensure that you provide the same value for the Fan-Out agent and shim passwords and
the encryption key. The default passwords are netiq.
6 To enable the SSL communication between the Fan-Out driver and ActiveMQ, specify the
following information:
Š AMQ Keystore Path: The full path to the keystore file. For example, /root/amqclients.ks.
Š AMQ Keystore Password: The password used by the keystore.
Š AMQ Truststore Path for SSL Certs: The full path to the truststore file. For example, /
root/amq-clients.ts.
Š AMQ Truststore Password: The password used by the truststore.
For more information about securing communication, see Chapter 5, “Securing Fan-Out Driver
Communication,” on page 35.
7 Do not change the default value of Fanout Shim classname.
8 Do not change the default value of Matching Attributes.
The Fan-Out agent uses Matching Attributes to match the objects in the delayed add events.
This parameter must be schema-mapped equivalent of the attributes that are used in the object
matching policy. If you are using different attributes, specify the attribute names according to the
connected system schema.
9 The Normal JDBC Driver settings section for the Fan-Out driver is similar to the JDBC driver.
For more information about these parameters, see “Driver Parameters” in the NetIQ JDBC Driver
Guide.
After completing the configuration tasks, continue with Section 4.1.4, “Configuring the Database
Connections for the Driver,” on page 31.
4.1.4
Configuring the Database Connections for the Driver
Designer lets you configure multiple database connections for the Fan-Out driver. Each JDBC driver
instance loaded by the Fan-Out agent uses this information to connect to the database and for tracing
purposes.
Alternatively, you can run the createConnLDIF script to create an LDIF file that includes the
connection objects for the Fan-Out driver. However, you can run the script only after deploying the
driver. For more information, see “Configuring the Database Connections by Using the
createConnLDIF Script” on page 32.
Creating New Fan-Out Driver
31
The advantage of using Designer is that it allows you to manage the connections after they are
configured. If you use the createConnLDIF script for creating the connections, the script does not
provide this flexibility.
Š “Configuring the Database Connections in Designer” on page 32
Š “Configuring the Database Connections by Using the createConnLDIF Script” on page 32
Configuring the Database Connections in Designer
1 Open your project in Designer.
2 In the Modeler, right-click the driver icon and select Fanout Configuration.
3 Click
icon to create a fan-out connection.
4 Specify the fan-out connection details:
Š Name: Specify the name for the new connection.
NOTE: NetIQ restricts the connection object name to15 characters.
Š User: Specify the user name with which the JDBC driver instance will authenticate to the
database.
Š Connection Password: Specify the password with which the JDBC driver instance will
authenticate to the database
Š Server: Specify the server with which the JDBC driver instance will connect to. For more
information, see JDBC URL Syntaxes in the NetIQ Identity Manager Driver for JDBC
Implementation Guide.
Š Trace Level: Specify the trace level for the JDBC driver instance. This defines the level for
logging the trace messages.
Š Trace File: Specify the name of the trace file. This file includes the trace and debugging
messages for the JDBC driver instance.
Š Trace File Size: Specify the trace file size. This defines the limit for the trace file.
This parameter is not currently supported with the driver.
5 Click
icon to enable or disable the selected connection. By default, the connection is
disabled.
6 Click Save on the Designer toolbar.
7 (Conditional) To create multiple database connections for the fan-out configuration, repeat Step
3 through Step 6.
Configuring the Database Connections by Using the
createConnLDIF Script
After deploying the driver, you can run the createConnLDIF script to create an LDIF file that allows
you to create multiple database connection objects. The createConnLDIF file is located in
<FanoutAgent Installation Location>.
To create a database connection:
1 Create a CSV file with the required database connection information. A sample CSV file is
located in <FanoutAgent Installation Location>. For example: NIdM_Driver_4.5_JDBCFanout/
linux or NIdM_Driver_4.5_JDBCFanout/windows
32
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
2 Run the createConnLDIF script with the parameters as follows:
createConnLDIF [DriverDN in LDAP format] [input csv absolute file path] [output
ldif absolute file path]
This script creates the LDIF file in the specified location.
3 Import the LDIF file into eDirectory using any LDAP tool.
4.1.5
Deploying the Driver Object
After you create the driver in Designer, you can deploy the driver into the Identity Vault.
To deploy the driver:
1 In Designer, open your project.
2 In the Modeler, right-click the driver icon or the driver line, then select Live > Deploy.
3 If you are authenticated to the Identity Vault, skip to Step 5; otherwise, specify the following
information:
Š Host: Specify the IP address or DNS name of the server hosting the Identity Vault.
Š Username: Specify the DN of the user object used to authenticate to the Identity Vault.
Š Password: Specify the user’s password.
4 Click OK.
5 Read through the deployment summary, and then click Deploy.
6 Read the success message, and then click OK.
7 Click Define Security Equivalence to assign rights to the driver.
8 Click Exclude Administrative Roles to exclude users that should not be synchronized.
9 Click OK.
4.1.6
Starting the Driver
After creating a driver, you must start it. Identity Manager is an event-driven system and starts
caching the events once the driver is deployed. These events are processed when you start the
driver.
NOTE: NetIQ recommends that you complete the Fan-Out agent configuration before starting the
driver. For more information, see Chapter 3, “Configuring the Fan-Out Agent,” on page 21.
To start the driver:
1 In Designer, open your project.
2 In the Modeler, right-click the driver icon
or the driver line, then select Live > Start Driver.
Creating New Fan-Out Driver
33
4.1.7
Managing the Connection Objects
When you make changes to the connection objects and deploy the Fan-Out driver, you need not
restart the driver. Depending on the connection object changes, the Fan-Out driver starts, stops, or
restarts the JDBC driver instances.
When you add, modify, or delete a connection object, the Fan-Out driver sends the configuration
update to the Fan-Out agent. Based on the changes made, the Fan-Out agent starts, stops, or
restarts the corresponding JDBC driver instance.
NOTE: To detect the changes to the connection objects, Identity Manager provides two additional
filter classes namely DirXML-Resource and DirXML-Driver in the default filter of the Fan-Out driver.
Ensure that you review the following notes before redeploying the Fan-Out driver:
Š When you deploy the Fan-Out driver, all the connection objects are also deployed. If you perform
any dynamic updates to the connection objects or if you create the connection object
dynamically using Designer, NetIQ recommends that you deploy those connection objects
separately to avoid the entire driver restart.
Š If you change the password for a connection object, the connection object must be deployed
again. In this case, NetIQ recommends that you do not separately deploy or reconcile the
named-passwords for the connection objects.
Š When you use Designer to delete an existing Fan-Out connection, the connection object is
deleted only from Designer and it is not updated in the Identity Vault. To delete an existing FanOut connection object from the Identity Vault, use iManager to manually remove the connection
object.
4.2
Activating the Driver
If you created the driver in a driver set that has not been activated, you must activate the driver within
90 days. Otherwise, the driver stops working.
If driver activation has expired, the ndstrace window displays an error message.
To use the driver, you must reactivate it.
For information about activation, see “Activating Identity Manager” in the NetIQ Identity Manager
Setup Guide.
34
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
5
Securing Fan-Out Driver Communication
5
NetIQ recommends using Secure Socket Layer (SSL) protocols for driver communication. By default,
the SSL protocol is not configured among the Fan-Out components. You must configure the SSL
connection among the following Fan-Out components:
Š Between the Fan-Out driver shim and ActiveMQ
Refer to the following sections for instructions:
Š Section 5.1, “Creating a Keystore and a Truststore,” on page 35
Š Section 5.3, “Enabling SSL for the Fan-Out Driver Shim,” on page 36
Š Section 5.2, “Enabling SSL for ActiveMQ,” on page 36
Š Between ActiveMQ and the Fan-Out agent
Refer to the following sections for instructions:
Š Section 5.1, “Creating a Keystore and a Truststore,” on page 35
Š Section 5.2, “Enabling SSL for ActiveMQ,” on page 36
Š Section 5.4, “Enabling SSL for the Fan-Out Agent,” on page 37
Figure 5-1 represents the secured connection between the Fan-Out components.
Figure 5-1 Secured connection between Fan-Out components
Fan-Out
Driver Shim
SSL
ActiveMQ
SSL
Fan-Out
Agent
To support the SSL connections, you need to create keystore and truststore files. This section
explains how to create, export, and store this certificate on your server
After the secured connection is enabled, the Fan-Out components perform an SSL handshake to
establish a secure channel.
5.1
Creating a Keystore and a Truststore
1 Create a certificate for the broker by using keytool.
keytool -genkey -alias broker -keyalg RSA -keystore broker.ks
2 Export the broker's certificate to share with clients.
Securing Fan-Out Driver Communication
35
keytool -export -alias broker -keystore broker.ks -file broker_cert
3 Create a certificate/keystore for the client.
keytool -genkey -alias client -keyalg RSA -keystore client.ks
4 Create a truststore for the client and import the broker's certificate. This establishes that the
client "trusts" the broker.
keytool -import -alias broker -keystore client.ts -file broker_cert
5 Export the client's certificate so it can be shared with broker:
keytool -export -alias client -keystore client.ks -file client_cert
6 Create a truststore for the broker, and import the client's certificate. This establishes that the
broker "trusts" the client:
keytool -import -alias client -keystore broker.ts -file client_cert
NOTE: You must use the same passwords that were used for creating the keystores to configure the
Fan-Out components for SSL. For more information about creating certificates, see Setting up the
Key and Trust Stores.
5.2
Enabling SSL for ActiveMQ
1 Copy the files broker.ks and broker.ts to the server where ActiveMQ is installed.
2 Edit the server.xml present in the <AMQ install path>/conf/ folder.
Add the transport connector to enable SSL in transportConnectors section.
<transportConnector name="ssl" uri="ssl://0.0.0.0:61617?trace=true"/>
3 Update the sslContext section to add the paths of Keystore/Truststore and the respectice
passwords.
<sslContext>
<sslContext keyStore="file:///root/activemqkeystore/amq-server.ks"
keyStorePassword="novell"
trustStore="file:///root/activemqkeystore/amq-server.ts"
trustStorePassword="novell"/>
</sslContext>
4 Restart ActiveMQ.
NOTE: For more information about enabling secure transport on ActiveMQ, see Using Spring to
configure SSL for a Broker instance.
5.3
Enabling SSL for the Fan-Out Driver Shim
1 Copy the client.ks and client.ts files to the Identity Manager server.
2 Edit the following driver properties using Designer:
Š AMQ Keystore Path: Specify the client.ks path.
Š AMQ Keystore Password: Specify the password for client.ks.
Š AMQ Truststore Path: Specify the client.ts path.
36
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
Š AMQ Truststore Password: Specify the password for client.ts.
3 Save the configuration changes.
4 Deploy the driver.
5.4
Enabling SSL for the Fan-Out Agent
1 Copy the client.ks and client.ts files to the server where you install the Fan-Out agent.
2 Open the config file and specify the parameters as follows:
Š netiq.fanoutagent.connection.truststore.file: Specify the client.ts path. For example,
netiq.fanoutagent.connection.truststore.file=/home/keys/client.ts.
Š netiq.fanoutagent.connection.keystore.file: Specify the client.ks path. For example,
netiq.fanoutagent.connection.keystore.file=/home/keys/client.ks.
3 Start the Fanout Agent in Server Only Mode where it accepts only the configuration changes.
4 Set the passwords as follows:
Š setAMQKSPassword -config <fanoutaget_installdir>/Fanoutagent/config/
fanoutagent-config.properties <keystore password> <agent password>
Š setAMQTSPassword -config <fanoutaget_installdir>/Fanoutagent/config/
fanoutagent-config.properties <truststore password> <agent password>
5 Stop and start the Fan-Out Agent.
Securing Fan-Out Driver Communication
37
38
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
6
Troubleshooting the Driver
6
This section provides information on all the Fan-Out driver issues.
6.1
Mismatch in Driver Version
iManager and the driver trace display different versions of the Fan-Out driver. This occurs because
they fetch the version documents from different sources - the Fan-Out driver and the JDBC driver. For
example, iManager’s Version Discovery shows the version of the Fan-Out driver, but the trace shows
both versions for both the drivers.
This is because some documents are directly returned from JDBC driver whereas some are
constructed by the Fan-Out driver.
6.2
Fan-Out Driver and the Fan-Out Agent Time Out
When ActiveMQ and Fan-Out Agent are Running
When the Fan-Out driver does not receive response within a specified time, it displays a time out
warning message and processes the subsequent event.The response for the previous event will be
processed whenever it is available.
It is safe to ignore the warning as this doesn’t not cause any functionality loss.
6.3
ActiveMQ May Display Exception Error
Sometimes ActiveMQ may display an exception error while it is viewing a queue with an unprocessed
event.
To workaround this issue, install the latest patch from the ActiveMQ web site.
6.4
Cannot Run Two Instances of the Fan-Out Agent
Using the Same Queue Names
For multiple Fan-Out agents, you require equal number of ActiveMQs. In case the same ActiveMQ is
used for multiple Fan-Out agents, manually clean the ActiveMQ queues before using a different FanOut agent.
6.5
Unable to Update the Parameters Using the
setConfig Command
In order to change the netiq.fanoutagent.trace.level, netiq.fanoutagent.cmd.srv.ip,
netiq.fanoutagent.cmd.srv.port,and netiq.fanoutagent.cmd.allow.http parameters, stop
the Agent, change the parameters in the configuration file and restart the agent.
Troubleshooting the Driver
39
6.6
Troubleshooting Driver Processes
Viewing driver processes is necessary to analyze unexpected behavior. To view the driver processing
events, use DSTrace. You should only use it during testing and troubleshooting the driver. Running
DSTrace while the drivers are in production increases the utilization on the Identity Manager server
and can cause events to process very slowly. For more information, see “Viewing Identity Manager
Processes” in the NetIQ Identity Manager Driver Administration Guide.
40
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
7
Managing the Driver
7
As you work with the JDBC driver, there are a variety of management tasks you might need to
perform, including the following:
Š Starting, stopping, and restarting the driver
Š Viewing driver version information
Š Using Named Passwords to securely store passwords associated with the driver
Š Monitoring the driver’s health status
Š Backing up the driver
Š Inspecting the driver’s cache files
Š Viewing the driver’s statistics
Š Using the DirXML Command Line utility to perform management tasks through scripts
Š Securing the driver and its information
Š Synchronizing objects
Š Migrating and resynchronizing data
Š Activating the driver
Because these tasks, as well as several others, are common to all Identity Manager drivers, they are
included in one reference, the NetIQ Identity Manager Driver Administration Guide.
Managing the Driver
41
42
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
A
Known Issues and Limitations
A
NetIQ Corporation strives to ensure that our products provide quality solutions for your enterprise
software needs. The following issues are currently being researched. If you need further assistance
with any issue, please contact Technical Support.
For the list of the known issues in Identity Manager 4.5, Identity Manager Standard Edition 4.5, and
Identity Manager 4.5.1, see the Release Notes accompanying each release on the Identity Manager
Documentation page.
A.1
Known Issues
Š In the MSSQL database the underline base table can be modified through a view only if the
INSERT, UPDATE and DELETE statements refers to the column of the single base table.
Š If you are connecting the driver to Microsoft SQL database, the driver does not support Windows
NTLM and Windows Single Sign-On authentication.
Š Although the driver returns a success status for the Out of Band Cached event on a referential
attribute, the change is not updated in the target database.
Š The Fan-Out driver configuration page of iManager displays the Remote Loader option. Ensure
that you do not use this option with the Fan-Out driver.
Š The Fan-Out driver does not support direct synchronization mode for MySQL InnoDB. This is
because the driver does not support the Subscriber Add operation in this mode.
Š If you use the Tab key to navigate the Password field in the Fan-Out Configuration page of
Designer, Designer prompts you to save the resource when no change is made to the resource.
Š Identity Manager does not support the non-root installation of the Fan-Out agent.
Š When you stop the Fan-Out agent, the command server log file displays a warning message
stating that one thread cannot be stopped. Ignore the warning message.
Š Sometimes when a codemap refresh is done, you may not receive codemap data of all the
connected databases. You may get errors such as “Unable to complete the CODE MAP refresh
for entitlement” in catalina.out. This is due to the time taken by the query to return the codemap
results. Hence, you need to increase the timeout for the following parameters:
Š Default Query Timeout (IDMProv web UI > Roles and Resources > Configure Roles and
Resource Settings > Entitlement Query Settings > Default Query Timeout).
If the value of this parameter is 10 minutes, then increase the value of
NCPCLIENT_REQ_TIMEOUT parameter.
Š NCPCLIENT_REQ_TIMEOUT
Refer to Knowledgebase for more information on how to increase the value of this
parameter.
Known Issues and Limitations
43
A.2
Limitations
Š The Managed System Entitlement and Account Summary report displays inaccurate data for the
following two components:
Š Number of Logical Systems
Š Account Entitlement Number of Assigned Accounts
For example, if there are ‘n’ number of Logical Systems, the report displays ‘n+1’ number of
Logical Systems. If there are ‘n’ Account tracking identifiers and ‘m’ Accounts, the report displays
‘m*n’ Accounts.
Š The driver displays User is unassociated exception while performing modify and delete
operations with only dest-dn because these operations are not supported without providing
user association.
44
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
B
Driver Properties
B
This section provides information about the Driver Configuration and Global Configuration Values
properties for the JDBC driver and the Fan-Out driver. These are the only unique properties for
drivers. All other driver properties (Named Password, Engine Control Values, Log Level, and so forth)
are common to all drivers. Refer to “Driver Properties” in the NetIQ Identity Manager Driver
Administration Guide for information about the common properties.
The information is presented from the viewpoint of iManager. If a field is different in Designer, it is
marked with a Designer icon.
B.1
Driver Configuration
In iManager:
1 Click
to display the Identity Manager Administration page.
2 Open the driver set that contains the driver whose properties you want to edit:
2a In the Administration list, click Identity Manager Overview.
2b If the driver set is not listed on the Driver Sets tab, use the Search In field to search for and
display the driver set.
2c Click the driver set to open the Driver Set Overview page.
3 Locate the driver icon, then click the upper right corner of the driver icon to display the Actions
menu.
4 Click Edit Properties to display the driver’s properties page.
By default, the Driver Configuration page displays.
In Designer:
1 Open a project in the Modeler.
2 Right-click the driver icon or line, then select click Properties > Driver Configuration.
The Driver Configuration options are divided into the following sections:
B.1.1
Driver Module
The driver module changes the driver from running locally to running remotely or the reverse.
Java: Use this option to specify the name of the Java class that is instantiated for the shim
component of the driver. This class can be located in the classes directory as a class file, or in the
lib directory as a .jar file. If this option is selected, the driver is running locally. Select this option to
run the driver locally.
The Java class name is: com.netiq.idm.driver.fanoutshim.FanoutDriverShim.
Native: This option is not used with the JDBC Fan-Out driver.
Connect to Remote Loader: This option is not valid for this driver.
Driver Properties
45
Name: Displays the java class name.
IMPORTANT: Although Driver Object Password option is editable, this parameter is not applicable
for the Fan-Out driver.
B.1.2
Authentication
The authentication section describes the parameters required for authentication to the connected
Active MQ.
Connection Information (Designer only): Specify the IP address or name of the server the
application shim should communicate with.
Driver Cache Limit (kilobytes): Specify the maximum event cache file size (in KB). If it is set to
zero, the file size is unlimited. select Unlimited option to set the file size to unlimited in Designer.
IMPORTANT: Although Application Authentication ID and Set Password options are editable,
these parameters are not applicable for the Fan-Out driver.
The Remote Loader options do not apply to the Fan-Out driver. This driver uses the Fan-Out agent
component to create multiple JDBC Fan-Out driver instances.
B.1.3
Startup Option
The Startup Option section allows you to set the driver state when the Identity Manager server is
started.
Auto start: The driver starts every time the Identity Manager server is started.
Manual: The driver does not start when the Identity Manager server is started. The driver must be
started through Designer or iManager.
Disabled: The driver has a cache file that stores all of the events. When the driver is set to Disabled,
this file is deleted and no new events are stored in the file until the driver state is changed to Manual
or Auto Start.
B.1.4
Driver Parameters
The Driver Parameters section lets you configure the driver-specific parameters. When you change
driver parameters, you tune driver behavior to align with your network environment.
The parameters are presented by category:
Driver Settings
Fanout transport related parameters: Select Show to view the transport related parameters for
Fan-Out driver.
Show Subscriber Event Queue parameters: Select Show to view the Subscriber event
parameters. The options are:
Š SEND: The driver uses this queue for sending the Subscriber events to the Fan-Out agent.
Š RECV: The driver uses this queue for receiving the Subscriber events from the Fan-Out agent.
46
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
Š DELAYED RECV: This driver uses this queue for receiving the delayed Subscriber events from
the Fan-Out agent.
Show Configuration Queue Parameters: Select Show to view the configuration queue parameters.
The options are SEND and RECV.
Show Query-in Queue Parameters: Select Show to view the query-in queue parameters. The
options are SEND and RECV.
Show Query-out Queue Parameters: Select Show to view the query-out queue parameters. The
options are SEND and RECV.
Show Other Parameters: Select Show to view the additional parameters.
Š Configuration batch size: Specify the batch size for the driver configuration document. The
value is from 1 - 99999.
Š Show Fanout Parameters: Select Show to view the fan-out connection related information
such as Fan-Out agent password, configuration information, Fan-Out agent shim password.
Š Fanout Shim Password: Specify the password for the Fan-Out driver shim. After successful
authentication, the FanOut Agent loads/creates the driver instances of the specified shim class
name.
Š Fanout Agent Password: Specify the password of Fan-Out agent you are connecting to. The
Fan-Out agent establishes connection only after a valid authentication.
Š Encryption Key: Specify the key to encrypt/decrypt the sensitive data before sending to the
message queue(s).
Š AMQ Keystore Key: Specify the full path to the keystore file.
Š AMQ Keystore Password: AMQ Keystore Password: Specify the keystore password.
Š AMQ Truststore Path for SSL Certs: Specify the full path to the truststore file.
Š AMQ Truststore Password: Specify the truststore password.
Š Fanout Shim classname: Specify the driver shim classname that the Fan-Out agent loads
when you start the a Fan-Out driver.
Š Matching Attributes: The Fan-Out agent uses Matching Attributes to match the objects in the
delayed add events. This parameter must be schema-mapped equivalent of the attributes that
are used in the object matching policy. If you are using different attributes, specify the attribute
names according to the connected system schema.
Normal JDBC Driver Settings
For the normal JDBC driver setting, see Driver Parameters from the JDBC Driver Guide.
Subscriber Settings
Disable Subscriber: Select no (default) to allow flow of events from Identity Manager engine to the
connected database.
Show primary key parameters: Select Show if you want to configure the primary key parameters.
Š Generation/retrieval method (table-global): Select the desired option to generate/retrieve the
primary key values. This setting is global for all tables and views. The options are as follows:
Š subscription event (default)
Driver Properties
47
Š subscriber-generated
Š auto-generated / identity column
Š Retrieval timing (table-global): Select the desired option to retrieve the primary key value.
This setting is global for all tables and views. The options are:
Š before row insertion (default)
Š after row insertion
Š Method and timing (table-global): Specify how and when the primary key values are
generated or retrieved on a per table or view basis. This parameter overrides global method and
timing settings. Use semicolon, comma, or space as the delimiter for multiple values. For
example: usr("?=indirect.proc_idu()"); grp("indirect.proc_idg(idg)").
Disable statement-level locking: Select the appropriate option to disable statement locking. This
option determines if explicit locking or database resources are disabled on the Subscriber channel.
The value is set to no (default) by default.
Check update counts: Select yes (default) to enable the Subscriber channel to check for any
updates after any of the insert, update, or delete statements are executed against the tables. This
option ensures that the statements are resulting in updating the database. The value is set to yes
(default) by default.
B.1.5
ECMA Script
Displays an ordered list of ECMAScript resource files. The files contain extension functions for the
driver that Identity Manager loads when the driver starts. You can add additional files, remove existing
files, or change the order the files are executed.
B.1.6
Global Configuration
Displays an ordered list of Global Configuration objects. The objects contain extension GCV
definitions for the driver that Identity Manager loads when the driver is started. You can add or
remove the Global Configuration objects, and you can change the order in which the objects are
executed.
B.2
Global Configuration Values
Global configuration values (GCVs) are values that can be used by the driver to control functionality.
GCVs are defined on the driver or on the driver set. Driver set GCVs can be used by all drivers in the
driver set. Driver GCVs can be used only by the driver on which they are defined.
The Fan-Out driver includes several predefined GCVs. You can also add your own if you discover you
need additional ones as you implement policies in the driver.
To access the driver’s GCVs in iManager:
1 Click
to display the Identity Manager Administration page.
2 Open the driver set that contains the driver whose properties you want to edit:
2a In the Administration list, click Identity Manager Overview.
2b If the driver set is not listed on the Driver Sets tab, use the Search In field to search for and
display the driver set.
2c Click the driver set to open the Driver Set Overview page.
48
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
3 Locate the driver icon, click the upper right corner of the driver icon to display the Actions menu,
then click Edit Properties.
or
To add a GCV to the driver set, click Driver Set, then click Edit Driver Set properties.
To access the driver’s GCVs in Designer:
1 Open a project in the Modeler.
2 Right-click the driver icon
or line, then select Properties > Global Configuration Values.
or
To add a GCV to the driver set, right-clickthe driver set icon
, then click Properties > GCVs.
The global configuration values are organized as follows:
Š Section B.2.1, “Global Configuration Values,” on page 49
Š Section B.2.2, “Managed System Information,” on page 49
Š Section B.2.3, “Entitlements,” on page 51
Š Section B.2.4, “Account Tracking,” on page 52
Š Section B.2.5, “Password Synchronization,” on page 53
Š Section B.2.6, “JDBC Fan-Out Common,” on page 53
B.2.1
Global Configuration Values
The following global configuration values are used for database options and base configuration
options.
JDBC connection URL format used: Specify the connection URL format used for the JDBC driver
to connect to the databases. Use '<HOST>','<PORT> and '<DB>' tokens to specify the location of
host's IP address, port and database/SID in the connection URL.
NOTE
Š The tokens are case-sensitive and angle-brackets are mandatory since they are used as
delimiters.
If you use the same Fan-Out driver to connect oracle pluggable database and oracle traditional
database, the url template of the databases should be separated using a comma. For example:
jdbc:oracle:thin:@<HOST>:<PORT>/<DB>, jdbc:oracle:thin:@<HOST>:<PORT>:<DB>
Synchronization model: Select the synchronization model. The synchronization options are: Direct
and Indirect. Direct synchronization uses views to synchronize directly to existing tables of arbitrary
structure. Indirect synchronization synchronizes to intermediate staging tables with a particular
structure.
UserName Column: Specify the exact column name of the usr table that store the usernames.
B.2.2
Managed System Information
These settings help the Identity Reporting Module function to generate reports. There are different
sections in the Managed System Information tab.
Driver Properties
49
General Information
Name: Specify a descriptive name for the managed system.
Description: Specify a brief description of the managed system.
Location: Specify the physical location of the managed system.
Vendor: Specify the vendor of the managed system.
Version: Specify the version of the managed system.
System Ownership
Business Owner: Browse to and select the business owner in the Identity Vault for the connected
application. You must select a user object, not a role, group, or container.
Application Owner: Browse to and select the application owner in the Identity Vault for the
connected application. You must select a user object, not a role, group, or container.
System Classification
Classification: Select the classification of the connected application. This information is displayed in
the reports. The options are:
Š Mission-Critical
Š Vital
Š Not-Critical
Š Other
If you select Other, you must specify a custom classification for the connected application.
Environment: Select the type of environment the connected application provides. The options are:
Š Development
Š Test
Š Staging
Š Production
Š Other
If you select Other, you must specify a custom classification for the connected application.
Connection and Miscellaneous Information
Connection and miscellaneous information: This set of options is always set to hide, so that you
don’t make changes to these options. These options are system options that are necessary for
reporting to work.
JDBC Fan-Out Instances Information
These settings help to configure the Managed System Service related details of each JDBC FanOut
instance. To create a new instance, click the plus sign and fill in the following information:
Š JDBC FanOut Instance Name: Specify the descriptive name of the new logical instance of the
managed system.
50
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
Š Show other configuration values: Select Show to display additional information related to the
FanOut instance. For more information, see Section B.2.2, “Managed System Information,” on
page 49.
Š Connection and miscellaneous information: Select Show to display the system options. The
options are:
Š Instance ID
Š Authentication IP Address
Š Authentication Port
Š Authentication ID
Š Database Schema
Š Type
NOTE: The connection information options are auto-generated and always set to hide.
B.2.3
Entitlements
There are multiple sections in the Entitlements tab. Depending on which packages you installed,
different options are enabled or displayed.
Entitlements
Account Entitlement Value: Specify the entitlement value to assign for user account during the
account creation. Role Based Provisioning Module displays this value to the user during account
provisioning.
Use Entitlements to Control DB Accounts: Select True to enable the driver to manage database
accounts based on the driver’s defined entitlements. Select False to disable management of
database accounts based on the entitlements.
Use Group Entitlement: Select True to enable the driver to manage group membership based on
the driver’s defined entitlements.
Allow Login Disabled in Subscriber Channel: Select True to enable the driver to control the flow
of Login Disabled attribute in the Subscriber Channel and only on a regular attribute change.
Advanced Settings: Entitlement options that allow or deny additional functionality like data
collection, role mapping, resource mapping, parameter format, and entitlement extensions. Leave
these settings as default.
Data Collection
Data collection enables the Identity Report Module to gather information to generate reports. For
more information, see the Using Identity Manager 4.5 Reports.
Enable data collection: Select Yes to enable data collection for the driver through the Data
Collection Service by the Managed System Gateway driver. If you are not going to run reports on data
collected by this driver, select No.
Allow data collection from user accounts: Select Yes to allow data collection by the Data
Collection Service for the user accounts.
Allow data collection from groups: Select Yes to allow data collection by the Data Collection
Service for groups.
Driver Properties
51
Role Mapping
The Identity Manager Catalog Administrator allows you to map business roles with IT roles. For more
information, see the NetIQ Identity Manager Catalog Administrator User Guide.
Enable role mapping: Select Yes to make this driver visible to the Catalog Administrator.
Allow mapping of user accounts: Select Yes if you want to allow mapping of user accounts in the
Role Mapping Administrator. An account is required before a role, profile, or license can be granted
through Catalog Administrator.
Allow mapping of groups: Select Yes if you want to allow mapping of groups in Catalog
Administrator.
Resource Mapping
The Roles Based Provisioning Module allows you to map resources to users. For more information,
see the NetIQ User Application: User Guide.
Enables resource mapping: Select Yes to make this driver visible to the Roles Based Provisioning
Module.
Allow mapping of user accounts: Select Yes if you want to allow mapping of user accounts in the
Roles Based Provisioning Module. An account is required before a role, profile, or license can be
granted.
Allow mapping of groups: Select Yes if you want to allow mapping of groups in the Roles Based
Provisioning Module.
Parameter Format
Format for Account entitlement: Specify the parameter format the entitlement agent must use
when granting the user account entitlement. The options are Identity Manager 4 and Legacy.
Format for Group entitlement: Specify the parameter format the entitlement agent must use when
granting the group entitlement. The options are Identity Manager 4 and Legacy.
Entitlements Extensions
User account extension: Specify the user account extension. The content of this field is added
below the entitlement elements in the EntitlementConfiguration resource object
Group extensions: Specify the group extensions. The content of this field is added below the
entitlement elements in the EntitlementConfiguration resource object
B.2.4
Account Tracking
The following controls the Account tracking is part of the Identity Reporting Module. For more
information, see the Using Identity Manager 4.5 Reports.
Enable Account Tracking: Set this to True to enable account tracking policies for the Fan-Out
driver. Set it to False if you do not want to execute account tracking policies.
Š Object class
Š Realm
52
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
Š Identifiers for Account
Š Status Attribute
Š Status active value
Š Status inactive value
Š Subscription default status
Š Publication default status
B.2.5
Password Synchronization
The following GCVs control password synchronization for the Fan-Out driver. For more information,
see the NetIQ Identity Manager Password Management Guide.
Application Accepts Passwords from Identity Manager: If this option is set to True, the driver
allows passwords to flow from the Identity Manager data store to the connected server.
Identity Manager Accepts Passwords from the Application: If this option is set to True, it allows
passwords to flow from the connected system to Identity Manager.
Publish Passwords to NDS Password: Use the password from the connected system to set the
non-reversible NDS password in the Identity Vault.
Publish Passwords to Distribution Password: Use the password from the connected system to
set the NMAS Distribution Password used for Identity Manager password synchronization.
Require passwords policy validation before publishing passwords: Select True to apply NMAS
password policies when publishing passwords. Password is not written to the data store if it does not
comply.
Reset user’s external system password to the Identity Manager password on failure: If this
option is set to True, and the Distribution Password fails to distribute, attempt to reset the password in
the connected system by using the Distribution Password from the Identity Manager data store.
Notify the user of password synchronization failure via e-mail: If this option is set to True, notify
the user by e-mail of any password synchronization failures.
Connected System or Driver Name: Specifies the name of the connected system, application or
Identity Manager driver. This value is used by the e-mail notification templates to identify the source
of notification messages.
In Designer, you must click the icon next to a GCV to edit it. This displays the Password
Synchronization Options dialog box for a better view of the relationship between the different GCVs.
In iManager, you should edit the Password Management Options on the Server Variables tab rather
than under the GCVs. The Server Variables page has a better view of the relationship between the
different GCVs.
B.2.6
JDBC Fan-Out Common
Allow ‘Group add’ in Fanout mode: This GCV controls the creation of groups in the Subscriber
channel. By default, this is Disabled. The driver vetoes the group add operations. Enabling this
option allows the driver to send the group add events to each of the JDBC instances configured by
the driver.
Driver Properties
53
Synchronize the first or the last replica value: Select the appropriate option to synchronize the
first or last replica value of multi-valued attributes mapped to single-valued columns. The options are:
First and Last.
54
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
C
REST Endpoints
C
Table C-1 on page 55 lists the endpoints that the Fan-Out agent exposes for performing basic
monitoring and management tasks.
Table C-1 REST endpoints
Path
Method
/fanoutagent/config PUT
Parameter(s)
Description
{
Used to set or update the
parameter values for the
Fan-Out agent.
“KEY”:”VALUE”,
…
}
Key-value pair of the
parameters received
through the GET method
call to this endpoint (refer
(3))
/fanoutagent/config GET
{}
None
/fanoutagent/
config/setpassword
PUT
Clients to this endpoint
should provide the
changed/modified value
pairs only.
Password updates cannot
be done through this
endpoint. Due to the
alternate handling of
sensitive data, different
endpoints are available for
password updates.
Provides the current
configuration values of the
Fan-Out agent.
{
Used to set the agent and
the shim password on the
“OLD_SHIM_PASSWD”:”. Fan-Out agent.
..”,
NOTE: Both the password
“NEW_SHIM_PASSWD”:” pairs must be provided.
...”,
Otherwise, the agent
might be locked down that
“OLD_AGENT_PASSWD”
can result in an error at
:“”,
startup. This is because
“NEW_AGENT_PASSWD one of the passwords is
used for encrypting the
”:“”
other and hence the
}
dependency.
All the values must be
provided
There are no endpoints for
fetching the password.
REST Endpoints
55
Path
Method
Parameter(s)
Description
/fanoutagent/
config/
setkspassword
PUT
{
Sets the keystore
password for the
command server.
“PASSWORD”:“...”
}
The keystore contains a
self-signed certificate
created by the Fan-Out
agent at the initial startup.
A user provided keystore
with a certificate can also
be used.
The certificate is used for
securing the endpoint
transport. An option exists
to disable the SSL, which
is not the recommended/
default option.
/fanoutagent/
service
GET
{}
None
Retrieves the list of
connected system
services (shims) in the
Fan-Out agent.
Both running and stopped
shims are reported in the
response of this endpoint.
/fanoutagent/
service/{state}
GET
{}
None
Possible values for state
are RUNNING or
STOPPED
/fanoutagent/
service/cmd/stop/
{serviceId}
PUT
{}
None
Provides the list of
connected system
services (shims) in the
Fan-Out agent based on
the service state.
NOTE: Legal values are
RUNNING and
STOPPED.
Used to start a currently
stopped service.
ServiceId returned by the
GET service endpoint
/fanoutagent/
service/cmd/start/
{serviceId}
PUT
{}
None
ServiceId returned by the
GET service endpoint
56
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
Used to start a currently
stopped service.
Path
Method
Parameter(s)
Description
/fanoutagent/
shutdown
PUT
{}
Used to shutdown a FanOut agent instance.
None
NOTE: When this
endpoint is invoked, the
agent instance will
shutdown.
This means that all further
communication with the
agent will cease.
Further communication
will resume only after the
agent is started by logging
into the computer hosting
the agent.
/config/
setEncryptionkey
REST Endpoints
57
58
NetIQ Identity Manager Driver for JDBC Fan-Out Implementation Guide
">