SAP NetWeaver Identity Management Virtual Directory Server. Tutorial. Version 7.0 Rev 3. - Using Virtual view

SAP NetWeaver

_{Identity Management}

Virtual Directory Server

Tutorial

- Using Virtual view

© Copyright 2008 SAP AG. All rights reserved. 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

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 want to use the Virtual Directory Server's VirtualView Java class.

Prerequisites

To get the most benefit from this manual, you should have the following knowledge: • Basic knowledge of LDAP.

• Basic knowledge of databases.

• Basic knowledge of Microsoft Access. • Basic knowledge of Java.

The following software is required:

• SAP NetWeaver Identity Management Virtual Directory Server version 7.0 or newer, correctly installed and licensed.

• A Java development environment. This can be downloaded from http://java.sun.com (version 1.5).

• Microsoft Access 2000.

• An LDAP client to view the information presented by the Virtual Directory Server. Different LDAP clients may yield different results.

• The source files for this tutorial:

• The MaXdata.mdb database that is the data source to be LDAP enabled.

• The mvd-virtualview.xml configuration file with the initial configuration for the Virtual Directory Server, including the Java classes necessary to access the database.

The manual

This document describes how you can use the custom Java class called "Virtual view" to create a virtual hierarchy from a database based on the values of one or more columns in the database.

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.

Table of contents

Introduction... 1

Verifying the configuration of the Virtual Directory Server...1

Section overview ...2

Section 1: Viewing the data source and opening the server configuration... 3

The MaXdata.mdb database ...3

Creating an ODBC System DSN...3

Defining the LDAP mapping ...4

Opening the server configuration ...5

Section 2: Adding the data source ... 7

Section 3: Creating the virtual tree ... 13

Renaming the default tree ...13

Creating the static nodes ...14

Creating the data source node ...17

Section 4: Running the server ... 21

Specifying the port number ...21

Running the server ...21

Viewing the virtual directory ...22

Section 5: Adding a display name... 23

Modifying the data source node ...23

Adding the attribute class ...24

Modifying the data source...26

Restarting the server...27

Section 6: Creating a two-level tree... 28

Creating the departments branch...29

Running the server ...35

Creating the locations branch ...36

Running the server ...41

Section 7: Considering search access ... 42

Configuration 1 ...43

Introduction

This tutorial describes how you use the custom Java class "Virtual view" to create a hierarchical view of a database based on the contents of columns in the database. You will define the data source, the nodes in the virtual tree and see how you can implement different access control policies.

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 (version 1.5).

The configuration may look like this when choosing Tools/Options…:

Section overview

The tutorial consists of the following sections: Section 1: Viewing the data source and opening

the server configuration

In this section you will view the contents of the database. You will also open the server configuration that contains the initial configuration.

Section 2: Adding the data source This section describes how you add and configure the data source.

Section 3: Creating the virtual tree In this section, you create the virtual tree with all the nodes necessary to build the structure of the virtual directory.

Section 4: Running the server Here, you run the server and use an LDAP client to view the contents of the virtual directory.

Section 5: Adding a display name This section explains how you can add a display name to the entries when they are returned to the client. Section 6: Creating a two-level tree In this section you extend the virtual tree with two

branches: one for departments and one for locations. Section 7: Considering search access This section discusses different methods to configure

Section 1: Viewing the data source and opening the server

configuration

The tutorial and the necessary files are installed in a sub-directory below the product installation directory. For a default installation, the tutorial will be located in

C:\Program Files\SAP\IdM\Virtual Directory Server\Tutorials.

You can either work with the files from this directory, or you can copy them to another directory, to be able to repeat the process.

The tutorial includes two files:

• The configuration file mvd-virtualview.xml. Copy this file to a directory where you can access it from the Virtual Directory Server.

• The database file MaXdata.mdb. Copy this file to the same directory as the

mvd-virtualview.xml file.

In this section, we look at the database. We also open the server configuration that contains the initial configuration.

The MaXdata.mdb database

This is a database with a table, "Employees", containing employee data. The table has the following layout:

Creating an ODBC System DSN

To be able to reference the data source, you need to create an ODBC System DSN for it. Use the "Data Sources (ODBC)" in the "Administrative Tools" group in the Control Panel. Name the data source "maxdata".

