# Basic Authentication

The following topic explains how to secure a web resource using basic authentication.

Basic authentication involves a two part challenge to candidate users. (1) Basic authentication requires users to provide a valid username/password pair before they can access a web resource. (2) It also requires that users have been granted the appropriate role membership before they can access the resource. The web resource can be any web-accessible component, such as a web application, web service, or an individual JSP page.

When a user requests a web resource protected by basic authentication, first the user is redirected to a login window where he enters his username and password. If he fails to provide a valid username and password, then he is denied access to the resource. If he provides a valid username/password pair, he graduates to the second (role-based) challenge. If the user has not been granted the required role, then he is denied access to the resource (even if he provides a valid username and password). If he has been granted to required role, then he is granted access to the resource.

In basic authentication, the browser provides the login window and it cannot be customized. If you require a customizable login page use Form Authentication.

Note: you should not use basic authentication (or form authentication) to secure individual JSP pages or action methods within a page flow directory. After collecting a username and password, basic authentication redirects the user to the requested resource. But redirection into a page flow directory always fails, because the page flow's begin() action method is always invoked when a new user enters the page flow. However, it is appropriate to secure an entire page flow directory using basic or form authentication.

To secure a web resource using basic authentication, you must complete the following steps:

1. Specify the web resources to be protected
2. Specify the roles that can access the web resource
3. Specify basic authentication as the method of protection
4. Declare the security roles referenced in step 2
5. Assign security roles to principals (groups and individual users)

## 1. Specify the Web Resources to be Protected

You define a web resource, such as a web application or web service, as a protected resource by placing a security constraint on that resource. Security constraints are specified by <security-constraint> XML elements in the web.xml configuration file in the WEB-INF directory.

In the example below, the JSP page Administrators.jsp is defined as a protected web resource.

web.xml

        <security-constraint>
            <web-resource-collection>
                <web-resource-name>Administrator's Page</web-resource-name>
                <url-pattern>/myProtectedWebResources/Administrators.jsp</url-pattern>
                <http-method>GET</http-method>
                <http-method>POST</http-method>
            </web-resource-collection>
        </security-constraint>

### The <url-pattern> Element

The child element <url-pattern> element defines which URLs in your web resources should be protected by a username/password challenge. If a user tries to access a protected URL, he is redirected to the login screen where he must enter a valid username/password pair before he can access the resource.

Using the <url-pattern> element you can restrict access to an entire web application, a folder or a particular file within the web application.

The following <url-pattern> element declares the entire project as protected.

