Securing Web Applications or Web Services with HTTP Basic Authentication on IBM WebSphere 7

The IBM WebSphere Application Server is one of the most used Application Server in Enterprises, but for sure not, because it’s so easy to use for developers ;-) Here you find a description to enable application security with HTTP Basic Authentication on WebSphere 7 (Java EE 5) for example to secure a web application or a webservice. For testing we choose a file based user realm, which is the easiest way to administer users and groups. In production you may configure your LDAP directory or another user realm of course.

We have to perform the following steps:

  • Enable Application Security in WebSphere Admin Console
  • Define role and protected resources in your web application’s web.xml
  • Define user and role mapping in application.xml and ibm-application-bnd.xml
  • Add application user to user repository
  • Make a test call

1. Enable Application Security in WebSphere Admin Console

Before you can do anything with security in WebSphere you have to ensure that application security is enabled in your server. You will find that options page in the Admin Console under “Security”/”Global Security”.

Enable Application Security in Admin Console

Enable Application Security in Admin Console

To use a file based user realm you have to configure “Federated repositories” under “User account repository”. If you create a new server profile from scratch, this should be the default setting. If you have to use an existing server profile ensure that “Federated repositories” are configured in the following way:

Create File Based User Realm in Admin Console

Create File Based User Realm in Admin Console

Hint: To be able to enable application security it’s important that you did create your server profile in the Profile Management Tool (PMT) with administrative security. That means you protect the Admin Console by a user/password login. I was not able to add administrative security to an existing server profile which initially was created without!

Enable Administrative Security in PMT

Enable Administrative Security in PMT during profile creation

2. Define role and protected resources in your web application’s web.xml

This step is fully standard Java EE, nothing special with WebSphere. You have to define protected web resources and roles which are allowed to access these resources. A web resource is a relative URL inside your application combined with the HTTP access method (GET, PUT, HEAD, TRACE, POST, DELETE).

Let’s assume you have a web service under the relative url /quoteservice and you want to restrict access to all autheticated users. The resulting web.xml will contain the following lines:




This is the longest section. First you define a web resource with an url <url-pattern>/QuoteService</url-pattern> and all secured http methods (<http-method>). In most cases you will protect the resource for all existing http methods. Under <auth-constraint> you will define the roles which have access to this resource. And with the tag <transport-guarantee> you are able to define, that the request has to be made over SSL (CONFIDENTIAL). Because I was not able to call the web service at all when setting to CONFIDENTIAL, I did choose NONE. Nevertheless a call over SSL is strongly recommended, because otherwise the password is transmitted as clear text.


Here we define the authentication method which may be BASIC (the browser or client handles the login) or FORM (the application has it’s own login form). Because in out example we want to secure a web service, we choose BASIC.


In this section we just define that the application needs a logical role “Authenticated”.

If you prefer the graphical way with the Web Deyploment Descriptor Editor you should select the security tab and get something like that:


3. Define user and role mapping

We already did define a role “Authenticated” in your web application. But this is only a logical role inside your application which we have to map to a real world role. There are two ways to achieve this:

  • Define mapping in your application with application.xml and ibm-application-bnd.xml
  • Define mapping in WebSphere with admin console

The first case is fine, if you have the same user realm in all environments where you deploy your application or at least the same user and group names. You do not need admin access to WebSphere, which may be an advantage in large enterprises.

The second case needs admin access to WebSphere admin console, but the mapping can be defined for each environment separately. This is convenient if you have different user and group names in each enviroment.

3a. Define user and role mapping with application.xml and ibm-application-bnd.xml

The two files application.xml and ibm-application-bnd.xml can be found both in the META-INF directory of the EAR, which contains your WAR file.

<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="" xmlns:xsi="" xsi:schemaLocation="" version="5">
<?xml version="1.0" encoding="UTF-8"?>
  xsi:schemaLocation="" version="1.0">
  <security-role name="Authenticated">
    <special-subject type="ALL_AUTHENTICATED_USERS" />

While in the application.xml you just repeat that there is a logical role “Authenticated” in your application, the important part is done in the ibm-application-bnd.xml. In this WebSphere specific file you define that the logical role “Authenticated” contains all authenticated users, which are able to logon to your WebSphere server. Here you are also able to define concrete users or map a physical role to a logical role. Here another example:

<security-role name="LogicalRole1">
  <user name="AppUser1" />
  <group name="PhysicalGroup1" />

Here the application role “LogicalRole1″ is mapped to the concrete user “AppUser1″ and all users from the group “PhysicalGroup1″. Note that we also talk about roles (the logical application roles) and group (physical groups from your user realm).

If you prefer the graphical way to edit application.xml and ibm-application-bnd.xml open the application.xml with the Application Bindings Editor and you should get somethine like that:


3b. Define user and role mapping with WebSphere admin console

You have to choose “Applications”/”Application Types”/”WebSphere enterprise applications” and select your application from the table. Now choose “Security role to user/group mapping”:


On the next page you can define the mapping as you already know it from before:


Attention: You only will get the OK button, if you have configured your server with the option “Run server with resources on Server” (Doubleclick on your server in the servers view in your workspace and look under “Publishing settings for WebSphere Application Server”). That means that the mapping is done in this case in the WebSphere server and not your application.

Because normally the WebSphere server in enterprises are not managed by the developers, I always would recommend the first way with editing the ibm-application-bnd.xml in your applications workspace. Then you have to ensure that in all environments where you deploy your application, the same user and roles have to be defined.

4. Add application user to user repository

In the last step you should define now at least one user in your file based user repository for testing. Select “Users and Groups”/”Manager Users” in the Admin Console:

Manage Users in Admin Console
Manage Users in Admin Console

Choose “Create” and enter a new application user for example “appuser”:


Hint: You will also be able to access your application with the admin user from the admin console.

5. Make a test call

If you now enter the url of your applications web service (for example http://localhost:9080/yourapp/quoteservice/) in the browser you should be prompted for user/password.


Note that the browser warns you, that you did not use https. Usage of https is strongly recommended!