Choose "Help" in the "ODBC Data Source Administrator" for details about how you create a data source.

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 11 and 12.

MaXdata database LDAP attribute Comments

EmployeeID uid Lastname sn Firstname givenName Title title Dep ou Location l Tel telephoneNumber Fax facsimileTelephoneNumber email mail

objectclass This will be set to "inetOrgPerson" for all entries. RDN This will be "uid=EmployeeID" for all entries.

Opening the server configuration

Note:

The class file in this tutorial is an example of what can be done with Java classes. It is primarily written for the purpose of browsing. When searching it may not yield correct results according to the LDAP standard. The class can be enhanced to produce correct search results.

To open the server configuration:

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" dialog box is displayed:

Section 2: Adding the data source

The original configuration does not include any data sources. We will now add the MaXdata.mdb database as a single 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". The "Generic Database template" dialog box is displayed:

Use the URL wizard and create a JDBC URL with the ODBC JDBC driver to the "maxdata" DSN.

3. Choose "OK". The "Database properties" dialog box is displayed:

Fill in the following fields:

Enable

Enable the data source.

Display name

This name is used to identify the data source. In this case we are using the name of the database.

Unique name

4. Select the "Connectors" tab:

In most cases you can use the default connectors for the different data source types. These connectors contain the most common operations. If you need to functionality not contained in the default connectors, you can add your own Java classes to the configuration. In this tutorial we are going to use a custom connector, the "Virtual view" that contains the functions we are going to use in this tutorial.

Select "Use custom connector".

Select "MxDBVirtualView" in the "Use methods from" list. This class contains the

necessary methods for creating the virtual tree in this tutorial. You can view the class in the Java editor by selecting it in the "Connectors" section in the configuration tree.

Select the "Search" check box to specify that the class should be used to process SEARCH

5. Select the "Database" tab:

The values you specified in the URL wizard are filled in.

6. Choose "Get database schema" to verify that you can access the database and select the "Employees" table in the list.

Size limit type

7. Select the "Data source attributes" tab:

Keep the values that are filled in based on information about the data source. 8. Select the "Conversion from" tab:

Here you configure the conversion from the internal attributes used by the Virtual Directory Server to the attributes in the data source. You can find more information about attribute sets and conversions in the help file. Use the information in the table on page 4.

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.

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.

9. Select the "Conversion to" tab:

Select "Enable conversion to internal attributes". Import the conversions by choosing "Synchronize". 10. Choose "OK" to close the dialog box.

Section 3: Creating the virtual tree

We are now going to add the nodes in the virtual tree that create the structure of the virtual directory.

