Enabling security with federated repositories

To use WebSphere Commerce with LDAP, you must configure WebSphere Application Server Administrative Security with Federated Repositories. The WebSphere Commerce Integration Wizard does the configuration for you. The federated repositories consist of one or more LDAP servers and a built-in, file-based repository.

The file-based repository stores the WebSphere Application Server Primary Administrative User. Even if the LDAP server is unavailable, the Primary Administrative User can still log on to the WebSphere Application Server administrative console.

Before you begin

If you do not require integration with an LDAP server and want to only enable security with the WebSphere file-based user registry, follow the instructions in Enabling security with WebSphere file-based user registry only.

Before you start the WebSphere Commerce Integration Wizard, ensure that you complete the following tasks:

  • Ensure that the WebSphere Application Server administrative server is running.
  • If your WebSphere Commerce Server is managed by a WebSphere Application Server deployment manager, make sure the following are started:
    • WebSphere Application Server deployment manager server (dmgr).
    • The node agent on the local WebSphere Commerce machine.
    • WebSphere Commerce application server (server1) on the local WebSphere Commerce machine.
  • WebSphere Commerce DeveloperEnsure that WebSphere Application Server is not started.
  • Ensure that the database is started.
  • If WebSphere Application Server security is already enabled by using an Operating System registry, you must disable WebSphere Application Server security.
  • If you are using SSL with the LDAP server, ensure that WebSphere Application Server administrative security (global security) is enabled by using the file-based registry. Otherwise, the configuration scripts fail when not enabled in advance. Follow the steps in Enabling security with a WebSphere file-based user registry only.
    Important: Ensure that you complete the following steps:
    • Restart the WebSphere Application Server.
    • Update the WebSphere Commerce configuration according to the steps defined in the task. For example, complete the steps to update the WebSphere Commerce Configuration Manager after you configure the administrative security. Or, for WebSphere Commerce Developer, complete the manual steps to update the wc-server.xml file and the WebSphere Commerce Test Server properties in Rational Application Developer.
  • If you are planning to set up WebSphere Commerce to connect with multiple LDAP servers, understand the sample configuration steps in Federating two LDAP servers with a common root organization.
Attention: WebSphere Commerce does not support rolling back to use the database repository after you configure WebSphere Commerce to use an LDAP repository.

About this task

You can enable WebSphere Application Server security with Federated Repositories by using one of the following methods:
  1. Using the WebSphere Commerce Integration Wizard
  2. Using the command line

Procedure

To enable WebSphere Application Server security with Federated Repositories by using the automated WebSphere Commerce Integration Wizard:
  1. Open the WebSphere Commerce Integration Wizard.
    • SolarisLinuxAIXWC_installdir/bin/WCIntegrationWizard.sh
    • WindowsWC_installdir\bin\WCIntegrationWizard.bat
    • WebSphere Commerce DeveloperWCDE_installdir\bin\WCIntegrationWizard.bat
  2. Verify the prerequisites. Click Next.
  3. Select your WebSphere Commerce instance name. Enter and confirm your database password. Click Next.
  4. Select WebSphere Application Server security with Federated Repositories as the integration task. Click Next.
  5. Enter the information specific to your LDAP server to configure LDAP as the user repository for the WebSphere Commerce instance.
    The following fields are available, depending on your LDAP server configuration:
    • LDAP type
    • LDAP host name
    • LDAP port
    • Enable SSL option
    • Truststore file path (Java keystore format)
    • Truststore password and verification
    • LDAP administrator DN
    • LDAP administrator password and verification
    • WebSphere Commerce root organization DN
    • WebSphere Commerce default organization DN
    • User RDN prefix
    • User object class
    • Organization object class
    • Organizational unit object class

    For more information about these fields, see the WC_installdir/components/ldap/properties/vmm.properties file.

    After you enter the information specific to your LDAP server, click Next.

    Note: The LDAP administrator DN and password is not used at run time. The LDAP administrator DN is used only by the WebSphere Commerce Integration Wizard to ensure that the specified Default Organization and Root Organization exist on the LDAP server.
  6. Enter the information specific to your LDAP server to configure WebSphere Application Server security for the WebSphere Commerce instance.
    The following fields are available, depending on your LDAP server configuration:
    • Realm name
    • WebSphere Application Server primary administrative user
      Important: Ensure that this user does not exist on the LDAP server or federated repositories.

      After WebSphere Application Server Administrative Security is enabled, this user can log on to the WebSphere Application Server administrative console. If WebSphere Application Server Administrative Security is already enabled, specify the existing primary administrative user. If WebSphere Application Server administrative security is not enabled, specify a user that does not exist in any of the federated repositories (LDAP server or WebSphere Application Server file repository) to create the user in the WebSphere Application Server file repository: wasprofile\config\cells\localhost\fileRegistry.xml. This user ensures that the primary administrative user can log on to the WebSphere Application Server administrative console, even when the LDAP server is unavailable.

    • WebSphere Application Server primary administrative user password and verification
    • LDAP base DN
    • LDAP bind DN

      The LDAP bind DN is used at run time to search, read, and update the LDAP server, depending on how the ldapentry.xml file is configured. For example, if the ldapentry.xml is configured such that synchronization is only from LDAP to the WebSphere Commerce database, then the bind DN user does not require update access to the LDAP server.

    • LDAP bind DN password and verification
    • LDAP user search filter string

    For more information about these fields, see the WC_installdir/components/ldap/properties/vmm.properties file.

  7. Optional: Enable application security. In general, application security is not advised because of performance implications.
    1. Select Enable Application Security.
    2. Complete the following fields:
      • WebSphere Commerce RunAs ID DN
      • WebSphere Commerce RunAs ID DN password and verification
  8. Click Next. Verify the summarized information.
  9. Click Next.
    A confirmation message displays: 
    WebSphere Commerce integration has successfully completed
  10. Click Finish to complete the WebSphere Commerce Integration Wizard.
  11. Verify that the configuration is complete.
    Search for the "Feature 'ldap' enablement completed successfully." string in the log file:
    • WebSphere Commerce DeveloperWCDE_installdir/logs/enableldap_timestamp.log
    • SolarisLinuxAIXWindowsWC_installdir/instances/instance_name/logs/enableldap_timestamp.log
  12. Manually configure these additional WebSphere Application Server security properties:
    1. WebSphere Commerce DeveloperConfigure the WebSphere Commerce Test Server properties.
      1. Right-click the server; then clickOpen.
      2. Navigate to the Security panel.
      3. Select Security is enabled on this server.
      4. Enter the user ID and plain-text password for the current active authentication settings.
        Note: The user ID and password must be the same as the WebSphere Application Server Primary Administrative User provided by using the WebSphere Commerce Integration Wizard.
      5. Select Automatically trust server certificate during SSL handshake.
    2. Optional: WebSphere Commerce DeveloperIf Application Security is enabled, configure security in WebSphere Commerce Developer.
      1. Open WebSphere Commerce Developer.
      2. Open the META-INF\ibm-application-bnd.xml file in the WebSphere Commerce EAR project. Click the Design view.
      3. Expand and select Security Role (WCSecurityRole).
      4. Click Add, select User and click OK.
      5. Under the Details heading, enter the distinguished name of the RunAs ID user.
      6. Save your changes.
  13. Restart WebSphere Application Server.

