Working with the Common Directory Services API

Managing User Information with the Common Directory Service API . . . . . . . . . . . . . . . . . . . . . 2

About the Common Directory Services API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
CDS Code Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1
Working with the Common Directory Services API

Managing User Information with the Common Directory

Service API
My webMethods Server provides several directory service options for managing users
and groups:
My webMethods system directory. This is an internal My webMethods Server user
directory, available by default in all installations of My webMethods Server. You can
access information in this directory server using the My webMethods user interface
and the Common Directory Services (CDS) API. Both read and write access are
available.
LDAP (Lightweight Directory Access Protocol). My webMethods enables you to
define one or more external LDAP user directories. For a list of supported directory
server products, see the PDF publication webMethods System Requirements. You can
access information in this directory server using the My webMethods user interface
and the CDS API. Only read access is available.
Database. My webMethods Server also enables you to authenticate users against a
database directory, which is a set of RDBMS tables and an SQL configuration to access
these tables. You can implement a custom authentication module to extend
authentication against a database directory. You can access information in this
directory server using the My webMethods user interface and the CDS API. Only
read access is available.
My webMethods Server and applications and services running within it can access the
user information contained in these directories, and you can configure external
applications and services that have access to My webMethods Server to use this data.
In addition to working with users and groups in a directory service, you can access and
maintain role information, which is maintained separately in the My webMethods Server
database.
For example, you can:
Configure other suite applications, such as webMethods Integration Server, to
authenticate users from any of the above user directory options instead of from a user
directory unique to Integration Server.
Configure a process step in a business process to call a Java service to obtain user
attributes from the directory service or role membership from the My webMethods
Server database, and pass that data into the process pipeline.
Configure a Java service to assign a user to a role programmatically.
The CDS API offers support for the following:
Search and discovery of users, groups, and roles.
Support for LDAP search controls for large directories.
Create and update users and groups in the system directory. All other external
directories are read-only.

2
 Working with the Common Directory Services API

Delete users and groups from the system directory.

Create, update, and delete roles in My webMethods Server.
Read custom attributes from LDAP and database directories.
Read and write custom profile attributes for users, groups, and roles (that is,
attributes which are not managed by external directories).
To view the Javadoc for the Common Directory Services API, refer to these packages:
com.webmethods.sc.directory
com.webmethods.sc.mws
Javadocs can be installed with other My webMethods Server documentation using the
Software AG Installer, and they are also available from the Web site
http://documentation.softwareag.com/.

About the Common Directory Services API

When connected to a My webMethods Server database schema, CDS behaves very much
like a My webMethods Server cluster instance, and it participates in all the distributed
caching across a My webMethods Server cluster. For example, when a system directory
user is updated, this change is immediately seen by all CDS instances connected to the
same database.
Directory services are defined and managed in My webMethods Server, by logging in to
My webMethods as either sysadmin or as Administrator. For more information about
working with directory services, see "Managing Directory Services" and "Managing
External Directory Services" in the PDF guide Administering My webMethods Server.
In addition to working with the CDS API, you can use the My webMethods interface to
perform all directory management activities:
User, group, and role management. For more information, see Part 2, "Administrator
Functions" in the PDF guide Administering My webMethods Server.
Authentication management. For more information, see Part 3, "System Administrator
Functions" in the PDF guide Administering My webMethods Server.
Implementation of attribute providers. For more information, see Part 3, "System
Administrator Functions" in the PDF guide Administering My webMethods Server.

Prerequisites
Before you can work with the CDS API, you must take the following actions:
The My webMethods Server database tables must be created by the webMethods
Database Component Configurator. This is normally carried out immediately after
installation.

3
Working with the Common Directory Services API

The My webMethods Server instance must be created and started.

CDS must be initialized with a JDBC connection to the My webMethods Server
database schema. For more information, see Initializing Common Directory
Services below.

Class Path Considerations

If you want to use CDS in a stand-alone application, in addition to providing the correct
JDBC connection information, all CDS .jar files must be present in the class path of the
external application running CDS. To ensure that these .jar files are available, include all
.jar files from Software AG_directory/common/lib and /common/lib/ext (assuming you
have a standard installation of My webMethods Server and Integration Server).

Initializing Common Directory Services

When the CDS API is accessed from inside My webMethods Server (from a CAF
application for example), CDS is already initialized and no further action is needed. If
you want to use the CDS API from an external application or service that has access to
My webMethods Server, the CDS API must be explicitly initialized from the external
application or service.
You initialize Common Directory Services by invoking the
com.webmethods.sc.mws.MWSLibrary.init() static method. The input parameters are
expected as Java system properties and must describe a JDBC connection URL to a My
webMethods Server database schema. Instead of using remote call backs to My
webMethods Server, the CDS API connects to this schema and reads all configuration
and principal information.
Here is sample code showing how to initialize CDS using the MWSLibrary class:
System.setProperty(MWSLibrary.SYSTEM_PROP_DB_DRIVER,
"com.wm.dd.jdbc.sqlserver.SQLServerDriver"); // JDBC Driver Class
System.setProperty(MWSLibrary.SYSTEM_PROP_DB_URL,
"jdbc:wm:sqlserver://localhost:1433;DatabaseName=webm82_dev"); // JDBC
Connection URL
System.setProperty(MWSLibrary.SYSTEM_PROP_DB_USER, "webm82_dev"); // DB username
System.setProperty(MWSLibrary.SYSTEM_PROP_DB_PASSWORD, "password"); // DB
password
MWSLibrary.init();

CDS Code Examples

The following are a few examples of common CDS code:

List All Roles

IDirectorySession session =
DirectorySystemFactory.getDirectorySystem().createSession();

4
 Working with the Common Directory Services API

List roles = session.listRoles();

for (IDirectoryRole role: roles) {
String roleID = role.getID();
String roleName = role.getName();
String roleDN = role.getDN();
}

Lookup a User by Name and Fetch all Attribute

IDirectorySession session =
DirectorySystemFactory.getDirectorySystem().createSession();
IDirectoryUser user = (IDirectoryUser) session.lookupPrincipalByName("user1",
IDirectoryPrincipal.TYPE_USER);
Map attributes = user.getAllAttributes();

Authenticate User
IDirectorySession session =
DirectorySystemFactory.getDirectorySystem().createSession();
IDirectoryUser user = session.authenticateUser("username", "password");

Create Static Role and Add User as a Member

IDirectorySession session =
DirectorySystemFactory.getDirectorySystem().createSession();
IDirectoryUser user = (IDirectoryUser) session.lookupPrincipalByName("user1",
IDirectoryPrincipal.TYPE_USER);
IDirectoryRole role = session.createRole(IDirectoryRole.STATIC_ROLE_TYPE,
"roleName", Collections.EMPTY_MAP);
session.addPrincipalToRole(user.getID(), role.getID());

5
Working with the Common Directory Services API