Setting Up An LDAP Repository

Before we do anything else we now need to make sure our users can login.

WebSphere only has an internal file repository that will only contain the “wasadmin” entry we created when installing.  The users and groups we want to be able to use Connections aren’t in that File Repository, they are in a LDAP directory (or directories) somewhere.  We need to tell WebSphere’s deployment manager where to find and authenticate those users.

First we need to consider where our directory is going to be and if there will be one or multiple directories (if all users aren’t held in one place).  For instance, if all my users login to Active Directory I might use that, or I might use Domino which itself could be running Directory Assistance.

When deciding on LDAP directory configuration:

  1. As few directories as possible should be referenced
  2. Every user should have a unique key in the directory
  3. If you use multiple directories each user should appear only once with their unique key. If my key is my email,, then there should only be one entry with that name across all the directories we reference.
  4. The directory should be a trusted source with strong password validation

In this case we’re going to choose a single Domino LDAP server but we could have just as easily chosen Active Directory or many other LDAP directory sources.

Adding external directories in WebSphere is known as adding Federated Repositories. Before modifying or adding any federated repository I like to take a backup of the Deployment Manager.  Very often if the LDAP configuration is wrong you can end up locking yourself out of WebSphere entirely and you will need to restore from that backup.

To backup go to the /bin directory under /profiles/Dmgr01 and run:

./ <locationofzipfile> -nostop


To add or modify a Federated Repository we go to Global Security in the ISC and choose “Configure” next to the “Available realm definitions – Federated repositories”:


We are going to add an LDAP repository:


Here we enter the details of the LDAP directory source we’re going to use.  In this case I have a Domino server running LDAP on hostname and secure port 636.  Note how the “Require SSL Communications” checkbox is enabled, you must select this if you are connecting to LDAP securely.

Choosing the right Directory type from the drop down list ensures that the LDAP query syntax is correctly formed for the directory you are accessing. Selecting “IBM Lotus Domino” when pointing to an Active Directory server will prevent the directory from working.

I do not recommend using bind credentials to login to your LDAP directory unless you are also using a secure SSL protocol to connect. If you are connecting using 389 or another non-encrypted port I would suggest an anonymous bind.

The field “Federated repository properties for login” will determine what values can be used to login.  These are all LDAP attributes that map to fields in the source directories. If possible in a Connections environment we want to have “uid” listed first.  UID maps to the value ‘shortname’ in Domino LDAP, ‘mail’ maps to the internet mail address and ‘cn’ maps to my fullname.  With the values set here as uid,mail,cn I will be able to login using variations of my name including:

Gabriella Davis
Gabriella Davis/Turtle

Finally the value for failover server can be used to point to other identical directories. Although many customers use a separate load balancer to handle LDAP failover, WebSphere actually responds faster to multiple LDAP failover servers entered here rather than waiting for a load balancer to return a new host.

WebSphere will attempt to validate all the information on this screen including hostname, bind credentials and port when we save. The next step is to define the Unique Distinguished Name for entries in this repository. Whatever we choose here, it must be unique across all directories.skitch.6

For this directory I could use the value O=Turtle and that will restrict valid users to just those with a hierarchical name containing the Turtle organisation e.g Gabriella Davis/Turtle.  In a Domino directory, unique for LDAP sources, not all entries are hierarchical (groups names for instance are flat) so with this configuration WebSphere won’t recognise any Domino groups.  One option to workaround that is to use the value “root” for the Unique distinguished name which will tell WebSphere to recognise all organisations and even flat names or groups.


We also need to make sure the Group definitions are correct for the directory type we are using.  For Domino the attribute use for defining a group is called “dominoGroup” not the default “groupofNames” and the member attribute is called “member”.

Once the repository is configured we log out of the ISC and restart the deployment manager, then we log back in and go to Users and Groups – Manage Users / Manage Groups to confirm that all our LDAP users and groups are found and displayed.

If I can’t log back in after a restart I can rollback to the earlier backed up instance of the deployment manager and start over.


Now that the Federated Repository is set up the next thing we want to do is add additional accounts that can administer the ISC, including a LDAP account which will become the Connections Administrator.  Here we are using an account called “connadmin” that I created in the Domino directory.  Once the account is added we can test that it works by logging out of the ISC and attempting to login as “connadmin”.