The final structure will be like this:

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=maxdata/ou=people/*

Renaming the default tree

First, we are renaming the default virtual tree created by the Virtual Directory Server to give it a more describing name.

1. View the properties of the entry "Tree 1" to open the "Virtual tree properties" dialog box:

Enter Virtual view as the name of the tree.

Creating the static nodes

We are now going to create the two static nodes, o=maxdata and ou=people. They do not reference any data source.

Creating the top node

1. Select the entry "Virtual view" and choose "New…" from the context menu. The "Node properties" dialog box is displayed:

Fill in the following fields:

Relative DN

Enter the node's relative distinguished name (RDN). The name must comply with the rules for LDAP distinguished names. In this case, enter o=maxdata.

Object class

Enter an object class that matches the attribute type of node's RDN. Some of the most common object classes are included in the list box. Remove the * and select "organization" from the "Append Object Class" list. Or type the name of the object class in the "Object class" field.

2. Select the "Access control list" tab:

Select "Anonymous" in the "User group" list and "FullReadAccess" in the "Rule" list. This will give users connecting anonymously (and thus connected to the "Anonymous" group) read-only access ("FullReadAccess") to the sub-tree.

3. Choose "OK" to close the dialog box. The virtual tree contains the following nodes:

Creating the sub-node

1. Select the node o=maxdata and choose "New…" from the context menu. The "Node properties" dialog box is displayed:

Fill in the following fields:

Relative DN

Enter ou=people as the node's RDN.

Object class

Select "organizationalUnit" from the list box as the node's object class. 2. Choose "OK" to close the dialog box.

Creating the data source node

Now we are going to add the node that represents the person entries in the database.

1. Select the node o=maxdata/ou=people and choose "New…" from the context menu. The "Node properties" dialog box is displayed:

Fill in the following fields:

Relative DN

Enter * as the node's relative distinguished name. This will match all possible DNs on this level.

Source

Select the data source "MaXdata", created in section 2.

Object class

Select the object classes "top", "person" and "inetOrgPerson" as the object class for the entries in the database.

2. Select the "Additional method parameters" tab:

Here you define the method parameters specific to this node. These parameters are sent to the methods in the Java class in addition to the parameters you defined for the data source. 3. We are now going to define the RDN for the objects in the database. In this tutorial we will

use UID=<EmployeeID> as RDN, but this could be any unique attribute or combination of attributes.

Select "Define DB parameters…" to enter the necessary parameters to create the DN for the entries in the database:

4. Choose "OK" to return to the "Node properties" dialog box:

In addition to the DN parameters the connector needs the following parameter: NODETYPE

Node type is "Plain" means that the parent node does not have a specific node type. Enter this value manually. The value is case sensitive.

These parameters are class specific and the parameter names depend on how the class is defined.

5. Select the "Advanced" tab:

Select the following check boxes:

Disallow one-level search/Disallow inherited sub-tree search/Disallow exact sub-tree search

Since this object contains leaf-nodes in the directory tree, doing one-level or sub-tree search is not possible. However, we want to include the leaf nodes in any search higher in the hierarchy. Select "Disallow one-level search" and "Disallow exact sub-tree search". The "Disallow inherited sub-tree search" is not selected to include this node in a sub-tree search from a superior node.

You can find additional information about these settings in the help file. 6. Choose "OK" to close the dialog box.

Section 4: Running the server

The initial configuration should now be complete. We are going to deploy the server as an LDAP server. Before we can start the server, we must specify the port number the clients are going to use to access the server.

Specifying the port number

The port number is a part of the LDAP deployment configuration. 1. View the properties of the "main_listener" LDAP deployment:

If the existing port number conflicts with an existing server, enter a different port number. 2. Choose "OK" to close the dialog box.

Running the server

Start the server by choosing Server/Start. When the server is started, the indicator in the status bar turns green.

You can use the internal LDAP client in the Virtual Directory Server to view the result. If you are using an external client, you configure the client using the following information: • Server address (host name) according to your system's configuration.

• The same port number as you used when configuring the server. • LDAP version 3.

• No starting point (to include the whole virtual tree in the search). • Anonymous login.

Viewing the virtual directory

When viewing the virtual directory with an external LDAP client you should see the following:

All person entries are displayed using the UID value (number) only. This is because the entries do not contain a display name that the client can use when displaying the entries.

Section 5: Adding a display name

The next step is to add a display name to the entries that the client can use.

Note:

Not all LDAP clients use the displayName attribute, so the results you see may vary.

Modifying the data source node

You need to add a method parameter on the data source node. The attribute class is already prepared to construct the displayName attribute.

1. View the properties of the node o=maxdata/ou=people/* and select the "Additional method parameters" tab:

Modify the following parameter: MANDATORYFIELDS

Enter the fields firstname and lastname to the list. The reason for adding these attributes here, is that we are going to use them to construct the displayName attribute of the object, thus they must always be retrieved from the database, regardless of what the LDAP client has requested.

Note:

The parameter names are case sensitive.

Adding the attribute class

Before we can reference the methods in the attribute class we need to reference the class in the server configuration:

1. View the properties of the VDS server and select the "Classes" tab:

2. Choose "New…" to the right of the "Attribute class" field and choose "SampleAttributeFixClass".

Enter a name for the class. 3. Choose "OK".

The Java class is displayed in the editor:

The class contains a method "BuildDisplayName", which adds the “displayName” attribute based on the values of the attributes "firstname" and "lastname".

4. Compile the class.

5. Choose "OK" to close the window.

Modifying the data source

You need to add a method parameter to the data source.

1. View the properties of the data source and select the "Conversion to" tab (since we are going to modify the data going back to the client):

Select the "Edit attribute set, using method" and choose the "BuildDisplayName" method from the list.

2. Choose "OK" to close the dialog box.

Note:

If you want to make additional changes to the returned dataset, this can be done by calling the method "EditAttributeSet". Write new methods to perform the required attribute modifications and include a call to these methods from the EditAttributeSet method.

Restarting the server

As we now have added a new class to the configuration, we need to start the server and compile the classes.

1. Stop the server.

2. Choose Server/Compile and start.

Section 6: Creating a two-level tree

In the existing configuration, all person entries in the organization are located below one single node in the virtual tree.

Now, we are going to extend the virtual tree with two branches: One representing the

organization's departments and one representing the organization's geographical locations. The people will be placed in the corresponding nodes, according to their department (ou) and location (l) attributes. This of course means that the same person may be present at several locations in the tree, but with different DNs.

The virtual tree will consist of the following nodes:

Creating the departments branch

The first step is to create the branch that represents the organization's department.

Adding the static node o=maxdata/ou=departments

1. Select the node o=maxdata and choose "New…" from the context menu:

Fill in the following fields:

Relative DN

Enter ou=departments as the node's relative distinguished name.

Object class

Select organizationalUnit as the node's object class. (This matches the attribute type of the node's RDN.)

Adding the data source node o=maxdata/ou=departments/ou=*

1. Select the node o=maxdata/ou=departments and choose "New…" from the context menu:

Fill in the fields:

Relative DN

Enter ou=* as the node's relative distinguished name (RDN). This RDN is used as a filter to identify all the ou entries in the data source.

Source

Select the "MaXdata" data source.

Object class

Select organizationalUnit as the node's object class. (This matches the attribute type in the RDN.)

2. Select the "Additional method parameters" tab and choose "Define DB parameters…".

Select "OU=" in the "Attribute types" list.

Select "Dep" in the list of "Available attributes" and choose "Add attribute".

The resulting DN is displayed in the "DN" field. It is not necessary to modify the DN. 3. Choose "OK" to return to the "Additional method parameters" tab.

In addition to the DN parameters, you need to add a parameter: NODETYPE

This is a different node type from the other data source node we have created. The value "COLUMN" specifies that the method should perform a "SELECT DISTINCT" statement on the specified column, in this case dep. This statement returns all unique values from the specified column.

The virtual tree contains the following nodes:

Adding the data source node o=maxdata/ou=departments/ou=*/*

We can clone the node o=maxdata/ou=people/* to use as a basis for the new node:

1. Select the node o=maxdata/ou=people/* and choose "Clone single node" from the context menu. The virtual tree looks like this:

2. Move the node by selecting the node o=maxdata/ou=people/Copy of * and choosing "Cut" from the context menu. Select the node o=maxdata/ou=departments/ou=* and choose "Paste". The virtual tree looks like this:

Modify the following fields:

Relative DN

Remove "Copy of" so the RDN is a single asterisk.

4. Select the "Additional method parameters" tab and choose "Define DB parameters…":

Select "UID=" in the list of "Attribute types".

Select "EmployeeID" in the list of available attributes. Choose "Add attribute" to update the "DN" field. 5. Select the "Second RDN" tab:

Select "OU=" in the list of "Attribute types". Select "Dep" in the list of available attributes. Choose "Add attribute".

6. Choose "OK" to return to the "Additional method parameters" tab. You get a warning that some of the existing parameters may be overwritten:

In addition to the DN parameters, you need to modify the following parameter: NODETYPE

The value "LEAF" tells the method that the parent node is a data source node. Add the following parameters:

ONEORSUBDN and ONEORSUBFILTER

These parameters are used when performing a one-level or sub-tree search with the parent node as the starting point. This starting point matches the ONEORSUBDN parameter. The value of <param1> is extracted and used in the ONEORSUBFILTER. The resulting ONEORSUBFILTER is added to the SQL statement being executed.

Example:

The Virtual Directory Server receives a one-level SEARCH request with the following starting point:

ou=admin,ou=departments,o=maxdata

This is matched against the ONEORSUBDN parameter: ou=<param1>,ou=departments,o=maxdata

The value corresponding to the <param1> part is extracted from the received DN, in this case admin.

This, in turn, is added to the ONEORSUBFILTER: dep='<param1>'

which will give the following value: dep='admin'

The virtual tree now consists of the following nodes:

Running the server

It is now time to update the configuration and view the contents:

1. Update the configuration by choosing the "Update" button in the toolbar. (Wait a few seconds for the configuration to reload.)

2. View the contents of the server. You see the structure now reflects the contents of the database.

Creating the locations branch

We have now created the branch for departments. We can use this branch when creating the corresponding branch for locations.

Cloning the departments branch

Clone the branch by selecting the node o=maxdata/ou=departments and choosing "Clone branch" from the context menu. The virtual tree now has the following structure:

Modifying the node o=maxdata/Copy of ou=departments

1. View the properties of the node o=maxdata/Copy of ou=departments:

Modify the following fields:

Modifying the node o=maxdata/l=locations/ou=*

1. View the properties of the node o=maxdata/l=locations/ou=*:

Modify the following fields:

Relative DN

Enter l=* as the node's relative distinguished name.

Object class

Select locality as the node's object class.

2. Select the "Additional method parameters" tab and choose "Define DB parameters…":

Enter L= in the "Attribute types" field.

3. Choose "OK" to return to the "Additional method parameters" tab. Answer "Yes" to overwrite the existing parameters:

Modifying the node o=maxdata/l=locations/l=*/*

