A Guide to Password Use in WebSphere Application Server


We've all been there—sitting at the login screen of the WebSphere® Integrated Solutions Console, trying to remember the password that was used when the product was installed last year. Or perhaps the certificate we've been using has just expired and the system is down. If you could just figure out where you stashed the keystore password, you could get your e-commerce site back up and running.

Whatever the scenario might be, nearly every WebSphere administrator has been in a position to desire a deeper understanding of how passwords are created, used, stored, and encrypted. In this paper, I'll go over the different types of passwords used inside of the WebSphere Application Server (WAS) and suggest recovery plans to help restore your server when passwords go awry.

Passwords are a necessary component of a secure IT system, but they can also be very challenging to manage. Lost, forgotten or poorly documented passwords are a very commonplace occurrence, but their frequency with which this problem occurs doesn't make it any less frustrating, time consuming or difficult to resolve.

The aim of this paper is to give the reader some background about WAS passwords and how they work as well as to share some tips that are likely to be helpful in getting a WebSphere system up and running again if there is a password snafu.

This paper contains an overview of each of the four types of passwords used in a WAS. However, before password troubleshooting can start, the user will have to determine whether their installation of WAS is even configured to use passwords, so let's start there.

Determining Whether Security is Enabled on a WAS

First things first. Back in the good ol' days (pre WebSphere v6.0), WAS was commonly configured to allow administrators to log in without a password. Now, times have changed. Although newer versions of WAS can be configured to run in a security disabled mode, that is certainly not a recommended configuration in this day and age. When running in the security disabled mode, administrative access to the server only requires a user name with no password. Therefore, any security for the application has to be enforced by the application itself. When running in security disabled mode, there is no access control to prevent unauthorized users from accessing the system. In order to prevent such a scenario, WAS should be configured in the security enabled mode whenever possible.

Figure 1: WebSphere Login Screen in Security Disabled Mode

However, running WAS in the security enabled mode adds layers of complexity to its use. Configuring the security enabled mode will necessitate the creation of a primary admin account and, after security is enabled, accessing the console will require both a valid username and a password.

Figure 2: WebSphere Login Screen in Security Enabled Mode

You can determine which security mode (enabled or disabled) is running on your server by checking security XML that can be found at WebSphere profile directory, in the config/cells/<CellName>/security.xml.

<?xml version="1.0" encoding="UTF-8"?> 
<security:Security xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:orb.securityprotocol="http://www.ibm.com/WebSphere/appserver/schemas/5.0/orb.securityprotocol.xmi" xmlns:security="http://www.ibm.com/WebSphere/appserver/schemas/5.0/security.xmi" xmi:id="Security_1" useLocalSecurityServer="true" useDomainQualifiedUserNames="false" enabled="true" cacheTimeout="600" issuePermissionWarning="true" activeProtocol="BOTH" enforceJava2Security="false" enforceFineGrainedJCASecurity="false" appEnabled="false" dynamicallyUpdateSSLConfig="true" allowBasicAuth="true" activeAuthMechanism="LTPA_1" activeUserRegistry="WIMUserRegistry_1" defaultSSLSettings="SSLConfig_1">

Once you enable security on your WAS, you can start defining users and passwords to access the system. There are four primary types of passwords:

  • Admin
  • Java Authentication and Authorization Service (JAAS)
  • User
  • Keystore

Each type of password has its own management considerations. We can split these four passwords into two broad categories:

  • Passwords that use one-way encryption (user and admin)
  • Passwords that use two-way encryption (JAAS and keystore)

JAAS Passwords

JAAS passwords are associated with user accounts that WebSphere uses to connect to external resources such as databases and messaging systems. WebSphere stores these JAAS passwords with a bidirectional or "two-way" encoding method, as opposed to the "one-way" method used with admin passwords. This is because WebSphere needs to communicate these credentials to external systems, so it needs to have a way in which to know the actual value of the password in order to share it with the external application.

You can tell if a password is encoded using an XOR algorithm because it will start with the text {xor}, and it will usually end with an = sign.

Decoding these passwords is relatively easy using a Perl script. A sample Perl script that will help you to decode your JAAS password will look something like this:

my $password=$ARGV[0]; 
$password =~ s/{xor}(.*)/$1/; 
$password =~ tr#A-Za-z0-9+/##cd; 
$password =~ tr#A-Za-z0-9+/# -_#; 
my $len = pack("c", 32 + 0.75*length($password)); my $unpackstring = unpack("u", $len . $password); 
my @chars = unpack('C*', $unpackstring); 
foreach my $char (@chars) {  push @c2, ($char ^= 0x5f); 
print pack('C*', @c2); 
print "\n"; 

To use the decoder script, just save the code into a file and then pass your encoded password as the parameter to the script, i.e.: decode {xor}NDomLz4sLA==. The program will then return your decoded password.

There are several WebSphere password decoders available online and they are generally effective. However, when using this type of decoder, it is important to take security concerns into consideration. Some of the online decoders perform all of the encoding/decoding using JavaScript within your browser. This means that your password is not passed along to the decoding website. Other decoders are form based in which your encrypted password is transmitted up to the website and then sent back to you across the internet. The passwords you decode using form-based decoders can be captured by the website offering the tool.

For a web-based decoder that does not capture your password information, you can use: http://www.esm-solutions.com/WebSphere/WebSphere_xor_password_tool.html

Keystore Passwords

Secure socket layer (SSL) communications are used to secure data in transit between two systems. Authentication of SSL communications involves using published certificates. These certificates are stored in a keystore database. These databases are encrypted and protected via password. Certificates are designed to expire after a specified period of time, usually between one and five years. When these certificates expire, new ones need to be created and added to your keystore database.

Because certificates expire relatively infrequently, the passwords to the keystore databases are often nowhere to be found when the time comes to add the new certificate to the database.

What to Do When Your Keystore Passwords Are Nowhere to Be Found

Luckily, since keystore databases need to be accessed by the WebSphere application, the passwords need to be stored in a manner that allows them to be decoded with the appropriate tools. The passwords are commonly stored using a stash file (a file that contains the "stash" encrypted text of the passwords). The stash file is usually found in the same location as the keystore, with a .sth file extension.

As was also the case with JAAS passwords, keystore passwords use two way encryption, allowing them to be recovered using a Perl script or decoder. "Stashed" passwords are stored in a binary format that makes it difficult to copy and paste the contents into a web browser. This means that online stash decoders need to have access to your stashed password in order to decode it. So, unlike with the JAAS passwords, I can't recommend a safe online decoder.

Passwords encrypted in a stash file can be recovered using the following decoding program. Just save this code to a file in the same directory as the stash file, and execute it passing the name of the stash as a parameter, i.e., unstash.pl mykeystore.sth

#!/usr/bin/perl my $file=$ARGV[0]; open F, $file; my $stash; 
read F, $stash, 1024; 
my @unstash=map {$_^0xf5} unpack ("C*", $stash); 
foreach $c (@unstash) {  last if $c eq 0;  printf "%c", $c; 
print "\n";  

Admin passwords

Generally when you install WebSphere, you are prompted to create an account when you enable security. Once the server is built and running, people don't habitually need to log in to it, so the password often gets forgotten. Passwords can also be lost during employee turnover, or if a consultant has installed the system but failed to transmit the passwords.

Any WAS will need to have at least one admin account defined in order to for security to be enabled. Although you can create and define as many admin accounts as you would like to on your WAS, each server that has security enabled will have a primary admin account. This primary account must have certain permissions, but these same permissions are often granted to additional admin accounts if there is more than one admin. It is necessary to log in to WebSphere using a valid admin username and password in order to gain access to the Integrated Solutions Console (ISC ).

By default, the WebSphere admin is defined in the WebSphere file repository, which is an XML file stored on the server that contains a list of defined users and their hashed passwords. The hashed passwords are secured using one-way encryption, so decoding them from their stored value back to their decoded or original state is not an easy task. It's not impossible to decode a password that has been encoded with one-way encryption, but it is very difficult to do and isn't necessarily worth messing with if you have other options. Luckily, you almost always do have other options, including the option set to the password to a known value.

What to Do When Your Admin Login Goes Wrong

If you're unable to log in to your WebSphere ISC using your admin account, verify that you are indeed using the correct user name. You can find the user name of the primary admin in the security xml.

<userRegistries xmi:type="security:WIMUserRegistry" xmi:id="WIMUserRegistry_1" serverId="" serverPassword="{xor}" realm="defaultWIMFileBasedRealm" ignoreCase="true" useRegistryServerId="false" primaryAdminId="wasadmin" registryClassName="com.ibm.ws.wim.registry.WIMUserRegistry"/> 

If you are sure that you are using the correct username, then the problem must be the password. Normally, the official recommendation in this situation is to disable security and then re-enable it. However, that requires reconfiguration of all your security configurations, which will take lots of time and effort.

Instead of disabling security, you can instead change the password within the WebSphere file registry to a known value. For example, the password "password" encrypts to the value

"U0hBLTE6anZycmwxMzV6NG5mOktNR3lyblFkcHpIa2h0SWprYjdKeHcvU2hEbz0K". So, if we edit the fileRegistry.xml and replace the password of the admin user with this known value, we'll now be able to log in using "password" as our password.

After we make this change, we just need to restart the WebSphere application server. Then we can log in using the new username and password. We can then go into the ISC and set the password to a more secure one.

<?xml version="1.0" encoding="UTF-8"?> 
<sdo:datagraph xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xmlns:sdo="commonj.sdo" xmlns:wim="http://www.ibm.com/WebSphere/wim">  <wim:Root> 
 <wim:entities xsi:type="wim:PersonAccount"> 
 <wim:identifier externalId="65c5897f-7129-41f2-ac0e-ae617d22d076" externalName="uid=virtuser,o=defaultWIMFileBasedRealm"  uniqueId="65c5897f-7129-41f2-ac0e-ae617d22d076" uniqueName="uid=virtuser,o=defaultWIMFileBasedRealm"/> 
 <wim:identifier uniqueName="o=defaultWIMFileBasedRealm"/> 

User Passwords

User passwords are generally the most straightforward types of WebSphere passwords to deal with. These passwords should be stored in a single direction encryption that cannot be recovered. However an administrator can reset the password through the ISC. Just navigate to the Manage Users option in the navigation pane.

Select the user whose password you wish to reset.

Then enter a new password.

Unlike JAAS and keystore passwords, which need to use two-way encryption in order to access external resources, user passwords should never be stored in a way that they can be decrypted, it is a security weakness if user passwords can be decoded, so single direction encryption is the best practice to use in order to avoid compromising your system.

If you're using the WebSphere file repository database, you can also reset your user passwords by following the same procedures for admin password recovery (by inserting a known password for a user). This scenario might also be useful for testing a user's account: a known password could temporarily be inserted for the user whose account is being tested and then their original password can be restored after the testing is complete. If you use this method, just be sure to save the original one-way hash and restore it to the file repository.xml after the testing is complete.

External Passwords

There are a number of other places that passwords may be stored for your WebSphere system (for it, not in it). Many times WebSphere can be integrated with Lightweight Directory Access Protocol (LDAP) so that user and admin accounts and passwords are maintained by the LDAP repository. Sometimes the passwords are stored inside of a database. This is generally used for user passwords that are managed internally to your application (for example).

In the event that your passwords are stored in an external repository, the recovery mechanism will be specific to that repository. If your administrator accounts are contained inside an external repository, recovery may require you to disable WebSphere security entirely and reconfigure the WebSphere security. In order to disable WebSphere security, you must modify the security.xml and turn the enabled setting from "true" to "false".

<?xml version="1.0" encoding="UTF-8"?> 
<security:Security xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:orb.securityprotocol="http://www.ibm.com/WebSphere/appserver/schemas/5.0/orb.securityprotocol.xmi" xmlns:security="http://www.ibm.com/WebSphere/appserver/schemas/5.0/security.xmi" xmi:id="Security_1" useLocalSecurityServer="true" useDomainQualifiedUserNames="false" enabled="false" cacheTimeout="600" issuePermissionWarning="true" activeProtocol="BOTH" enforceJava2Security="false" enforceFineGrainedJCASecurity="false" appEnabled="false" dynamicallyUpdateSSLConfig="true" allowBasicAuth="true" activeAuthMechanism="LTPA_1" activeUserRegistry="WIMUserRegistry_1" defaultSSLSettings="SSLConfig_1">  

Then after restarting your WAS, you'll be able to access the ISC without the use of a password. This scenario is most likely to occur in the event that you have a single LDAP configured for your administrator accounts. If that LDAP server becomes unavailable or the password to the admin account is lost, your only recourse will be to disable security.

Keep Calm and Carry On

This paper was designed to give you the necessary tools to handle the most common WebSphere password problems that are likely to occur in production environments. The methods that were outlined in this paper are designed to help minimize the impact to your servers while getting your system up and running again as quickly as possible.

When dealing with lost or misbehaving WebSphere passwords, it's important to keep calm and to bear in mind that there are workarounds for just about any scenario. So take a deep breath and carry on, confident in the knowledge that there is a way to get your system up and running.


About the Author

David Biondi is the founder and CEO of ESM Solutions, an IT consulting company that is recognized as an IBM Advanced Business Partner and is accredited across multiple IBM product groups. In addition to working as an IT consultant, David also takes pride in his work as an instructor and course director for Global Knowledge.

David has a strong commitment to broadening his knowledge base and keeping his skills cutting edge. He is ITIL Foundations certified and maintains current certifications on many IBM products including Tivoli and WebSphere. David is also pursuing a master's degree in computer science from Georgia Tech where he is focusing on artificial intelligence and machine learning.