What to do next

WebSphere Commerce DeveloperIntroduced in Feature Pack 2If you are working in your development environment and you enabled application security, you must also enable application security on your search server. For more information, see Securing the WebSphere Commerce search server.

Using the command line

Procedure

Alternatively, enable WebSphere Application Server security with Federated Repositories by using the command line. For example, when you want to use an LDAP Version 3 server other than one that is supported by the WebSphere Commerce Integration Wizard.

The WebSphere Commerce Integration Wizard supports the following LDAP server types:
  • IBM Tivoli Directory Server
  • Lotus Domino Enterprise Directory Server
  • Sun Java System Directory Server
  • Windows Active Directory
  • Novell eDirectory
For IBM i OS operating systemNote: Use the command line option for IBMi.
  1. Copy the components/ldap/properties/vmm.properties file to the following directory:
    • WC_installdir/instance_name/properties/vmm.properties
    • WebSphere Commerce DeveloperWCDE_installdir\setup\vmm.properties
  2. Modify the file as appropriate.
    For example, if you want to use another LDAP Version 3 compliant server type, specify vmm.ldapType=CUSTOM.
    Sample values are shown in the following snippet:
    #-----------------------------------------------------------------
# Licensed Materials - Property of IBM
#
# WebSphere Commerce
#
# (C) Copyright IBM Corp. 2006, 2010 All Rights Reserved.
#
# US Government Users Restricted Rights - Use, duplication or
# disclosure restricted by GSA ADP Schedule Contract with
# IBM Corp.
#-----------------------------------------------------------------

# LDAP server type
#     Accepted values: (IDS, DOMINO, SUNONE, AD, NDS, CUSTOM)
#         IDS = IBM Directory Server
#         DOMINO = IBM Lotus Domino
#         SUNONE = Sun Java System Directory Server
#         AD = Microsoft Windows Active Directory
#         NDS = Novell Directory Services
#         CUSTOM = Custom 
#--------------------------------------------------------
vmm.ldapType=CUSTOM

# Fully qualified LDAP server host name
#--------------------------------------------------------
vmm.ldapHost=wcinstall08.torolab.ibm.com

# LDAP server port number
#--------------------------------------------------------
vmm.ldapPort=389

# Specifies whether the LDAP server requires an SSL connection
# 	Accepted values are: (true, false)
#--------------------------------------------------------
vmm.ldapWithSSL=false

# The keystore file path for SSL commnication to LDAP
#--------------------------------------------------------
vmm.keystorePath=

# The keystore password 
# (To avoid decrypting warnings in the log, it is strongly recommended to use 
# the ASCII encrypted string generated from the <WCInstallDir>/bin/wcs_encrypt.bat 
# command without the merchant key option.)
#--------------------------------------------------------
vmm.keystorePassword=

# LDAP search base distinguished name
#--------------------------------------------------------
vmm.baseDN=o=root organization

