Abstract: This article explains
the details of configuring standalone LDAP on IBM® WebSphere® Application
Server and IBM WebSphere Portal security, to Microsoft® Active Directory
running on Windows® 2003 Enterprise Server, over Secure Socket Layer (SSL).
Learn how to use Certificate Services in Microsoft Windows 2003 to create
a server certificate to be used in Active Directory over SSL, how to import
the certificate into WebSphere Application Server’s Deployment Manager,
and how to specify standalone LDAP parameters in wkplc.properties to run
the WebSphere Portal configuration task wp-modify-ldap-security.
Contents
1 Introduction
2 Preparing Microsoft Active Directory for Secure Socket Layer (SSL) configuration
3 Setting up the Active Directory for SSL connection
4 Configure WebSphere Deployment Manager to import the certificate
5 Configuring security in a cluster with Active Directory over SSL
5.1 Running ConfigEngine tasks
Appendix A
6 Resources
7 About the author
1 Introduction
Although it is a recommended practice to set up security through the non-secure
channel (default port 389), in some cases it’s not practical due to company
security policies or the restrictions on the LDAP server itself.
In this article, we discuss the details of configuring IBM WebSphere Application
Server and IBM WebSphere Portal security as a standalone LDAP configuration
to a Microsoft Active Directory running on Windows 2003 Enterprise Server,
over Secure Socket Layer (SSL).
Also provided in the appendix is the solution of the recommended configuration,
i.e. configuring security over a non-secure channel first and then adding
SSL support later.
It is assumed that you have set up your cluster per the instructions in
technote #1313184,
Step-by-Step Cluster Guide for IBM WebSphere Portal 6.1,
and that your system’s default file-based repository is working correctly
with respect to both WebSphere Application Server security and WebSphere
Portal security.
2 Preparing Microsoft Active Directory for Secure Socket Layer (SSL)
configuration
Microsoft Active Directory 2003 used in this study was installed on a machine
with hostname
goldensand.raleigh.ibm.com and with the domain set
to “raleigh.ibm.com”. This set the LDAP’s NamingContext to “DC=raleigh,DC=ibm,DC=com”,
which can be verified by the following partial RootDSE output:
subschemaSubentry=CN=Aggregate,CN=Schema,CN=Configuration,DC=raleigh,DC=ibm,DC=com
dsServiceName=CN=NTDS Settings,CN=GOLDENSAND,CN=Servers,CN=Default-First-Site-Name,CN=Sites,CN=Configuration,DC=raleigh,DC=ibm,DC=com
namingContexts=
DC=raleigh,DC=ibm,DC=com
namingContexts=CN=Configuration,DC=raleigh,DC=ibm,DC=com
namingContexts=CN=Schema,CN=Configuration,DC=raleigh,DC=ibm,DC=com
namingContexts=DC=DomainDnsZones,DC=raleigh,DC=ibm,DC=com
namingContexts=DC=ForestDnsZones,DC=raleigh,DC=ibm,DC=com
defaultNamingContext=
DC=raleigh,DC=ibm,DC=com
schemaNamingContext=CN=Schema,CN=Configuration,DC=raleigh,DC=ibm,DC=com
configurationNamingContext=CN=Configuration,DC=raleigh,DC=ibm,DC=com
rootDomainNamingContext=DC=raleigh,DC=ibm,DC=com
To begin the configuration, we perform these steps:
1. Install
Internet Information Services
(IIS) on the domain controller (to be used later in Certificate Services
configuration) by selecting Start > Settings > Control Panel >
Add or Remove Programs, select “Add/Remove Windows Components”; then
check the box for Application Servers. This installs IIS and other related
components.
2. On the domain controller machine, enable
Certificate Services by selecting Start > Settings > Control
Panel > Add or Remove Programs; then select “Add/Remove Windows Components”.
The window in figure 1 was shown.
Figure 1. Add Windows Components
3. Check “Certificate Services” and click
Next. The warning message shown in figure 2 should display.
Figure 2. Certificate Services warning
4. Click Yes to continue. You are then asked
to select the type of CA you want to set up (see figure 3). We chose Stand-alone
root CA, since this is only a test environment. Do not check the “Use
custom settings to generate the key pair and CA certificates” option at
this time. Click Next.
Figure 3. CA Type options
5. On the “Common Name for this CA” panel,
enter the DNS name or NetBIOS name for the machine, in this case, “goldensand”.
This sets the full DN to “CN=goldensand,DC=raleigh,DC=ibm,DC=com".
You can keep the default key validity period of 5 years, and answer Yes
to overwrite the existing private key, if asked.
6. Answer Yes to enable Active Server Pages
(ASPs) support for “CertServ” configuration later. (If you answer No,
you can still enable it later, using the command “certutil –vroot”)
7. Keep the default locations for the certificate
database and certificate database log. After the configuration finishes,
you should start the IIS Manager (inetmgr) to verify that “CertControl”,
“CertEnroll”, and “CertSrv” are listed under the Default Web Site (see
figure 4).
Figure 4. Default Web Site listings
3 Setting up the Active Directory for SSL connection
There are several ways of configuring SSL on Active Directory; the following
is the approach we took:
1. Configure a certificate request through the
Web interface: Open an Internet Explorer browser window and access the
URL
http://goldensand.raleigh.ibm.com/certserv
. The window in figure 5 should display. Select the "Request a certificate”
task.
Figure 5. Certificate Services Welcome screen
2. In the Request
a Certificate window (see figure 6) select “advanced certificate request”.
Figure 6. Request a Certificate screen
3. On the next panel (see figure 7), select
“Create and submit a request to this CA”.
Figure 7. Advanced Certificate Request screen
4. On the next panel (see figure 8), enter the
fully qualified hostname of the machine “goldensand.raleigh.ibm.com”
in the Name field, and enter your email address. Optionally, you can enter
the company name and other information, but make sure the following are
selected and leave others as default:
a. Type of the certificate needed: Server Authentication
Certificate
b. Create new key set;
c. CSR: Microsoft RSA SChannel Cryptographic
Provider
d. Key size: 1024
Figure 8. Key options
5. After clicking the Submit button, click Yes
on the Potential Scripting Violation warning dialog. You will then see
the window in figure 9.
Figure 9. Certificate Pending screen
6. Process the request from Certificate Services:
Add snap-ins “Certificates (Local Computer)” and “Certificate Authority
(Local)” to Microsoft Management Console (MMC). From Certificate Authority
(Local), expand “goldensand” and “Pending Requests”; you should see
the newly created request with a request ID (see figure 10).
Figure 10. Request ID
7. Right-click on the Request ID, and select
All Tasks > Issue (see figure 11).
Figure 11. Issue the request
8. Retrieve and install the certificate: Open
a browser window and enter URL
http://goldensand.raleigh.ibm.com/certserv.
Select “View the status of a pending Certificate request” and then “Server
authentication certificate (
<![CDATA[<date></date>]]>)”. You
should see that the certificate requested above was issued. Select “Install
this certificate”.
9. After the certificate is installed successfully,
you can test the connection using
LDP.exe, a useful tool for verifying
Active Directory connections, users and groups, and other configurations.
The details can be found at
http://technet.microsoft.com/en-us/library/cc772839.aspx.
4 Configure WebSphere Deployment Manager to import the certificate
There are basically two ways to import the certificate from the LDAP into
the WebSphere Network Deployment Manager’s trust store. Below we describe
the easier and more straightforward method, new in WebSphere Portal 6.1.
1. Log on to the Integrated Solution Console
(a.k.a the Administrative Console) on the Deployment Manager (Dmgr) using
the admin user ID in the file-based registry.
2. Navigate to Security > SSL certificate
and key management > SSL configurations > CellDefaultSSLSettings
> Key store and certificates > CellDefaultTrustStore > Signer
certificates. Click the “Retrieve from port” button (see figure 12).
Figure 12. Manage signer certificates
3. Enter the LDAP server hostname and the SSL
port (default 636), and click Retrieve signer information (see figure 13).
Figure 13. Retrieve signer information
4. You should see the information as shown in
figure 14. You can then save the certificate. Now the Dmgr contains the
LDAP server’s certificate.
Figure 14. Certificate General Properties
5. Make sure the entry “ClientDefaultTrustStore”
is specified correctly in
<![CDATA[<dmgr profile="profile">/properties/ssl.client.props:
</dmgr>]]>
com.ibm.ssl.trustStoreName=ClientDefaultTrustStore
com.ibm.ssl.trustStore=${user.root}/etc/trust.p12
com.ibm.ssl.trustStorePassword={xor}CDo9Hgw=
com.ibm.ssl.trustStoreType=PKCS12
com.ibm.ssl.trustStoreProvider=IBMJCE
com.ibm.ssl.trustStoreFileBased=true
If you have changed the default password for trust.p12, you may see a different
string for the encrypted password.
5 Configuring security in a cluster with Active Directory over SSL
It is recommended to use the WebSphere Portal configuration tasks to enable
standalone LDAP configuration. This way, you can guarantee a consistent
configuration between WebSphere Application Server, Virtual Member Manager
(VMM), and WebSphere Portal.
Tables 1, 2 and 3 list the "standalone" LDAP configuration parameters
we set in
wkplc.properties
Table 1. Basic LDAP parameters
| standalone.ldap.id
| msadSA1
|
| standalone.ldap.host
| goldensand.raleigh.ibm.com
|
| standalone.ldap.port
| 636
|
| standalone.ldap.bindDN
| cn=wp61 bind,cn=users,dc=raleigh,dc=ibm,dc=com
|
| standalone.ldap.bindPassword
| <![CDATA[<password></password>]]>
|
| standalone.ldap.ldapServerType
| AD2003
|
| standalone.ldap.userIdMap
| *:sAMAccountName
|
| standalone.ldap.groupIdMap
| *:cn
|
| standalone.ldap.groupMemberIdMap
| group:member
|
| standalone.ldap.userFilter
| (&(|(cn=%v)(samAccountName=%v))(objectclass=user))
|
| standalone.ldap.groupFilter
| (&(cn=%v)(objectclass=group))
|
| standalone.ldap.serverId
| cn=was61 admin,cn=users,dc=raleigh,dc=ibm,dc=com
|
| standalone.ldap.serverPassword
| <![CDATA[<password>
</password>]]>
|
| standalone.ldap.realm
| portal
|
| standalone.ldap.primaryAdminId
| cn=was61 admin,cn=users,dc=raleigh,dc=ibm,dc=com
|
| standalone.ldap.primaryAdminPassword
| <![CDATA[<password></password>]]>
|
| standalone.ldap.primaryPortalAdminId
| cn=wp61 admin,cn=users,dc=raleigh,dc=com
|
| standalone.ldap.primaryPortalAdminPassword
| <![CDATA[<password></password>]]>
|
| standalone.ldap.primaryPortalAdminGroup
| cn=wp61admins,dc=raleigh,dc=ibm,dc=com
|
| standalone.ldap.baseDN
| dc=raleigh,dc=ibm,dc=com |
Table 2. User and group management properties (used for VMM configuration)
| standalone.ldap.et.group.searchFilter
| (ObjectCategory=Group)
|
| standalone.ldap.et.group.objectClasses
| group
|
| standalone.ldap.et.group.objectClassesForCreate
| group
|
| standalone.ldpa.et.group.searchBases
| dc=raleigh,dc=ibm,dc=com
|
| standalone.ldap.et.personaccount.searchFilter
| (ObjectCategory=Person)
|
| standalone.ldap.et.personaccount.objectClasses
| user
|
| standalone.ldap.et.personaccount.objectClassesForCreate
| user
|
| standalone.ldap.et.personaccount.searchBases
| dc=raleigh,dc=ibm,dc=com
|
| standalone.ldap.gm.groupMemberName
| member
|
| standalone.ldap.gm.objectClass
| group
|
| standalone.ldap.gm.scope
| nested
|
| standalone.ldap.gm.dummyMember
| <![CDATA[<blank></blank>]]>
|
| standalone.ldap.personAccountParent
| cn=users,dc=raleigh,dc=ibm,dc=com
|
| standalone.ldap.groupParent
| dc=raleigh,dc=ibm,dc=com
|
| standalone.ldap.personAccountRdnProperties
| cn
|
| standalone.ldap.groupRdnProperties
| cn
|
|
|
|
| standalone.ldap.gc.name
| memberOf
|
| standalone.ldap.gc.scope
| nested
|
| standalone.ldap.gc.updateGroupMembership
| <![CDATA[<blank></blank>]]> |
Table 3. Properties related to SSL only:
| standalone.ldap.sslEnabled
| true
|
| standalone.ldap.sslConfiguration
| CellDefaultSSLSettings |
where selected entries in the above tables are defined as follows:
· The LDAP
ID is a string to identify this repository in the VMM configuration. It
can be any string, but we recommend using only alphanumeric characters,
period (.), hyphen (-), or underscore (_).
· The LDAP
hostname should be either the fully qualified host name, like the one we
used in our example, or the numerical IP address. The short machine name
is not recommended.
· The admin
users for WebSphere Portal and WebSphere Application Server security should
not have the same short name as those used in the default file registry,
especially for a federated repository configuration. The “standalone”
LDAP configuration does not have this requirement, but it is still recommended
not to use the same short names to avoid confusions.
· The bind
DN must be the distinguished name of the user ID. In Active Directory,
this ID should be part of the domain administrators group.
· The default
Virtual Member Manager (VMM, a.k.a WIM) adapter for Active Directory has
“uid” mapped to “samAccountName”. Thus, in a VMM/WIM configuration,
“uid” is used. For a standalone LDAP configuration, however, WebSphere
Application Server authentication components make direct LDAP connections
without going through VMM. Therefore, “samAccountName” should be used,
not uid, for user filter and user ID map. It’s a different
story, though, if the federated repository is configured.
· In WebSphere
Application Server version 6.1, a primary admin ID was introduced. It is
this ID that is used to access the admin console and stop the Dmgr, nodeagents,
and servers. You can still specify a server ID that is used only for some
internal protected methods; if it is not specified, the system will automatically
generate one for you. In this example, we used the same user ID for both
roles.
· LDAP NamingContexts
are DNs that define namespaces. The RootDSE should give all defined NamingContexts.
It is recommended to define the “baseDN” to one of such NamingContexts.
You should not define a partial NamingContexts in the baseDN parameter.
For example, our example shows “dc=raleigh,dc=ibm,dc=com”. You should
not set “baseDN” to “dc=ibm,dc=com”, or even “dc=com”.
· “standalone.ldap.et.personaccount.searchFilter”
and “standalone.ldap.et.group.searchFilter” should be left blank for
most LDAP server types.
Do not specify filters like
“cn=%v” or “uid=%v” in these parameters. VMM does not recognize this
format. If you cannot find users and groups in the Users and Groups portlet
after the security configuration, these should be checked.
In Active Directory, “ObjectCategory” is a single-valued attribute and
is indexed. Specifying ObjectCategory
in these filter parameters greatly
improves performance when searching for users and groups. Note that the
ObjectCategory for “Person” objects is Person,
not user;
thus (ObjectCategory=user) doesn’t make sense.
· In Active
Directory, the relative distinguished name (RDN)
for PersonAccounts is always “CN”.
Do not specify uid or samAccountName for the “standalone.ldap.personAccountRdnProperties”
parameter.
· LDAP servers
such as IBM Directory Server, Novell eDirectory, and Microsoft Active Directory
provide a system-generated group membership attribute that is back linked
from a member of a group to the enclosing group. In Active Directory, it’s
called “memberOf”, and this parameter should be set in the parameter
“standalone.ldap.gc.name”.
Setting this attribute can greatly improve performance when searching all
groups a user belongs to; however, when Active Directory’s Global Catalog
(GC) is configured, “memberOf” may not work as expected because not all
member information is replicated in Global Catalog for all group types.
· “personAccountParent”
and “groupParent” specify the LDAP tree branch where you want to create
new users and groups, respectively. They are only required when you configure
WebSphere Portal to create users and groups. They may or may not be the
same as the search bases, especially when multiple search bases exist.
· If nested
groups are to be used in WebSphere Portal, then you should specify “nested”
for both “standalone.ldap.gm.scope” and “standalone.ldap.gc.scope”
parameters. On the other hand, you should not them to “direct”,
if there are no nested groups. This could improve group search performance.
· “sslConfiguration”
should be set to the configuration in WebSphere security SSL settings.
In a WebSphere Portal cluster, the default is “CellDefaultSSLSettings”.
If you are configuring a standalone WebSphere Portal server, then it should
be set to “NodeDefaultSSLSettings”.
5.1 Running ConfigEngine tasks
We recommend running ConfigEngine on "validate-standalone-ldap"
first, to verify the LDAP connection, users and groups. If there are any
typos or configuration mistakes, you can correct them before any of the
configuration files get messed up.
When the validation task runs successfully (“BUILD SUCCESSFUL” message
displays), you are ready to run ConfigEngine on “wp-modify-ldap-security”.
When you run this task, it’s recommended to stop the WebSphere Portal
servers, and keep the Dmgr and nodeagents running. After the task shows
“BUILD SUCCESSFUL”, restart the Dmgr, nodeagents, and WebSphere Portal
servers.
Congratulations! You should now have a working WebSphere Portal cluster
with standalone LDAP configuration to Microsoft Active Directory over SSL.
Appendix A
As suggested at beginning of this whitepaper, it’s easier to configure
LDAP security with a non-SSL port, and then add SSL configuration after
you have verified the security is working correctly. The basic steps for
enabling Certificate Services and for generating and installing the certificates
on Active Directory are the same.
The basic steps for importing the LDAP certificate into the WebSphere Application
Server SSL trust store are similar:
1. First, make sure the security is enabled
successfully with the non-SSL configuration.
2. Import the certificate to WebSphere Application
Server Deployment Manager through
the administrative console:
a. Navigate to Security - SSL certificate and
key management - SSL configurations.
b. Click "CellDefaultSSLSettings"
(or create your own SSL configurations).
c. Select "Key stores and certificates".
d. Select "CellDefaultTrustStore"
on the next panel and then "Signer certificates".
e. Click "Retrieve from port".
f. Enter the LDAP host name or IP address, the
SSL port (default 636), and an alias of your choice; click "Retrieve
signer information". This should pull the certificate directly from
the LDAP server.
g. Save the changes to the master configuration.
3. Navigate to Secure administration, applications,
and infrastructure:
a. Make sure that "Standalone LDAP Repository"
is selected; click Configure.
b. Check "SSL enabled".
c. Replace the LDAP port (389) with the SSL
port (636).
d. Save the changes.
4. Stop the DMGR, node agents, and the WebSphere
Portal servers.
5. Edit the file wimconfig.xml in directory
<![CDATA[<dmgr profile="profile">/config/cells/<cellname>/wim/config/
</cellname></dmgr>]]> and make the following changes in the LDAP repository section:
a. Change the LDAP port in "
"
from 389 to 636;
b. Set "sslEnabled" to True.
c. Enter "CellDefaultSSLSettings"
as the value for
sslConfiguration (it was null).
6. Restart the DMGR, node agents, and the WebSphere
Portal servers.
6 Resources
WebSphere Portal 6.1 Information Center:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp
Step-by-Step Cluster Guide for IBM WebSphere Portal v6.1:
http://www-01.ibm.com/support/docview.wss?rs=688&ca=port&uid=swg21313184
Secure Socket Layer configuration from WebSphere Application Server InfoCenter:
http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.nd.multiplatform.doc/info/ae/ae/csec_sslconfigs.html
Active Directory Certificate Services:
http://technet.microsoft.com/en-us/library/cc732625.aspx
IBM developerWorks WebSphere Portal Forum:
http://www.ibm.com/developerworks/forums/forum.jspa?forumID=168&start=0
7 About the author
Fang Feng has been a member of the WebSphere Portal Support team since
2002, specializing in security configuration, system administration, XML
configuration interface (XMLaccess), and administration portlets. He has
broad knowledge of various LDAP servers and configurations, and is a major
contributor to the developerWorks WebSphere Portal forum. He also co-authored
the IBM Redpaper publication, “
IBM
WebSphere Portal V6 Self Help Guide,”
and has been a major proponent of customer self assistance.