WebSphere

 

Portal Express, Version 6.0
Operating systems: i5/OS, Linux, Windows

 

Use multiple realms and user registries

The information in this file describes how to configure WebSphere Portal Express to use multiple realms and user registries.

 

Overview

A Realm allows you to group users from one or more LDAP trees of one user registry and expose them as a coherent user population to WebSphere Portal Express; this is also referred to as horizontal partitioning. Realms allow a flexible user management with various configuration options; for example, you can combine principals from one or more corporate LDAP tree. A realm must be mapped to a Virtual Portal to allow the realm's defined user population to login to the Virtual Portal. See Multiple virtual portals for more information. Realm membership is validated during authentication to ensure that a virtual portal can only be accessed by members of the corresponding realm. Therefore, users from one realm cannot access another realm unless they are also members of that group. For example, a wpsadmin will not be able to log in to a virtual portal unless the wpsadmin is a member of the corresponding realm. Multiple virtual portals can share the same user population by specifying the same realm relationship. Realms can overlap, which allows users to be members of more than one realm.

 

Preparation

To use Realms, the WebSphere Application Server user registry provided by Member Manager must be used as the authentication mechanism in WebSphere Application Server. Use the enable-security-wmmur-ldap and enable-security-wmmur-db tasks to use the realm feature.

When combining multiple registries, ensure that the distinguished names are unique over all repositories. When using enable-security-wmmur-db, the IDs entered in the wpconfig.properties file (PortalAdminId, WasUserId, ...) are created in the database; these must not exist with its distinguished names in the other registries you want to add later.

When in non-security mode, using enable-security-ldap, or registering a custom user registry as WebSphere Application Server Authentication mechanism, realms cannot be leveraged. For more information about configuring security, see the following links:

 

Configuration

The Member Manager configuration files are located in the portal_server_root/wmm/ directory. The following files contain the Member Manager configuration.

The Member Manager configuration files within a clustered environment are moved from the portal_server_root/wmm/ directory to the was_profile_root/config/wmm directory by way of a configuration task that uploads and replicates to all cluster nodes.

When using the multiple realm feature, only adjust the wmmAttributes.xml file to add or remove attributes from the default. Refer to the following sections for more information about these files:

 

wmm.xml

The wmm.xml file defines general information about Member Manager:

Parameter Definition
defaultRealmName Use this parameter to define the name of the realm used as default from the WMMUR information
horizontalPartitioning Use this parameter to define if you will use multiple user repositories. Set this to true if you are using multiple LDAP repositories or a database and an LDAP repository.
lookaside Use this parameter if you will use a database attribute store to store additional attributes beside the LDAP database. The default setting is false.
configurationFile Use this parameter to define the attributes that Member Manager returns.
maximumSearchResult Use this parameter to define the maximum number of returned objects for a non-paged search result. The default setting is 200.
searchTimeOut Use this parameter to define the number of milliseconds a search result remains active.

 

Repository settings:

The tag <repositories>...</repositories> contains the following repositories; see the associated links for sample code settings:

 

wmmLDAPServerAttributes.xml

The wmmLDAPServerAttributes.xml file defines all the Member Manager attribute definitions and the LDAP attribute mappings. The following is a list of general rules to define attributes in the XML file:

 

wmmur.xml

Type the following lines between the <realms>...</realms> tag to add additional realms: 

	<realm  delimiter="@" default="true">
		<node wmmnode="dc=test,dc=com"/>
		<node wmmnode="cn=users,dc=test,dc=com" defaultParent="Person" />
		<node wmmnode="cn=groups,dc=test,dc=com" defaultParent="Group" />
	</realm>

You can add as many wmmNodes as required. Place wmmNodes under the membership hierarchy scope of the nodes defined in the wmm.xml file for each repository. If you plan to set this realm for a Virtual Portal, you need to add the following entries; This is not required for the default realm if it is not mapped to a Virtual Portal:

You must add one node with the property defaultParent="Person" defined; the specified node is used as parent distinguished name when creating users. You also must add one node with the property defaultParent="Group" defined; the specified node is used as parent distinguished name when creating groups. Sample: When you create a user in WebSphere Portal Express while being in a Virtual Portal that is mapped to the realm portal defined above, a user with name myuser will get the distinguished name <rdn-attribute>=myuser,cn=users,dc=test,dc=com.

The following table lists xml tags, parameter names, and descriptions for Realms:

XML Tag Parameter Name Description
Realm id The unique name of the realm.
delimiter A separator between the user ID and realm ID. "\" is the special character handler. If the user ID or realm ID contains special characters, put a backslash in front of the special character.

Do not give a realm that contains other realm delimiters inside.

