Introduction

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.

Back to top

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).

Back to top

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:

Basic

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.

Form-based

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).

Back to top

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 @include"security.config"

   
   

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 @include"security/enableSecurity.config"

   
   

   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 BzlB6HMtLqQfCSq9t/2pbA==

   
   

   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 /config/security/secretKey="BzlB6HMtLqQfCSq9t/2pbA=="

   
   

WebSphere sMash server uses the following user service types:

File-based

A flat-file-based user service

LDAP

Uses the Lightweight Directory Access Protocol (LDAP) server as a user service

Extending

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.

             
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.
create
CWPZC2121I: Creating new user.
             
CWPZC2127I: Enter username:
natasha
CWPZC2128I: Enter password:
xxxxx
CWPZC2129I: Enter group (or enter when done):
Admin
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.
exit
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.

             
natasha:c2702813148331721942c852a45b86e0:Admin
         

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.

# 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(/.*)?.

@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.

 
           
# The realm
/config/security/realm="IIP Authentication for Online Simulation"

Figure 1 shows the log-in form.

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.

# LDAP Specific information for Authentication
/config/security/userservice/registryType="ldap"

/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>,o=ibm.com",
 		"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).

#uses group discovered through LDAP authentication.
@include "security/basicAuthentication.config"{
   "conditions": "(/request/path =~ /resources/system(/.*)?) && (/request/method =~
      (POST|GET|PUT|DELETE)) ",
   "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.

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.

<form method="POST" action="" name="frmLogin">
<table border ="1" align="center" width="100%">
<tr>
<td>
<label>Username:</label>
</td>
<td>
<input type="text" name="zeroUserName" id="zeroUserName">
</td>
</tr>
<tr>
<td>
<label>Password:</label>
</td>
<td>
<input type="password" name="zeroPassword" id="zeroPassword">
</td>
</tr>
<tr>
<td colspan="2">
<input type="submit" value="Submit" name="submit" id="submit"/>
</td>
</tr>
</table>
</form>

</body>
</html>

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.

             
@include"security/formLoginURL.config"{
"formLoginPage":"/login.html"
}

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.

@include"security/formAuthentication.config"
{
   "conditions": "(/request/path =~ /path_to_resources(/.*)?)"
}

@include"security/authorization.config"{
   "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.

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.

Back to top

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).

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:

KeyStore

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.

TrustStore

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.

/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.

zero encode wrapper
CWPZC2029I: Input
mypassw0rd
CWPZC2030I: Result
<xor>KC0+Ly86LQ==

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.

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.

/config/connection/destinations += { 
 "https://localhost:8085/*" : { 
 	     "connection" : { 
            "protocol" : "https", 
            "config" : {"httpsConfig" : "myHttpsConfig"}  
      } 
   } 
} 

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

Back to top

Summary

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.

Resources

Learn

• Learn all about Project Zero (WebSphere sMash Server).
  
  
• Read HTTP Authentication: Basic and Digest Access Authentication (RFC 2617), the specification for HTTP's authentication framework, the original Basic authentication scheme, and a scheme based on cryptographic hashes, referred to as "Digest Access Authentication."
  
  
• Learn more about IBM WebSphere sMash authentication and authorization.
  
  
• Explore how your application can take advantage of WebSphere sMash security.
  
  

Get products and technologies

• Download WebSphere sMash.
  
  
• Download IBM product evaluation versions or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  

Discuss

• Discuss a variety of topics in the Project Zero forum.
  
  
• Create your developerWorks profile today and set up a watchlist on WebSphere sMash. Get connected and stay connected with developerWorks community.
  
  
• Find other developerWorks members interested in web development.
  
  
• Share what you know: Join one of our developerWorks groups focused on web topics.
  
  

About the authors

Natasha 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 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.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• The scenario
• Security basics
• Configuring security
• Securing the application using SSL
• Summary
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere sMash
• Briefing: Project Zero and WebSphere sMash
• Buy: WebSphere sMash

Dig deeper into Web development on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers