SAP NetWeaver® Identity Management
Virtual Directory Server
Tutorial
- Accessing databases
Version 7.2 Rev 1
© Copyright 2010 SAP AG. All rights reserved.
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, Excel, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation.
IBM, DB2, DB2 Universal Database, System i, System i5, System p, System p5, System x, System z, System z10,
System z9, z10, z9, iSeries, pSeries, xSeries, zSeries, eServer, z/VM, z/OS, i5/OS, S/390, OS/390, OS/400, AS/400,
S/390 Parallel Enterprise Server, PowerVM, Power Architecture, POWER6+, POWER6, POWER5+, POWER5,
POWER, OpenPower, PowerPC, BatchPipes, BladeCenter, System Storage, GPFS, HACMP, RETAIN, DB2 Connect,
RACF, Redbooks, OS/2, Parallel Sysplex, MVS/ESA, AIX, Intelligent Miner, WebSphere, Netfinity, Tivoli and
Informix are trademarks or registered trademarks of IBM Corporation.
Linux is the registered trademark of Linus Torvalds in the U.S. and other countries.
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.
SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP Business ByDesign, 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 other countries.
Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web
Intelligence, Xcelsius, and other Business Objects products and services mentioned herein as well as their respective
logos are trademarks or registered trademarks of Business Objects S.A. in the United States and in other countries.
Business Objects is an SAP company.
All other product and service names mentioned are the trademarks of their respective companies. Data contained in this
document serves informational 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.
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 Management Virtual Directory Server version 7.2 or newer,
correctly installed and licensed.
•
The source files for this tutorial:
•
The vds-db.xml configuration file with a minimum configuration for the Virtual
Directory Server.
•
Access to the Identity Center database with the HR_SAMPLE table.
The manual
This document contains a tutorial for accessing a database with the Virtual Directory Server.
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.
© Copyright 2010 SAP AG. All rights reserved.
ii
Related documents
You can find useful information in the following documents:
•
The X.500 standard, which can be ordered from http://www.itu.int.
•
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 http://www.ietf.org.
© Copyright 2010 SAP AG. All rights reserved.
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 ........................................................................................................................................2
Section 1: Opening the configuration file ........................................................................................ 3
Viewing the database contents ...................................................................................................................3
Defining the LDAP mapping .....................................................................................................................4
Opening the server configuration ...............................................................................................................5
Section 2: Adding the data source .................................................................................................... 7
Section 3: Creating the virtual tree ................................................................................................ 15
Renaming the virtual tree .........................................................................................................................15
Adding the static node..............................................................................................................................16
Adding the data source node ....................................................................................................................17
Defining access control ............................................................................................................................18
Section 4: Running the server ......................................................................................................... 19
Specifying port number ............................................................................................................................19
Enabling the operation log .......................................................................................................................19
Starting the server.....................................................................................................................................20
Section 5: Viewing the operation log .............................................................................................. 22
Interpreting the log ...................................................................................................................................22
© Copyright 2010 SAP AG. All rights reserved.
iv
© Copyright 2010 SAP AG. All rights reserved.
1
Introduction
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
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:\usr\SAP\IdM\Virtual Directory Server\Tutorials.
The tutorial includes the following files:
•
The configuration file vds-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.
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 http://java.sun.com.
The configuration may look like this when choosing Tools/Options…:
© Copyright 2010 SAP AG. All rights reserved.
2
Introduction
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
Adding the JDBC driver to the classpath
You need the JDBC driver for the Identity Center database, either Microsoft SQL Server or
Oracle. If the driver is not already in classpath, you need to add it:
1. Choose Tools/Options... and select the "Classpath" tab:
Add the correct JDBC driver to the list, if not already present.
2. Choose "OK" to close the dialog box.
Section overview
The tutorial consists of the following sections:
Section 1: Opening the configuration file
In this section we will see how the database columns
are mapped to LDAP attributes and open the
configuration file
Section 2: Adding the data source
This section describes how you configure the
connection to data source.
Section 3: Creating the virtual tree
Here we create the nodes in the virtual tree where we
reference the data source.
Section 4: Running the server
Finally, we start the server and view the contents of the
data source.
Section 5: Viewing the operation log
In this section we will take a closer look at the
operation log.
© Copyright 2010 SAP AG. All rights reserved.
3
Section 1: Opening the configuration file
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
Section 1: Opening the configuration file
In this section you will look at the contents of the database table and see how the columns in the
database are mapped to LDAP attributes. We will also open the configuration file.
Viewing the database contents
The database table that is used in this tutorial is the HR_Sample table in the Identity Center
database. It contains employee data for a number of employees:
© Copyright 2010 SAP AG. All rights reserved.
4
Section 1: Opening the configuration file
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
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 "HR_Sample 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 13 and 14.
HR_Sample database
LDAP attribute
EmployeeID
uid
Lastname
sn
Firstname
givenName
Title
title
Dep
ou
Location
l
Tel
telephoneNumber
Fax
facsimileTelephoneNumber
email
mail
Comments
objectclass
This will be set to "inetOrgPerson" for all
entries.
RDN
This will be "uid=EmployeeID" for all entries.
displayName
"FirstName"+"Lastname"
© Copyright 2010 SAP AG. All rights reserved.
5
Section 1: Opening the configuration file
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
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 vds-db.xml that accompanies this tutorial.
© Copyright 2010 SAP AG. All rights reserved.
6
Section 1: Opening the configuration file
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
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 "Default" Look & Feel.
© Copyright 2010 SAP AG. All rights reserved.
7
Section 2: Adding the data source
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
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.
© Copyright 2010 SAP AG. All rights reserved.
8
Section 2: Adding the data source
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
3. Choose the "…" button to the right of the "Database" field to open the "JDBC URL wizard".
Locate and select your database system in the list.
4. Choose "Next >".
Fill in the information for the database. Enter mxmc_db as database name, mxmc_rt as user
name and the password for the mxmc_rt user.
5. Choose "Next >" and then "Finish" to complete the wizard.
6. Choose "OK" to close the "Generic Database template" dialog box.
© Copyright 2010 SAP AG. All rights reserved.
9
Section 2: Adding the data source
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
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.
© Copyright 2010 SAP AG. All rights reserved.
10
Section 2: Adding the data source
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
7. 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.
The "Available attributes" dialog box is displayed. Select the "HR_Sample" table to display
all columns.
9. Choose "OK" to return to the "Database properties" dialog box.
© Copyright 2010 SAP AG. All rights reserved.
11
Section 2: Adding the data source
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
"HR_Sample" is selected in the "Scope" list.
10. Select the "Data source attributes" tab:
Fill in the fields with the following values:
© Copyright 2010 SAP AG. All rights reserved.
12
Section 2: Adding the data source
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
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.
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.
© Copyright 2010 SAP AG. All rights reserved.
13
Section 2: Adding the data source
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
12. Choose "OK" to close the dialog box and return to the "Database properties" dialog box.
13. Select the "Conversion from" tab:
Fill in the fields with the following values:
© Copyright 2010 SAP AG. All rights reserved.
14
Section 2: Adding the data source
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
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 4.
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.
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.
© Copyright 2010 SAP AG. All rights reserved.
15
Section 3: Creating the virtual tree
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
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 HR_Sample.
2. Choose "OK" to close the dialog box.
© Copyright 2010 SAP AG. All rights reserved.
16
Section 3: Creating the virtual tree
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
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 "HR_Sample" 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=HRSample 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.
© Copyright 2010 SAP AG. All rights reserved.
17
Section 3: Creating the virtual tree
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
Adding the data source node
Then we will add the node that references the data source:
1. Select the node o=HRSample 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 "HR_Sample" 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.
© Copyright 2010 SAP AG. All rights reserved.
18
Section 3: Creating the virtual tree
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
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=HRSample and select the "Access control list" tab:
Select "Anonymous" in the "User group" list and "ReadAccess" in the "Rule" list.
2. Choose "OK".
© Copyright 2010 SAP AG. All rights reserved.
19
Section 4: Running the server
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
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".
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".
© Copyright 2010 SAP AG. All rights reserved.
20
Section 4: Running the server
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
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.
© Copyright 2010 SAP AG. All rights reserved.
21
Section 4: Running the server
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
Port number
Enter the port number you specified for the server, here 7015.
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.
© Copyright 2010 SAP AG. All rights reserved.
22
Section 5: Viewing the operation log
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
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.
© Copyright 2010 SAP AG. All rights reserved.
23
Section 5: Viewing the operation log
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
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.
© Copyright 2010 SAP AG. All rights reserved.
24
Section 5: Viewing the operation log
SAP NetWeaver Identity Management Virtual Directory Server Tutorial - Accessing databases
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.
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.
© Copyright 2010 SAP AG. All rights reserved.