<url-pattern>/*</url-pattern>

The following <url-pattern> element declares the /myProtectedWebResources folder as protected.

<url-pattern>/myProtectedWebResources*</url-pattern>

The following <url-pattern> element declares that the web service /myProtectedWebResources/Administrators.jsp should be protected.

<url-pattern>/myProtectedWebResources/Administrators.jsp</url-pattern>

You can place multiple <url-pattern> elements within a single security constraint.

        <security-constraint>
            <web-resource-collection>
                <web-resource-name>Administrator's Pages</web-resource-name>
                <url-pattern>/myProtectedWebResources/Administrators.jsp</url-pattern>
                <url-pattern>/myProtectedWebResources/Payroll.jsp</url-pattern>
                <http-method>GET</http-method>
                <http-method>POST</http-method>
            </web-resource-collection>
        </security-constraint>

### The <http-method> Element

The <http-method> element declares which HTTP methods (usually, GET or POST) are subject to the security constraint. If <http-method> element is omitted, the the security constraint is applied to all HTTP methods by default.

## 2. Specify the Roles that Can Access the Resource

It is common to use basic authentication in conjunction with role-based security. Once a user passes the username/password challenge, he can be mapped to one or more roles, allowing the developer a finer-grained control over access to web resources.

When specify basic authentication you must also set up a role-based constraint on the web resource. The authorization constraint allows access only to those user that have been granted a specific role. In the following example, the <auth-constraint> element specifies that users must be granted the Administrator role to access the resource.

web.xml

        <security-constraint>
            <web-resource-collection>
                <web-resource-name>Administrator's Page</web-resource-name>
                <url-pattern>/myProtectedWebResources/Administrators.jsp</url-pattern>
                <http-method>GET</http-method>
                <http-method>POST</http-method>
            </web-resource-collection>
            <auth-constraint>
                <role-name>Administrator</role-name>
            </auth-constraint>
        </security-constraint>

### The <auth-constraint> Element

An <auth-constraint> child element (short for "authorization" constraint) specifies that a user must be a member of a certain role to access the web resource.

The role membership challenge can be heavy or light depending on your security needs. In some cases, requiring login is not intended to restrict access to web resources, but merely for the purpose of tracking individual users' behavior in the web application. In these cases, use a lightweight authorization challenge by requiring that users be members of the Users role. Provided that you assign the Users role to all visitors (see step 5 below), all visitors will be able to access the resource.

        <security-constraint>
            <web-resource-collection>
                <web-resource-name>Administrator's Page</web-resource-name>
                <url-pattern>/myProtectedWebResources/Administrators.jsp</url-pattern>
                <http-method>GET</http-method>
                <http-method>POST</http-method>
            </web-resource-collection>
            <auth-constraint>
                <role-name>Users</role-name>
            </auth-constraint>
        </security-constraint>

## 3. Specify Basic Authentication as the Method of Protection

To specify basic authentication at the method of protection, add a <login-config> element to the web.xml file. The <login-config> element should appear directly underneath the <security-constraint> element.

web.xml

        <security-constraint>
            <web-resource-collection>
                <web-resource-name>Administrator's Page</web-resource-name>
                <url-pattern>/myProtectedWebResources/Administrators.jsp</url-pattern>
                <http-method>GET</http-method>
                <http-method>POST</http-method>
            </web-resource-collection>
            <auth-constraint>
                <role-name>Administrator</role-name>
            </auth-constraint>
        </security-constraint>

        <login-config>
            <auth-method>BASIC</auth-method>
            <realm-name>default</realm-name>
        </login-config>

The value BASIC specifies that the browser should supply the login page shown to the user. If you with to provide a custom login page, use value FORM. For details on supplying custom login pages, see Form Authentication.

## 4. Declare Security Roles

The roles that you referenced in step 2 must also be declared in the web.xml file. Roles are declared using a <security-role> element.

web.xml

        <security-constraint>
            <web-resource-collection>
                <web-resource-name>Administrator's Page</web-resource-name>
                <url-pattern>/myProtectedWebResources/Administrators.jsp</url-pattern>
                <http-method>GET</http-method>
                <http-method>POST</http-method>
            </web-resource-collection>
            <auth-constraint>
                <role-name>Administrator</role-name>
            </auth-constraint>
        </security-constraint>

        <login-config>
            <auth-method>BASIC</auth-method>
            <realm-name>default</realm-name>
        </login-config>

        <security-role>
            <role-name>Administrator</role-name>
        </security-role>

## 5. Assign Security Roles to Principals (Groups and Individual Users)

Finally, you must assign role membership to the groups and individuals users you want to grant access to. In the weblogic.xml file add a <security-role-assignment> element for each role to principal mapping. In the following example the group administrators_group is granted the Administrator role.

weblogic.xml

        <security-role-assignment>
            <role-name>Administrator</role-name>
            <principal-name>administators_group</principal-name>
        </security-role-assignment>

If you desire a lightweight authorization challenge, you can map the Users role to the users group. The users group is a pre-defined group in WebLogic Sever: everyone that successfully logs on is automatically a member of the user group.

<login-config>

As an alternative to using the <auth-constraint> element you can use the <login-config> element to require a username and password from users.

Note that if you use the <login-config> element, basic authentication is applied universally to all of the web resources protected by <security-constraint> elements within the web.xml file.

        <security-constraint>
            <display-name>
                Security Constraint for HelloWorldSecure.jws
            </display-name>
    		<web-resource-collection>
                <web-resource-name>BasicAuthentication.jws</web-resource-name>
                <description>A web service secured by SLL and basic authentication</description>
                <!--
                Defines the scope of the web resource to be secured with SSL.
                Secure all methods calls to the HelloWorldSecure web service.
                -->
                <url-pattern>/security/transport/helloWorldSecure/HelloWorldSecure.jws/*</url-pattern>
                <http-method>GET</http-method>
                <http-method>POST</http-method>
    		</web-resource-collection>
        </security-constraint>

    	<login-config>
    		<auth-method>BASIC</auth-method>
    	</login-config>

Related Topics

For more information about setting up an authentication procedure see Developing Secure Web Applications in the WebLogic Server 8.1 documentation.

For reference information on the web.xml file see web.xml Deployment Descriptor Elements in the WebLogic Server 8.1 documentation. See especially the documentation for the <security-constraint> element, the <login-config> element, and the <user-data-constraint> element.

WebLogic Workshop Documentation

Role-Based Security

Authorization

WebLogic Server 8.1 Documentation

Developing BASIC Authentication Web Applications

web.xml Deployment Descriptor Elements

<security-constraint>

<login-config>

<user-data-constraint>