# LDAP administrator distinguished name
#--------------------------------------------------------
vmm.ldapAdminDN=cn=root

# LDAP administrator password
# (To avoid decrypting warnings in the log, it is strongly recommended to use 
# the ASCII encrypted string generated from the <WCInstallDir>/bin/wcs_encrypt.bat 
# command without the merchant key option.)
#--------------------------------------------------------
vmm.ldapAdminPassword=EaDPFd9VAf0=

# LDAP user search filter
#--------------------------------------------------------
vmm.ldapUserFilter=(&(uid=%v)(objectclass=inetOrgPerson))

# LDAP user prefix (for example, uid)
#--------------------------------------------------------
vmm.userPrefix=uid

# LDAP organization prefix (for example, o)
#--------------------------------------------------------
vmm.orgPrefix=o

# LDAP organizational unit prefix (for example, ou)
#--------------------------------------------------------
vmm.orgUnitPrefix=ou

# LDAP user object class (for example,  inetOrgPerson)
#--------------------------------------------------------
vmm.userObjClass=inetOrgPerson

# LDAP organization object class
#  (for example, organization)
#--------------------------------------------------------
vmm.orgObjClass=organization

# LDAP organizational unit object class
# (for example,  organizationalUnit)
#--------------------------------------------------------
vmm.orgUnitObjClass=organizationalUnit

# LDAP bind distinguished name
#--------------------------------------------------------
vmm.bindDN=cn=root

# LDAP bind password
# (To avoid decrypting warnings in the log, it is strongly recommended to use 
# the ASCII encrypted string generated from the <WCInstallDir>/bin/wcs_encrypt.bat 
# command without the merchant key option.)
#--------------------------------------------------------
vmm.bindPassword=EaDPFd9VAf0=

# A full DN that maps to the WebSphere Commerce root organization
#--------------------------------------------------------
vmm.rootOrgDN=o=root organization

# A full DN that maps to the WebSphere Commerce default organization
#--------------------------------------------------------
vmm.defaultOrgDN=o=default organization,o=root organization

# Specifies the property names to use to log into the application server.
# This field takes multiple login properties, delimited by a semicolon (;).
# For example, uid;mail. All login properties are searched during login.
# If multiple entries or no entries are found, an exception is thrown.
# For example, if you specify the login properties as uid;mail and the login ID as Bob,
# the search filter searches for uid=Bob or mail=Bob. When the search returns a single entry,
# then authentication can proceed. Otherwise, an exception is thrown.
#--------------------------------------------------------
vmm.ldapLoginProp=uid;cn

# The realm name, default to WC_<instanceName>_Realm.
#--------------------------------------------------------
vmm.realmName=myrealm

# The primary admin user id for the administrative security.
# If global security is already enabled, input the primary user
# currently using.
# Otherwise, input a user which does not exist in the federated
# repositories, the tool will create it into the WebSphere Application
# Server built-in file base user repository.
#--------------------------------------------------------
vmm.primaryAdminId=configadmin

# The primary admin user password for the administrative security.
# (To avoid decrypting warnings in the log, it is strongly recommended to use 
# the ASCII encrypted string generated from the <WCInstallDir>/bin/wcs_encrypt.bat 
# command without the merchant key option.)
#--------------------------------------------------------
vmm.primaryAdminPwd=Ua4xMY1lGEqYbwa0gxDxGg==

# Specifies whether to enable application security. (Accepted values are: true / false)
#--------------------------------------------------------
vmm.enableAppSecurity=true


# The WAS security user ID (The RunAs User ID, only required
#  when vmm.enableAppSecurity=true )
#--------------------------------------------------------
vmm.securityID=uid=rudy,o=default organization,o=root organization

# The WAS security user password (The RunAs user password,
#  only required when vmm.enableAppSecurity=true)
# (To avoid decrypting warnings in the log, it is strongly recommended to use 
# the ASCII encrypted string generated from the <WCInstallDir>/bin/wcs_encrypt.bat 
# command without the merchant key option.)
#--------------------------------------------------------
vmm.securityPwd=xK36ck80s6GCL9+YsULolg==
  3. Run the following command:
    
config_ant.bat -buildfile WC_installdir/components/common/xml/enableFeature.xml 
-DinstanceName=instance_name -DfeatureName=ldap -DdbUserPassword=db_password
    WebSphere Commerce Developer
    enableFeature.bat -DfeatureName=ldap
  4. Optional: WebSphere Commerce DeveloperIf Application Security is enabled, configure security in WebSphere Commerce Developer.
    1. Open WebSphere Commerce Developer.
    2. Open the META-INF\ibm-application-bnd.xml file in the WebSphere Commerce EAR project. Click the Design view.
    3. Expand and select Security Role (WCSecurityRole).
    4. Click Add, select User and click OK.
    5. Under the Details heading, enter the distinguished name of the RunAs ID user.
    6. Save your changes.

What to do next

WebSphere Commerce DeveloperIntroduced in Feature Pack 2If you are working in your development environment and you enabled application security, you must also enable application security on your search server. For more information, see Securing the WebSphere Commerce search server.