Secure your applications using the IBM WebSphere sMash security model

Easily manage authentication and authorization

IBM WebSphere® sMash server provides built-in security mechanisms. You can secure your applications in various ways by enabling security in configuration files. In this article, learn about different types of authentication, file-based and LDAP-based security, and how to implement SSL security. Using an example application, set up access-based security measures to learn about the capabilities of IBM WebSphere sMash server.


Natasha Sharma, Software Engineer, IBM

Photo of Natasha SharmaNatasha Sharma has been with IBM ISL for almost four years. She holds a Master's degree in Computer Application from SNDT University, Bombay. Natasha is interested in Java/J2EE technologies, Web2.0 technologies, and LAMP (in open source).

Vijaykumar Ladla (, Software Engineer, IBM

Vijaykumar Ladla photoVijaykumar Ladla works at the IBM Development Lab in Pune, India, and is interested in networks, IT security, UNIX/Linux administration, and Tivoli tools. He holds a Bachelor of Engineering degree in Electronics and Communication from North Gujarat University.

25 January 2011

Also available in Chinese Japanese


The IBM WebSphere sMash server, based on the acclaimed Project Zero (see Resources), implements the authentication and authorization module by securing different roles and protecting resources. The IBM WebSphere sMash server ensures that your source code or resources are protected by restricting access. You have control over which user or group has access. Since security is a feature of IBM WebSphere sMash, you don't have to add dependencies—just enable security in the configuration files. IBM WebSphere sMash authentication uses the Java™ Authentication and Authorization Service (JAAS) to implement the security module.

In this article, learn how to exploit the security module in the IBM WebSphere sMash server. Through examples, explore how to tune the security features to meet your specific requirements.

The scenario

We created a downloadable application called onlineLibrarySimulation in a previous article, sMashing your application... the Ajax way. The application uses its own logic and code for authentication and authorization to permit access.

In this article, exploit IBM WebSphere sMash server's internal security module to achieve the same outcome, but with a better handle on the authorization. You will use the editing and adding attributes in the zero.config file (the main configuration file for WebSphere sMash server).

Security basics

Before diving into the security module, this section covers some basics about the processes available for securing your application or resource.

Authentication ensures that the user or group that is accessing the resource is permitted to do so (or, is a valid user or group for that resource).

Authorization is giving specific permission to a user or group to access a resource.

Accounting is a record or log of what the user or group has accessed.

This article focuses on basic authentication and the form-based authentication. IBM WebSphere sMash server implements the following types of authentication:

The basic authentication scheme assumes that the client will provide the authentication credentials for each realm that it is accessing. For more information see Resources.
The form-based authentication is primarily for web-based applications. It provides the client with a log-in form to enter the credentials and consequently authenticate the user.
Single sign-on
Single sign-on is the facility for a user to enter the same log-in credentials to log on and access multiple applications within an enterprise.
Programmatic login
The application creates its own log-in module that it uses for authentication.

For more detailed information refer to the WebSphere sMash documentation (see Resources).

Configuring security

Every IBM WebSphere sMash application has a zero.config file—the file that is the "brain" behind each application. Most of the application-related configuration is decided by, and configured in, this file.

  1. Open the zero.config file in your Appbuilder.

    It's a good programming practice to have a separate file, security.config, that contains the entire security-related configuration. This will add modularity to the application and will segregate the configuration by category.

    You'll create another file, security.config, for this purpose and include it in the zero.config file, as shown below.

    Listing 1. Including security.config in zero.config
    # Include the security configuration file
  2. Create a new file called security.config. To facilitate security, the first step is enablement using the code below.
    Listing 2. Enabling security: security.config
    # Enable Security

    Security will be turned on in the example application. When the application has enabled security, IBM WebSphere sMash server will store some information about the authenticated user on the client. The information is confidential, so it needs to be encrypted. To encrypt the information, IBM WebSphere sMash uses a secret key that is an encrypted string that can be generated by using Command Line Interface (CLI) commands.

  3. To generate the secret key for the application, you need to be in the application directory. Listing 3 shows an example.
    Listing 3. Generating secretkey
    cd onlineLibrarySimulation
    zero secretkey
    CWPZC2031I: Result        

    Each time you execute the zero secretkey command it will generate a different secret key. The key generated by your command may be different from the sample key generated here. Once this key is generated, the example will use it as an attribute in the security.config file.

  4. Add the following line of code to set the secret key in the file.
    Listing 4. Including the secret key: security.config
    # Secret Key

WebSphere sMash server uses the following user service types:

A flat-file-based user service
Uses the Lightweight Directory Access Protocol (LDAP) server as a user service
When neither LDAP nor file-based user service can provide the required functions, WebSphere sMash provides an extension.

This article illustrates the file-based and the LDAP user service.

Basic authentication configuration using file-based user registry

WebSphere sMash uses the file-based user service as the default. It makes use of a file, zero.users, that contains the users that have access to the application or are valid users of the application.

To create a user or group in zero.users for the example application, change directory to the application and issue the command zero user, as shown in Listing 5. The add- user wizard will be started.

Listing 5. Creating user/group: zero.users
cd onlineLibrarySimulation
zero user
CWPZC2114I: Entering interactive mode.
CWPZC2126I: Enter location of user file:
 [Press enter to use default of ./config/zero.users]:
CWPZC2120I: Type 'create' to create user, 'update' to update user or 'exit' when done.
CWPZC2121I: Creating new user.
CWPZC2127I: Enter username:
CWPZC2128I: Enter password:
CWPZC2129I: Enter group (or enter when done):
CWPZC2129I: Enter group (or enter when done):
CWPZC2115I: User 'natasha' was successfully added to the user file.
CWPZC2120I: Type 'create' to create user, 'update' to update user or 'exit' when done.
CWPZC2119I: The interactive mode of the user service command successfully terminated.

The output shows that the user natasha was successfully added to the file zero.users. Listing 6 shows a snippet of the contents of zero.users. The password is obviously encrypted.

Listing 6. zero.users

User natasha with an encrypted password has been added to the Admin group. The users accessing the application will be authenticated against this file. You can add multiple users for this application.

To enable basic authentication the following line of code needs to be added in the security.config file. The configuration in Listing 7 ensures that the resource or application is protected and needs authentication.

Listing 7. Including basic authentication: security.config
# Basic Authentication for our directory/methods
@include "security/basicAuthentication.config"
  "conditions": "(/request/path =~ /path_to_resources (/.*)?)"

Listing 8 shows how you can include authorization for the application. The code will permit only user natasha, a member of the group Admin, to access /path_to_resources(/.*)?.

Listing 8. Defining authorization through file-based user service: security.config
@include "security/authorization.config"{
   "conditions": "(/request/path =~ /path_to_resources(/.*)?)",
   "users" : ["natasha"] ,
   "groups" :["Admin"]   

When the application is accessed, IBM WebSphere sMash, with basic authentication enabled, will display a log-in page. Users need to authenticate by entering their log-in credentials (in this case, user natasha/welcometoIBM). You can also name the realm for the authentication pop-up by including the line of code in Listing 9 in the security.config file.

Listing 9. Setting the realm: security.config
# The realm
/config/security/realm="IIP Authentication for Online Simulation"

Figure 1 shows the log-in form.

Figure 1. Authentication for file-based basic authentication
Pop-up window entitled 'Authentication required' with fields for 'Name' and 'Password.'

On successful authentication you can now access the application. If the authentication is unsuccessful, users will get a 401 – Unauthorized Access error.

The basic authentication configuration using a flat file (/config/zero.users) user service is now complete. Remember, IBM WebSphere sMash server needs to be restarted every time you make a change in the configuration files.

Basic authentication configuration using LDAP user service

The configuration in Listing 7 did not include any details about the authentication method. The default file-based user service was activated.

In the configuration in Listing 10 below, the first line tells IBM WebSphere sMash server that it is using LDAP user service for authentication purposes. It then proceeds to LDAP-related configuration. The configuration needs to be customized with your server names and so forth.

Listing 10. Authenticating through LDAP: security.config
# LDAP Specific information for Authentication

/config/security/userservice/ldap += {
 		"jndiProviderUrl" : "Your LDAP Server",
 		"jndiSecurityAuthentication" : "simple",
 		"ldapSearchScope" : 2,
 		"ldapUserIdSearchFilterPattern" : "(&(mail={0})(objectclass=ibmPerson))",
 		"ldapUserIdBaseDn" : "ou=ldappages,o=<domain>.com",
 		"ldapGroupBaseDn" : "ou=memberlist, ou=<Group Name>,",
 		"ldapUserIdAttributeType": "mail"

To enhance or strengthen the security of the application, you can make a group on the LDAP server and restrict usage to only users who are a part of this group. This is similar to the Admin group created for the file-based user service, except this group exists on LDAP.

The code in Listing 11 authorizes users to use the application (and is very similar to Listing 8).

Listing 11. Defining authorization through LDAP user service: security.config
#uses group discovered through LDAP authentication.
@include "security/basicAuthentication.config"{
   "conditions": "(/request/path =~ /resources/system(/.*)?) && (/request/method =~
   "groups" :["Simulation-Group"]   

# The realm <OPTIONAL>
/config/security/realm="IIP Authentication for Online Simulation - using LDAP"

Once you restart the server, the users will be authenticated against LDAP.

Figure 2 shows the browser-generated authentication screen that pops up when users access the application.

Figure 2. Authentication for LDAP-based basic authentication
Same pop-up window as Figure 1, but this time for using LDAP-based authentication.

Basic authentication has some drawbacks and should ideally be used only in the development environment. One reason not to use basic authentication in a production environment is that the username and password of the user are not encrypted but only encoded and are sent to the server for every single transaction. Credentials could be intercepted, and they will remain valid until the user actually changes the password. The more important drawback is that basic authentication only logs you out if you close the browser and restart it.

Form-based authentication

Form-based authentication is a process whereby application owners create their own log-in form (as opposed to using the one provided by the browser). Form-based authentication is similar to basic authentication in terms of configuration, except that for the log-in page you point IBM WebSphere sMash server to the customized log-in page.

Create a log-in page called login.html under the /public folder. Listing 12 shows the sample code that is needed for login.html.

Listing 12. login.html
<form method="POST" action="" name="frmLogin">
<table border ="1" align="center" width="100%">
<input type="text" name="zeroUserName" id="zeroUserName">
<input type="password" name="zeroPassword" id="zeroPassword">
<td colspan="2">
<input type="submit" value="Submit" name="submit" id="submit"/>


There are some constraints on creating the custom form:

  • The username field and password field must be named zeroUserName and zeroPassword, respectively.
  • The <form> method must be POST.

Like basic authentication, form-based authentication also has three ways of authenticating. Listing 13 shows the file-based user service for form-based authentication.

Listing 13. security.config file for file-based user service form-based authentication

The code above informs IBM WebSphere sMash server that the log-in page will be found under /public and is called login.html. We're essentially pointing it to the customized log-in form.

The remaining configuration, except for one block, remains the same.

Listing 14. security.config file for file-based user service form-based authentication, continued
   "conditions": "(/request/path =~ /path_to_resources(/.*)?)"

   "conditions": "(/request/path =~ /path_to_resources(/.*)?)",
"users" : ["natasha"] ,
"groups" :["Admin"]

As indicated in Listing 14, only the first block of the configuration changes—just the type of authentication. Everything else stays constant.

Save the file, restart the server, and try to access the sample application.

Figure 3. Custom-defined log-in form
Log-in form with fields for 'Username' and 'Password' and a 'Submit' button.

When you try to access the application, IBM WebSphere sMash server redirects the browser to our predefined custom log-in page. When you enter the right credentials (natasha/welcometoIBM) you are shown the home page. Otherwise, you get an error.

This completes the form-based authentication configuration using a flat file (/config/zero.users) user service. As an independent exercise, you can try the form-based authentication using LDAP as a user registry. The steps are the same, as covered in Listing 10.

Securing the application using Secure Socket Layer (SSL)

Using security with your applications is always a good idea, but you also need to secure the information that you're using for authentication purposes. Assume you're using form-based authentication for your application. When users hit your application, they're required to enter their username and password, which is checked against either a flat file or LDAP. But, when the information is being passed from your application to the server, the information is not secured. You need to secure even the log-in page to ensure that the information (log-in credentials) sent from the client to the server is completely secure. You can enhance security by using Secure Socket Layer (SSL).

Prerequisite: Obtain a certificate from a trusted 3rd party SSL certificate authority by creating a CSR (Certificate Signing Request).

Before actually configuring SSL on the IBM WebSphere sMash server, let's have a short crash course in the basics of how SSL works. The following are SSL terms used in the rest of this article:

The file that contains the public and private keys. Public keys are stored as signer's certificates and are sent to the clients that request them. When you configure an application to accept requests using HTTPS, you must define a key store. This key store must contain the private keys that the application will use when negotiating an incoming HTTPS connection from a client.
The file that contains the public keys, which are stored as signer certificates from the target servers that you've deemed trustworthy
Creating a TrustStore
Extract the public key from the server KeyStore and add it into the TrustStore as a signer certificate.
SSL certificate
Sent from the server to the client during SSL authentication to confirm the identity of the server

When a client encounters the application over an https:// URL, SSL kicks in on the server and uses the following process:

  • Server sends the client a public key from its own keyStore and certificate.
  • Browser at the client end confirms if the certificate is issued by a trusted third party authority or if it is still valid and related to the contacted site.
  • If yes, then the client uses the public key to encrypt random symmetric encryption key and sends it to the server, along with the encrypted URL required and other encrypted HTTP data.
  • The server decrypts the symmetric encryption key using its private key and uses the symmetric key to decrypt the URL and HTTP data.
  • The server sends back the requested HTML document and HTTP data that are encrypted with the symmetric key.
  • The client decrypts the HTTP data and HTML document using the symmetric key and displays the information.

Configure the server

This section explores a few brief scenarios for configuring SSL on the servers.

The first scenario involves a single instance of IBM WebSphere sMash server running in a single application. In this case, you need to secure only the communication between the client and the server.

Open up the zero.config file. Or, you can create your own file (such as ssl.config), include it in the zero.config file, and add the information in Listing 15.

Listing 15. Editing zero.config to enable SSL
/config/https/port = 8085 
/config/https/sslconfig = { 
        "keyStore": "./config/mykey.jks", 
        "keyStorePassword": "wrapper", 
        "keyStoreType": "JKS" 

The first line in Listing 15 declares a port for the HTTPS (HTTP over SSL). This port must be different from your normal HTTP port. The other code in Listing 15 elaborates about the SSL configuration: the keyStore file name, password, and the type. These are the mandatory parameters needed for an SSL configuration. Password can be encoded through the zero command and can be handled in a more secure way (as opposed to the clear text). Listing 16 shows the method to encode the password.

Listing 16. Encoding the password using zero encode
zero encode wrapper
CWPZC2029I: Input
CWPZC2030I: Result

When the client or browser hits the URL using HTTPS, the log-in page will be displayed right away. The log-in credentials that are passed to the server for authentication will be secured with SSL.

The next scenario involves securing data between two applications. Each application resides on a separate IBM WebSphere sMash server, as shown in Figure 4.

Figure 4. Two applications communicating with SSL
Diagram showing the client browser connecting to two applications.

Application1 should have configured both the keyStore and the trustStore. Application2 should have configured just the keyStore to store SSL certificates.

Listing 15 showed how the keyStore was configured. Listing 17 below illustrates the configuration needed for a trustStore.

Listing 17. Editing zero.config for enabling SSL
/config/connection/destinations += { 
 "https://localhost:8085/*" : { 
 	     "connection" : { 
            "protocol" : "https", 
            "config" : {"httpsConfig" : "myHttpsConfig"}  

@include "ssl/defaultTrustStore.config" { 
   "configKey" : "/config/connection/https/myHttpsConfig", 
   "disableTrustVerification" : "true"


In this article you learned about enhancing security for your applications by using the security mechanisms in IBM WebSphere sMash server. Through the exercises you:

  • Enabled security in the sample configuration files
  • Examined file-based and LDAP-based security mechanisms using basic and form-based authentications and authorizations
  • Implemented SSL security in the sample application

There are many more permutations and combinations to secure your application using the built-in security module of IBM WebSphere sMash server. This article covers just the tip of the iceberg. Now that you know the basics you can further explore the feature-rich security module.



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Web development on developerWorks

Zone=Web development, WebSphere
ArticleTitle=Secure your applications using the IBM WebSphere sMash security model