The WebSphere Integrated Solutions Console

Once WebSphere is installed I want to do two things, login to the admin interface and backup the environment so I have a “start point”

WebSphere’s admin interface is called the Integrated Solutions Console and is the same regardless of what product you are working with.

To login to the ISC

:9060 which is the non secure port will redirect to 9043


Login here using the credentials created during the original WebSphere install, these credentials are created and stored in the WebSphere default repository during install (and will always be your “backdoor” into the server).


Once logged in I know that WebSphere is correctly installed and running and I can logout and move onto my next task and come back to here later.


At this point, and before I start further configuration I like to take a backup of the WebSphere environment.  This is simple to do using the backupconfig command.

From the Dmgr profile location
/opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin type
./ /opt/Backups/ -nostop

The location and filename of the backup can be anything.

The -nostop option tells WebSphere not to stop its services before it does a backup.  By default it will stop the Dmgr to avoid anyone making any updates whilst it is backing up but since I know I am the only one working on here I’m happy to take a “live” backup instead.



A WebSphere Primer..

Before you start installing WebSphere you should really understand some core concepts behind its architecture and options. This is going to make it easier to decide where and how to build servers.

Connections uses WebSphere 8.5.5 Network Deployment.  When you go to install your Connections applications you’re going to need at least one instance of WAS to install onto, however a single WAS install may be running multiple independent servers each running different applications. Our Connections environment could therefore be a single host machine with multiple WebSphere servers or multiple host machines each with single WebSphere servers.

Every WAS server must be installed into what is called a Node  and similarly each Node must exist inside what is called a Cell. For Connections101 I am building two “nodes” on two physical hosts with each running multiple WAS instances hosting different applications.

Each Cell has one process called a Deployment Manager whose job it is to manage the configuration settings and changes for all servers in its cell.

Each server then also has another parent process called the Node Agent. Its job is to talk to the Deployment Manager and receive the latest sync information (XML files) for the server it is managing. It’s also responsible for starting and stopping the server.  You cannot start any WAS server unless its corresponding node agent is also running.  You can’t stop any WAS server unless its corresponding node agent is also running.

Here’s an example diagram of how the architecture for Connections101 might be designed. In this design I have built a deployment manager and two separate nodes which are full clusters of each other.


In WebSphere terms only individual servers need to be clustered, not entire nodes so I could easily just cluster the busiest components in my environment such as Cluster2 which contains search , homepage and profiles.  This is why it’s important to think about WebSphere design as well as the locations of the applications and which ones you may want to cluster, before starting the install.

The Deployment Manager directory holds XML files for every server.  It copies those files into the individual server directories when you Sync the servers.   You do all your configuration by logging into the administrative interface for the deployment manager (the Integrated Solutiions Console) and from there any changes push out to the managed servers.

Based on this there are important things to bear in mind

  1. Each server will have only one node agent
  2. Each node agent can manage multiple servers
  3. So from this we know that every single WAS cell will have, at minimum, one deployment manager, one node agent and the application server itself.
  4. Changes made to server configuration on the deployment manager will need to sync down to the nodes before the server itself will pick them up
  5. Syncing basically results in copies of the XML files for a server being sent from the Deployment Manager’s directory to the Server’s directory
  6. This means there will be at least 2 copies of every configuration file for a server, one owned by the Deployment Manager and one by the Server
  7. If you try and change a server setting in the Deployment Manager without syncing, the server won’t take the change
  8. If you try and change a server setting directly on the server without updating the Deployment Manager, it will be overwritten
  9. If you install the deployment manager and server on the same machine, it still has to sync to push out changes.  From a file system perspective, there are multiple copies of the same files.  If the servers are on different boxes the files will be too,  WAS is designed to work as if all servers are physically different and isolated from each other regardless of hardware infrastructure.  Sometimes you will be asked to locate a certain file, and you may find more than one.  It’s important to learn the locations of files and their purposes (i.e are you looking at the deployment manager’s copy of the file, or the servers’).  We will get to file locations in a later post.
  10. There are a lot of restarting servers required when working with WebSphere since server changes don’t just happen on the fly, they require a sync and a server restart to take effect as the XML files can be read as the server starts up.