1. View the properties of the node o=maxdata/l=locations/l=*/*. It is not necessary to modify the relative distinguished name. Select the "Additional method parameters" tab and choose "Define DB parameters…":

Select "UID=" in the "Attribute types" list.

Select "EmployeeID" in the list of "Available attributes". Choose "Add attribute".

2. Select the "Second RDN" tab:

3. Choose "OK" to return to the "Additional method parameters" tab. Answer "Yes" to overwrite the existing parameters:

Modify the following parameters: ONEORSUBDN

Modify the value to match the parent node's position and attribute type in the virtual tree. ONEORSUBFILTER

Substitute dep with location.

4. Choose "OK" to close the dialog box. The virtual tree should now look like this:

Running the server

It is now time to deploy the server configuration to view the results. With an LDAP client, they should look something like this:

You can also view properties of an entry:

You can see that the entry has a distinguished name as constructed by the Virtual Directory Server.

Section 7: Considering search access

In this section we are going to look at different models for search access.

When you perform a search with the LDAP client from the node maxdata, the search result will look something like this:

Note:

You have to select "Surname" in the "Search for" list.

The same person is now listed three times with three different DNs. It is possible to prevent this in different ways, depending on which behavior you want to achieve. Here two models are described:

• Preventing sub-tree searches from the top node. In this case a person is listed only once, but at the same time it would not be possible for the clients to perform a search from the top node. In many cases, this would be something the client expects should be possible. • Preventing inherited sub-tree searches in the departments and locations branches. This

method also prevents a person from being listed more than once, but it also has its side effects. It would, for instance, not be possible to search for organizations from the top node, as the sub-tree search will be stopped on the next level.

Each of the methods has its pros and cons, so which of these methods to choose is a design decision.

Configuration 1

One possibility is to prevent sub-tree searches from the node o=maxdata: 1. View the properties of the node and select the "Advanced" tab:

2. Select "Disallow exact sub-tree search". 3. Choose "OK" to close the dialog box. 4. Update the configuration.

This will prevent sub-tree searches starting from this node. To be able to perform a search including sub-folders, you have to start the search from one of the sub-nodes. A sub-search from the node maxdata will return 0 entries:

A sub-search from one of the sub-nodes returns only one instance of each entry:

Configuration 2

Another method is to prevent inherited sub-tree searches for the data source nodes

o=maxdata/ou=departments and o=maxdata/l=locations. An inherited sub-tree search is

defined as a sub-tree search with a starting point above the node.

1. View the properties of the node o=maxdata/ou=departments and select the "Advanced" tab:

3. View the properties of the node o=maxdata/l=locations and select the "Advanced" tab:

Select "Disallow inherited sub-tree search". 4. Choose "OK" to close the dialog box.

5. View the properties of the node o=maxdata and select the "Advanced" tab:

Deselect "Disallow exact sub-tree search". 6. Choose "OK" to close the dialog box. 7. Update the configuration.

This configuration will only include the node o=maxdata/ou=people/* in sub-tree searches. If you perform a search from the node maxdata, only one instance of each entry is found.