SAP NetWeaver Identity Management Virtual Directory Server. Tutorial. Version 7.0 Rev 3. - Accessing databases

Transcription

1 SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases Version 7.0 Rev 3

2 SAP Library document classification: PUBLIC No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft, Windows, Outlook, Excel, and PowerPoint are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iseries, pseries, xseries, zseries, System i, System i5, System p, System p5, System x, System z, System z9, z/os, AFP, Intelligent Miner, WebSphere, Netfinity, Tivoli, Informix, i5/os, POWER, POWER5, POWER5+, OpenPower and PowerPC are trademarks or registered trademarks of IBM Corporation. Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation. UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group. Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc. HTML, XML, XHTML, and W3C are trademarks or registered trademarks of W3C, World Wide Web Consortium, Massachusetts Institute of Technology. Java is a registered trademark of Sun Microsystems, Inc. JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. MaxDB is a trademark of MySQL AB, Sweden. SAP, R/3, mysap, mysap.com, xapps, xapp, SAP NetWeaver, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves information purposes only. National product specifications may vary. These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

3 i Preface The product The SAP NetWeaver Identity Management Virtual Directory Server can logically represent information from a number of disparate directories, databases, and other data repositories in a virtual directory tree. Different users and applications can, based on their access rights, get different views of the information. Features like namespace conversion and schema adaptations provide a flexible solution that can continually grow and change to support demands from current and future applications, as well as requirements for security and privacy, without changing the underlying architecture and design of data stores like databases and directories. The reader This manual is written for people who use the Virtual Directory Server to access a database. Prerequisites To get the most benefit from this tutorial, you should have the following knowledge: Basic knowledge of LDAP. Basic knowledge of Java. Basic knowledge of databases. The following software is required: SAP NetWeaver Identity ManagementVirtual Directory Server version 7.0 or newer, correctly installed and licensed. The source files for this tutorial: The mvd-db.xml configuration file with a minimum configuration for the Virtual Directory Server. The tutorial database that is installed with the product. The manual This document contains a tutorial for accessing a database with the Virtual Directory Server. This tutorial uses an Apache Derby database, but you could access any database system as long as you have a JDBC driver. You see how you configure the database as a data source and create a virtual tree where the data source is referenced. You also see how you can use the internal LDAP browser to view the contents of the virtual directory. The tutorial also contains a section where we look more closely at the operation log.

4 ii Related documents You can find useful information in the following documents: The X.500 standard, which can be ordered from LDAP v. 2, RFC1777, "Lightweight Directory Access Protocol". LDAP v. 3, RFC 2251, "Lightweight Directory Access Protocol (V3)". RFCs and Internet drafts can be downloaded from

5 iii Table of contents Introduction... 1 Verifying the configuration of the Virtual Directory Server...1 Adding the JDBC driver to the classpath...2 Section overview...3 Section 1: Starting the database server and opening the configuration file... 4 Starting the database server...4 Defining the LDAP mapping...5 Opening the server configuration...6 Section 2: Adding the data source... 8 Section 3: Creating the virtual tree Renaming the virtual tree...17 Adding the static node...18 Adding the data source node...19 Defining access control...20 Section 4: Running the server Specifying port number...21 Enabling the operation log...22 Starting the server...23 Section 5: Viewing the operation log Interpreting the log...25

6 iv