For example, userId=user1@ca.ibm.com; delimiter=@; realm=ibmclub; When passing UserId to WMMUR, the string should look like: user1\@ca.ibm.com@ibmclub.

default If true, this realm is a default realm.

Define only one realm as the default realm in the whole WMMUR configuration.

Node wmmnode The Member Manager node value. In wmm.xml, each repository has a nodeMaps definition. Here, wmmnode should match the Member Manager member node. For example, in wmm.xml, one of the <nodeMap> has the following value: 

	<nodeMap node="dc=yourco,dc=com"
		pluginNode="dc=yourco,dc=com"/>
In wmmur.xml, the <node> could be: 

	<node wmmnode=" dc=yourco,dc=com"/>

The cases are sensitive. The wmmNode case in wmmur.xml should match the node case in wmm.xml.

defaultParent (Optional) Set this wmmNode to be the default parent DN for specified member type. The member type can be Person for users or Group for groups.

The realm that is flagged as the default realm must contain all wmmNodes that are defined in the other realms.

 

wmmWASAdmin.xml

The following table lists xml tags, parameter names, and descriptions for wmmWASAdmins:

XML Tag Parameter Name Description
admin logonID The ID used for logon.
logonPassword The encrypted user password.

Although clear text passwords are accepted, it is highly recommended that you encrypt the password. Use the encryption tool that Member Manager provides.

uniqueUserID The distinguished user name.

 

Sample Configuration

The following are sample configurations:

 

Aspects when using Member Manager in a cluster

In a clustered environment, Member Manager files are not located at portal_server_root/wmm. They are moved to was_profile_root/config/wmm. When the security configuration task runs, it uploads the files to the deployment manager and replicates them to all cluster nodes.

If you need to manually edit the Member Manager files for a WebSphere Portal Express node that has been federated, check the files out of the deployment manager configuration repository before you can make any changes. For information on checking files out or in, refer to Managing the cluster.

Refer to Enabling LDAP server as Localmode for information about manually configuring your LDAP directory to perform authentication. On the WebSphere Application Server machine and any nodes in the cell that do not contain WebSphere Portal Express, the authentication works by default against the wmmWASAdmin.xml file. The same holds true for the node agent that runs on each server. When stopping a node agent, use a user ID specified in the wmmWASAdmin.xml file.

Refer to the wmmWASAdmin.xml section for more information.

 

Enable LDAP server as Localmode

You can configure the authentication against an LDAP server by using the WebSphere Application Server administrative console. In the administrative console, navigate to Security > Global security > User Registries > Custom > Custom Properties and adapt the following parameters to enable LDAP servers:

Name Value

(Example/Default)

Description
wasUserRegistryType (Optional) wmmLDAP WebSphere Application Server user's profile is on LDAP server

Then add the following properties depending on the type of LDAP server you are using:

Name Valid Value (Example) Description
ldapURL (Required) ldap://localhost:389 (for single LDAP)

or

ldap://ldap1.yourco.com:389

ldap://ldap2.yourco.com:389 (for multiple LDAP directories)

LDAP server URL. It can be a single LDAP URL or multiple LDAP URL.

Use a space to separate multiple URL.

ldapType (Optional) 0 = Tivoli Directory Server

2 = Sun Java System Directory Server

3 = Lotus Domino

4 = Active Directory

5 = Novell eDirectory

LDAP server. If not specified, 0 defaults as the ldapType.
baseDN (Required) <DN> The base distinguished name of wmmLDAP, which indicates the starting point for LDAP searches.

The following property is required for all LDAP servers. The DN is case sensitive. The baseDN case should match the <nodeMap> node case set in wmmur.xml

ldapBaseDN (Optional) <ldapDN> If you are in the wmm.xml configuration file, the pluginNode in nodeMap for this LDAP server is different from the wmmNode; put the pluginNode value as ldapBaseDN.

For example:

baseDN="o=default organization" and in wmm.xml, <nodeMap node="0=default organization" pluginNode="dc=yourco,dc=com"/>

Here ldapBaseDN="dc=yourco,dc=com"

The DN is case sensitive. The ldapBaseDN case should match the pluginNode case set in wmm.xml.

bindDN (Optional) LDAP bind ID The distinguished name for the application server to use to bind to the directory server. If not specified, this property will be anonymous.
bindPassword (Optional) password The password used when binding the application server to the directory server.

Although clear text passwords are accepted, it is highly recommended that you encrypt the password. Use the encryption tool that Member Manager provides.

userIdMap (Optional) Tivoli Directory Server = *:uid

Sun Java System Directory Server=inetOrgPerson:uid

Lotus Domino=person:uid

Active Directory=user:sAMAccountName

Novell eDirectory=person:cn

A Member Manager person RDN filter.

