Form Authentication

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

Form authentication is similar to basic authentication: both require a candidate user to provide a valid username and password and both require that the candidate user be a member of an appropriate role before they can access a protect web resource. The major difference is that form authentication, unlike basic authentication, allows you to present a customized HTML login page to candidate users. In basic authentication, the login page is provided by the browser and cannot be customized according to your preferred look and feel.

Form authentication involves a two part challenge to candidate users. (1) It 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 form authentication, first the user is redirected to a login page 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. In the second challenge, WebLogic Server checks to see if the user has been granted the required role. 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 the required role, then he is granted access to the resource.

Note: you should not use form authentication (or basic authentication) to secure individual JSP pages or action methods within a page flow directory. After collecting a username and password, form 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 form authentication, you must complete the following steps:

Specify the web resources to be protected
Specify the roles that can access the web resource
Specify form authentication as the method of protection
Declare the security roles referenced in step 2
Assign security roles to principals (groups and individual users)
Provide login and failover pages

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 Form 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>FORM</auth-method>
        <realm-name>default</realm-name>
        <form-login-config>
            <form-login-page>/security/login/login.jsp</form-login-page>
            <form-error-page>/security/login/fail_login.jsp</form-error-page>
        </form-login-config>
    </login-config>

The value FORM specifies that the developer has supplied the login page shown to the user. The path to the login page is specified in the <form-login-page> element. The login page you provide can be an HTML or JSP file. In the <form-error-page> element, you can supply a failover page, should the user fail the username/password challenge. See step 6 below for specific requirements on these pages.

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>

6. Provide Login and Failover Pages

The custom login page must meet three requirements:

it must contain an HTML <form> with the attribute action="j_security_check"
it must contain an HTML <input> with the attribute name="j_username"
it must contain an HTML <input> with the attribute action="j_password"

You can use the following HTML <form> as a template for your login page.

    <form method="POST" action="j_security_check">  
        Username: <input type="text" name="j_username"><br>
        Password: <input type="password" name="j_password"><br>
        <input type=submit value="Submit">
    </form>

The failover page does not have any special requirements. The failover page is shown to users who fail the username/password challenge. If the user passes the username/password challenge, but fails the role membership challenge, the failover page will not be shown. Error handling in this case must be provided by your web application.