7 Introduction 1 Introduction The purpose of this tutorial is to show how you can access a database from the Virtual Directory Server. You will see how you define the database as a data source and create a virtual tree to display the contents of the database. The tutorial and the necessary files are installed in a sub-directory below the product installation directory. For a default installation on Microsoft Windows, the tutorial will be located in C:\Program Files\SAP\IdM\Virtual Directory Server\Tutorials. The tutorial includes the following files: The configuration file mvd-db.xml. Copy this file to a directory where you can access it from the Virtual Directory Server before you start working with the configuration so that you can repeat this tutorial if you wish to do so. The sub-directory \maxdata contains the database that is used as a data source. This is an Apache Derby database ( It must be started as a server to accept multiple connections. Verifying the configuration of the Virtual Directory Server When you installed the Virtual Directory Server, you specified the location of the Java runtime environment. In this tutorial, you need to compile a Java class. To be able to do this, a Java compiler is required. If necessary, you can download a compiler from (version 1.5). The configuration may look like this when choosing Tools/Options :

8 2 Introduction Adding the JDBC driver to the classpath The JDBC driver for Apache Derby is installed with the Virtual Directory Server. In a default installation, this will be located in the directory C:\Program Files\SAP\IdM\Virtual Directory Server\JDBCdrivers. If the driver is not already in classpath, you need to add it: 1. Choose Tools/Options... and select the "Classpath" tab: 2. Choose "Add file..." and browse to the directory where the JDBC driver is installed. Add the files derby.jar, derbyclient.jar and derbynet.jar. 3. Choose "Open". 4. Choose "OK" to close the dialog box.

9 Introduction 3 Section overview The tutorial consists of the following sections: Section 1: Starting the database server and opening the configuration file Section 2: Adding the data source Section 3: Creating the virtual tree Section 4: Running the server Section 5: Viewing the operation log In this section we will start the database server, see how the database columns are mapped to LDAP attributes and open the configuration file This section describes how you configure the connection to data source. Here we create the nodes in the virtual tree where we reference the data source. Finally, we start the server and view the contents of the data source. In this section we will take a closer look at the operation log.

10 4 Section 1: Starting the database server and opening the configuration file Section 1: Starting the database server and opening the configuration file In this section you will start the database server and see how the columns in the database are mapped to LDAP attributes. We will also open the configuration file. Starting the database server The database that is used in this tutorial is an Apache Derby database. It contains a table "Employees" with the MaXdata employees. Note: This shows the Microsoft Access version of the database, but the contents are the same. To start the database server: 1. Choose Programs/SAP Identity Management/Virtual Directory Server/Start tutorial database from the Start menu. A status window is displayed where you verify that the server started successfully, and you can monitor the connections to the database:

11 Section 1: Starting the database server and opening the configuration file 5 Defining the LDAP mapping The columns in the database do not match the LDAP attributes in the clients' requests. There are several ways to perform this mapping in the Virtual Directory Server. In this case, the mapping is performed as part of the data source configuration. The table below shows the columns in the database and suggested LDAP attributes. The rows with no value in the "MaXdata database" column are LDAP attributes that have been requested by the client, but that are not included in the database. They need to be constructed during the processing in the Virtual Directory Server. This table is used when defining the conversion on page 15 and 16. MaXdata database LDAP attribute Comments EmployeeID Lastname Firstname Title Dep Location Tel Fax uid sn givenname title ou l telephonenumber facsimiletelephonenumber mail objectclass RDN displayname This will be set to "inetorgperson" for all entries. This will be "uid=employeeid" for all entries. "FirstName"+"Lastname"

12 6 Section 1: Starting the database server and opening the configuration file Opening the server configuration To open the configuration file: 1. Start the Virtual Directory Server by choosing Programs/SAP NetWeaver Identity Management/Virtual Directory Server from the Start menu. 2. Choose File/Open. The "Open server configuration" dialog box is displayed: Select the configuration file mvd-db.xml that accompanies this tutorial.

13 Section 1: Starting the database server and opening the configuration file 7 3. Expand the tree by selecting the top node and choosing "Collapse/Expand" in the toolbar. The expanded configuration tree looks like this: Note: The appearance of the user interface depends on what you have chosen in View/Look & Feel. This screen shot shows the "MaXware" Look & Feel.

14 8 Section 2: Adding the data source Section 2: Adding the data source In this section, you use the configuration file accompanying this tutorial for some initial configuration that is necessary to make this configuration work. To add the database as a data source: 1. Select the entry "Singles" below "Data sources" and choose "New..." from the context menu. The "Select template" dialog box is displayed: Select "Database" in the "Group" list and "Generic Database" in the "Template" list. 2. Choose "OK" to open the "Generic Database template" wizard.

15 Section 2: Adding the data source 9 3. Choose the " " button to the right of the "Database" field to open the "JDBC URL wizard". Locate and select "Apache Derby" in the list. 4. Choose "Next >". Fill in the information for the database. Enter maxdata both as database name, user name and password. 5. Choose "Next >" and then "Finish" to complete the wizard. 6. Choose "OK" to close the "Generic Database template" dialog box.

16 10 Section 2: Adding the data source The "Database properties" dialog box is displayed: Fill in the fields with the following values: Enable Enable the data source. Display name Enter a display name for the data source. Unique name Enter a unique name for the data source.

17 Section 2: Adding the data source Select the "Database" tab: The values you specified in the JDBC URL wizard are filled in. 8. Choose "Get database schema" to verify that you can access the database.

18 12 Section 2: Adding the data source The "Available attributes" dialog box is displayed. Select the "Employees" table to display all columns. 9. Choose "OK" to return to the "Database properties" dialog box. "EMPLOYEES" is selected in the "Scope" list. Choose "None" as "Size limit type" as the Derby database does not support size limit.

19 Section 2: Adding the data source Select the "Data source attributes" tab: Fill in the fields with the following values: Attributes Select "Accept only data source attributes" to specify that only the attributes in the attribute list are accepted when the Virtual Directory Server processes the incoming LDAP request. In LDAP filter Select "Accept all available data source attributes" to specify that all attributes in the attribute list are accepted in the filter part of the LDAP request. Ignore filtering on following LDAP attributes Most LDAP clients use the "objectclass" attribute for filtering. Since there is no "objectclass" attribute (column) in the database, this attribute must be ignored when the Virtual Directory Server creates the SQL query. Select "Ignore filtering on selected attributes". Make sure that the "objectclass" attribute is in the attribute list.

20 14 Section 2: Adding the data source 11. Choose "Define..." to open the "Define parameters" dialog box: You use this dialog box to construct a distinguished name (DN) by using the attribute EmployeeID as a user-id type DN. In this way, we build a unique identifier for the user information that is contained in this database. Note that two or more fields and/or constant values can be combined to construct a DN for example Firstname + Lastname + example.com. In this case, we select "UID=" in the "Attribute types" list and "EMPLOYEEID" in the list of "Available attributes" to construct a DN for the users in this database. Choose "Add attribute". The fields in the "Constructed parameters" group box are filled in. 12. Choose "OK" to close the dialog box and return to the "Database properties" dialog box.

21 Section 2: Adding the data source Select the "Conversion from" tab: Fill in the fields with the following values: Select "Enable conversion from internal attributes". Select "Add all data source attributes" to fill in the "To" column with all attributes from the data source. Add all attribute pairs from the table on page 5. Select the value in the "LDAP attribute" column in the "From" list. If you do not find the attribute name in the list (for instance uid), you can enter it manually. Note: The order of the attributes is not significant.

22 16 Section 2: Adding the data source 14. Select the "Conversion to" tab: Select "Enable conversion to internal attributes". Import the conversions by choosing "Synchronize". 15. Choose "OK" to close the dialog box. The configuration of the database is now complete.

23 Section 3: Creating the virtual tree 17 Section 3: Creating the virtual tree We are now going to create the virtual tree where we reference the data source we just created. Nodes in the virtual tree are referenced by their qualified name. A node's qualified name includes the relative distinguished name (RDN) of all nodes above it in the virtual tree, starting with the top node. The RDNs are separated by the / character. For instance: o=myorg/mydep/* Renaming the virtual tree The configuration file contains a default tree which we are going to rename: 1. Select "Tree 1" in the configuration tree and choose "Properties..." from the context menu: Name the tree MaXdata. 2. Choose "OK" to close the dialog box.

24 18 Section 3: Creating the virtual tree Adding the static node The tree consists of a static node that represents the o= level in the virtual tree. This node does not reference any data source. To add the static node: 1. Select the "MaXdata" tree and choose "New..." from the context menu: Fill in the fields with the following values: Enable Select "Enable" to enable the node. Relative DN Enter o=maxdata as the node's DN. It is not necessary that the DN is the same as the name of the data source. Object class Select "organization" as the node's object class. This matches the object class of the DN we specified. 2. Choose "OK" to close the dialog box.

25 Section 3: Creating the virtual tree 19 Adding the data source node Then we will add the node that references the data source: 1. Select the node o=maxdata and choose "New..." from the context menu: Fill in the fields with the following values: Relative DN Enter * as the node's relative distinguished name. This should match all possible DNs on this level. Source Select the data source "MaXdata" in the list. Object class Select "inetorgperson" as the object class for the entries that are returned to the client. 2. Select the "Advanced" tab: Disallow one-level search This is a leaf node that does not have any sub-entries. Select this check box to specify that the clients are not allowed to perform one-level searches on this node.

26 20 Section 3: Creating the virtual tree Disallow exact sub-tree search For the same reason, select this check box to specify that the clients are not allowed to perform exact sub-tree searches on this node. 3. Choose "OK" to close the dialog box. Defining access control The configuration file contains two user groups. We will use one of them to give clients that connect anonymously read access to the virtual tree. Note: Make sure you select the correct node to specify access control. 1. View the properties of the node o=maxdata and select the "Access control list" tab: Select "Anonymous" in the "User group" list and "ReadAccess" in the "Rule" list. 2. Choose "OK".

27 Section 4: Running the server 21 Section 4: Running the server The configuration is now complete and we can run the server. Specifying port number Before we can run the server, you have to specify the port number the server is going to use. This is specified as part of the deployment configuration. 1. Expand the "Deployments" node and view the properties of the "main_listener" LDAP deployment: Enter a port number that is not used by any other service, here we use 7015 as the port number. 2. Choose "OK".

28 22 Section 4: Running the server Enabling the operation log It can be useful to be able to see any log messages when the server is running, so we enable the operation log: 1. Choose Configure/Logging/Operation log... Select "DEBUG" both as general log level and as log level for extensions. 2. Choose "OK".

29 Section 4: Running the server 23 Starting the server Start the server by choosing the "Start" button in the toolbar. The indicator in the status bar turns green when the server is started. You can use the internal LDAP client to access the virtual directory. You can either use the LDAP client that is part of the utility panel in the main window. You can also start a separate LDAP browser: 1. Choose Tools/Browse LDAP... to open the LDAP browser: 2. Start the wizard by choosing "Wizard " to the right of the "Starting point" field: Fill in the fields: Host name Enter localhost.

30 24 Section 4: Running the server Port number Enter the port number you specified for the server, here Search type Select a search type in the list. 3. Choose "OK" to return to the LDAP browser. The LDAP URL is displayed in the "Starting point" field. 4. Choose "Search" to start the search: 5. Close the browser window when you are finished.

31 Section 5: Viewing the operation log 25 Section 5: Viewing the operation log The Virtual Directory Server's operation log can be used to monitor the server, both for troubleshooting purposes and to view the daily operation. Interpreting the log We are now going to see which messages are written to the log. The log excerpt below is based on the following search from the internal LDAP browser: Note: Using different LDAP clients and/or search criteria may produce other log messages.

32 26 Section 5: Viewing the operation log 1. Perform the search and view the log by choosing the "Operation" button in the toolbar. To avoid the log refreshing select the "Toggle auto-refresh" button in the toolbar. Then you can scroll to the top of the log. The operation log will look something like this: Some lines are longer than can be displayed. You can view the complete log lines in the details window. From the log information we see that the client is assigned the user group "Anonymous". The log describes each phase in the processing of the request: The above lines show that the incoming request is a sub-tree search followed by a list of attributes. These are the attributes requested by the client. In this case all attributes are requested. The next line shows the search filter (i.e. the attributes from the search criterion). The following two lines show the result of user group conversions. In this case, there is no change, as no user group conversion is defined. In this phase, each node in the virtual tree is processed. The processing is first performed based on the rule found for this user group on the node (or any parent node). Afterwards, they are processed based on the data source properties.

33 Section 5: Viewing the operation log 27 The excerpt shows how the search is performed on the data source. This section of the operation log will contain any (debug) messages from the Java classes. In this phase we can see which attributes are returned, converted or removed before the search result is returned to the client. We also see how many entries were found from each node. This section shows the completion of the search operation. We see that 6 entries were found, and the result code was 0, which means success.

34 28 Section 5: Viewing the operation log