This property should match the "Person" rdnAttrTypes value for Member Manager supportedMemberTypes

If you are in Member Manager, the Member Manager attribute is mapped to a different name in LDAP directory; add the LDAP attribute name to the end and separate it with ":".

For example, in the wmmLDAPAttributes.xml file, uid is mapped to the e-mail attribute. userIdMap=inetOrgPerson:uid:email.

If not specified, the default value will be used.

ldapUserIdMap (Optional) <LDAP user RDN attribute name> The user LDAP RDN. This parameter is only required when the value is different than the userIdMap value. It should match "Person" rdnAttrTypes value for wmmLdap supportedLdapEntryTypes.
groupIdMap *:cn An LDAP filter that maps the short name of a group to an LDAP entry.

If not specified, the default value will be used.

userFilter (Optional) Tivoli Directory Server = (&(uid=%v) (objectclass=ePerson))

Sun Java System Directory Server(&(uid=%v) (objectclass=inetOrgPerson))

Lotus Domino(&(uid=%v) (objectclass=Person))

Active Directory(&(sAMAccountName=%v) (objectclass=Person))

Novell eDirectory(&(uid=%v) (objectclass=Person))

An LDAP filter clause for searching the registry for users.

If not specified, the default value will be used. The default value is (&(uid=%v) (objectclass=Person))

groupFilter (Optional) Tivoli Directory Server = (&(cn=%v) (|(objectclass=groupOfNames) (objectclass=groupOfUniqueNames)))

Sun Java System Directory Server(&(cn=%v) (objectclass=ldapsubentry))

Lotus Domino(&(cn=%v) (objectclass=dominoGroup))

Active Directory(&(cn=%v) (objectclass=group))

Novell eDirectory(&(cn=%v) (objectclass=groupOfNames))

An LDAP filter clause for searching the registry for groups.

If not specified, the default value will be used.

sslConfig (Optional) true or false Secure Sockets Layer configuration to use for the LDAP connection. If not set, assume SSL is not enabled.

 

Recommendations

 

Adding the super admin to other realms:

When you separate the realms completely for the different Virtual Portals, the administrator of the default Virtual Portal can not log into the other Virtual Portals anymore. Add the users to the other realms to change this. Make the following adjustments to the wmmur.xml file:

Add <node wmmnode="<DN of the super admin"/> to the wmmNodes you want the super admin to log in (where the super admin is not already part of another wmmNode).

 

Manually configuring your LDAP server to perform authentication:

Refer to Enabling LDAP server as Localmode for information about manually configuring your LDAP server to perform authentication.

 

Sample for multiple LDAPs: 

<wmmur>
		<realms>
			<realm  delimiter="@" default="true">
				<node wmmnode="dc=raleigh,dc=ibm,dc=com"/>
				<node wmmnode="OU=hr,o=ibm,C=us"/>
			</realm>
			<realm id="suffix2" delimiter="@" default="false">
				<node wmmnode="OU=hr,o=ibm,C=us" />
				<node wmmnode="cn=users,OU=hr,o=ibm,C=us" defaultParent="Person" />
				<node wmmnode="cn=groups,OU=hr,o=ibm,C=us" defaultParent="Group" />
				<node wmmnode="uid=wpsadmin,cn=users,dc=raleigh,dc=ibm,dc=com"/>
			</realm>
		</realms>
	</wmmur>

 

Limitations

 

Uniqueness of logon-ids and DNs:

The DN of a principal must be unique over all wmmNodes defined in wmmur.xml.

The attributes that are defined as logon attributes should be unique for the wmmNodes defined in a realm or the logon will fail. If the uniqueness of the logon attributes cannot be achieved, the following configuration makes it possible to logon with the DN of the user:

  1. Select the appropriate console, depending on your environment:

    • If running a standalone environment, use the local administrative console.

    • If running a cluster environment, use the console of the Deployment Manager.

  2. Start the administrative console by entering the following in the URL location field of a Web browser: http://example.com:admin_port/ibm/console where example.com is the name of your server and admin_port is the port assigned to the administrative console.

  3. In the navigation open the Security section by clicking the plus ( + ) sign.

  4. Click Global Security > User Registries > Custom > Additional Properties > Custom Properties.

  5. Click wmmUserSecurityNameAttr and set the value to memberDN.

  6. When you are done, click Save at the top of the screen under Message(s).

  7. Click Save again when prompted to confirm your changes.

  8. If running a cluster configuration, replicate your changes to the cluster.

  9. Restart the server to make the changes become effective.

Users with a logon attribute that is unique still can login using the attribute.

 

Lotus Domino Single Signon is not supported in combination with multiple user registries.

 

Parent topic:

Additional LDAP configuration