8
Security HTTP Administration

Overview

This chapter contains a series of operations designed to be helpful in setting up the HTTP security for the servlet engine. The topics we cover are the following:

• Prerequisites to Web Server Security

• Authentication and Authorization

• Declaring Principals

• The Tools

• Protecting A Resource

• Declaring Permissions

• Declaring A Security Servlet

• Trouble Shooting

Prerequisites to Web Server Security

Before you define and program the security settings in the OSE, you must be proficient at setting up and manipulating the JNDI structure. Verify your knowledge against the following checklist:

Single-Domain

Multiple-Domain

HTTP Virtual Path

Mapping Virtual Paths to Servlet Contexts

HTTP Requests

Request Served by Servlet

Request Served by the Default Servlet

Create Service

Create a Context

If you are unsure of any of the above topics, review the diagrams and examples describing how the OSE works with the JNDI namespace and how Web browsers interact with the OSE. A link follows each topic to a specific discussion. A complete example list is located in Appendix B, "Examples".

After you learn the basic security set up in this chapter, you can safely change the configuration of your Web service security from the default set up.

Authentication and Authorization

In HTTP security, access to a protected resource is composed of two parts: authentication of valid credentials and authorization of the user. Authentication is the validation of submitted credentials establishing that a user is known and validated by the system. Authorization is the determination of whether an authorized user is allowed to perform the requested action.

There are four stages to declare when establishing security measures:

1. The principals of a service.

2. Resources as being protected and how they are to be protected.

3. Permissions of principals within the servlet context.

4. A security servlet in the root of the servlet context.

Use these steps to ensure the correct base information is in use defining HTTP security for your Web resources. Without any one of these steps, security will either be non-existent or will deny access to protected resources.

Declaring Principals

A principal is a generic term for either a user or a group. The realm is an object in the service, which contains the declared principals. Figure 8-1 shows the position of the realm object at the top level of the Web service, at the same level as the config object for the service.

Figure 8-1 JNDI Structure Depicting /realms in the Domain Root

Groups

Groups contain other principals (users or other groups). Individual members of a group inherit the permission of the group object.

Users

Users are single objects. Unlike a group, there are no subsets of other principals belonging to a user.

Realms

Each realm defines a separate set of principals. The realm and its implementation are core to all of HTTP Security. There can be multiple realms within a service. The realm is the source of:

• the valid set of principals

• the types of principals that are handed to the server

Because the realm is the source of all principals, it also plays a key role in:

• what types of credentials are to be used to identify principals

• aiding the principals in managing the credentials themselves or it can defer to whatever entity that does have them

• establishing the relationships among all principals within it.
  

By default, there are three implementations of realms, named in HTTP Security:

• JNDI-- stores all information in JNDI entries in the namespace

• DBUSER-- defers to local user definitions within the database itself

• RDBMS-- stores all principals and their relationships in more regular database tables

These names are just shortcuts. When instantiating the realm, use the appropriate name when declaring the realm class in the JNDI namespace.

DBUSER Considerations

The DBUSER realm is a principal definition derived from the users and roles defined within the database. There are several implications.

• No principal management is allowed through any security commands. Principal creation, deletion, and role membership is managed by the database, not security tools.

• Because all instances utilize the same source for principal definition, all instances will essentially be equivalent.

• When referring to principals, no case translations are performed to the form of the name, as presented to the Java system. This means when the database entity was created, unless the case was explicitly expressed, the entire name is uppercase. For example, SYS and PUBLIC are in uppercase, but if a user were created in lower case, such as:

  create user "joe" identified by welcome;
  
  
  

  then the username would be joe, in lowercase.

  Note: The upper case/lower case distinction is important when supplying usernames and passwords from the browser.

The Tools

You set the security levels with the realm command, using the different flags and options. You can see the complete definition of all valid realm uses in the Oracle Java Tools Reference. To see a list of the different choices, execute the realm command from the session shell.

Example 8-1 Executing The Realm Command Listing Valid Security Commands

$ realm
usage:
realm
realm list -d <webServiceRoot>
realm echo [0|1]
realm secure -s <servletContextPath>
realm map -s <servletContextPath> [- add|remove <path>] [-scheme <auth>:<realm>]
realm publish -d <webServiceRoot> [- add|remove <realmName>] [-type RDBMS | DBUSER | JNDI]
realm user -d <webServiceRoot> -realm <realmName> [- add|remove <userName> [-p <user password>]]
realm group -d <webServiceRoot> -realm <realmName> [- add|remove <groupName> [-p <group password>]]
realm parent -d <webServiceRoot> -realm <realmName> [-group <groupName> [- add|remove <principalName>]] 
[-query <principalName>]
realm perm -d <webServiceRoot> -realm <realmName> -s <servletContextPath> -name <principalName> [-path <path> 
(+|-) <permList>]

The Mechanics

Underscoring its central role, realm is the start of all security commands in the shell. The following sections depict example commands creating and managing realms from the shell.

Realms

To create a RDBMS realm, type:

realm publish -w /myService -add testRealm -type RDBMS
For JNDI and DBUSER, use those titles as the type argument.

To remove a realm, type:

realm publish -w /myService -remove testRealm
Realm declarations reside in the JNDI namespace. Deploying customized realms, once written, requires only slight customization of the namespace entry.

To publish a custom realm, type:

realm publish -w /myService -add testRealm -classname foo.bar.MyRealm

Principals

To create a user, type:
realm user -w /myService -realm testRealm1 -add user1 -p upswd1

To create a group, type:
realm group -w /myService -realm testRealm1 -add group1 -p gpswd1

In either of the above commands, if the password is left blank, the principal name is used instead.

To delete a user, type:
realm user -w /myService -realm testRealm1 -remove user1

To delete a group, type:
realm group -w /myService -realm testRealm1 -remove group1

To list users of a realm, type:
realm user -w /myService -realm testRealm1

To list groups of a realm, type:
realm group -w /myService -realm testRealm1

To add a principal to a group, type:
realm parent -w /myService -realm testRealm -group group1 -add user1

To remove a principal from a group, type:
realm parent -w /myService -realm testRealm -group group1 -remove user1

To list principals within a group, type:
realm parent -w /myService -realm testRealm -group group1

To query which groups a principal is a member of, type:
realm parent -w /myService -realm testRealm -q user1
(All realms do not support this query option.)

Details

If a service has any realms declared, they are located in a realms sub-context of the service. If it is a JNDI realm, there is additional sub-contexts within the realms context that contain its principal declarations.

If /realms is removed, all realm definitions are removed along with it. However any external resources (such as table entries) would remain. Using the session shell realm tool is much safer for efficient realm management.

Removing subcontexts of realms can affect any JNDI type realms. The RDBMS realm is defined to use the following tables:

• JAVA$HTTP$REALM$PRINCIPAL$-- contains all principals and an encoded form of their password

• JAVA$HTTP$REALM$GROUP$-- contains principal/group relationships

Protecting A Resource

OSE HTTP security resource protection is local to the servlet context. To declare a resource protected, two pieces of information must be supplied, embodied in a protection scheme. A scheme is of the form:

<authType>:<realmName>

There are two valid authentication types:

• Basic-- typical base64 encoding, not very secure.

• Digest-- both parties keep the password to themselves and pass highly encrypted codes. The codes are embedded with many situation-specific values, such as time stamp, URL being requested, a secret key, and IP of the requester.

Although Digest is far more secure than Basic, not all browsers support it. From looking at typical installations, IE5 supports it; Netscape 4.7 does not.

You can also declare resources not to be protected. This is useful when the servlet context root is to be protected. However, when the root is protected, the error pages, being part of the tree, are also protected. Delivering an error page is part of the authentication process. If the error page is protected, cycles develop, and the desired behavior is not observed.

Instead of letting the error page default as part of the tree, explicitly declare the error pages as not being protected. Use a protection scheme of <NONE>. For example:

realm map -s /myService/contexts/myContext -a /system/* -scheme <NONE>

realm map -s /myService/myService/contexts/myContext -a /* -scheme 
basic:testRealm1

The Mechanics

The protected path is local to the servlet context. Internally, that path is normalized, enabling stable, predictable patterns for matching. This may cause the internal representation to differ from the original path used to create the protection scheme. HTTP Security will use the longest, most exact match possible when trying to apply the protection rules.

Protecting paths to resources with protection schemes:

realm map -s /myService/contexts/myContext -a /doc/index.html -scheme 
basic:testRealm1 

realm map -s /myService/contexts/myContext -a /doc -scheme basic:testRealm2 

realm map -s /myService/contexts/myContext -a /doc/* -scheme basic:testRealm3

When declarations are made, as shown in the previous example, the paths are matched to realms as in the following examples:

/doc/index.html -> testRealm1 

/doc/foo -> testRealm3 

/doc -> testRealm2 

/doc/ -> testRealm2 

/doc/index -> testRealm3

To remove the protection of a path, type:
realm map -s /myService/contexts/myContext -r /doc/index.html

To list all protected paths within a servlet context, type:
realm map -s /myService/contexts/myContext

To explicitly declare a path not to be protected, type:
realm map -s /myService/contexts/myContext -a /system/* -scheme <NONE>

To list all protected paths within a servlet context, type:
realm map -s /myService/contexts/myContext

More Details

The JNDI entry for protection mappings is located in a subdirectory, policy, of the servlet context. Within that sub-context is an entry, httpMapping, which creates the object responsible for handling the security servlet protection mapping. By default, this object is used as an index into the JAVA$HTTP$REALM$MAPPING$ table. The HTTP realm mapping table contains all the mapped paths. Simple JNDI entry manipulation can introduce a customized version of HttpProtectionMapping.

Declaring Permissions

Permissions are the most involved of all HTTP Security declarations because they tie domain-scoped entities with servlet context-scoped entities and reside in the servlet context themselves.

A permission declaration consists of several pieces:

1. service

2. realm within specified service

3. servlet context within specified service

4. principal within specified realm

5. path to which the permission is to apply

6. whether the permission is being granted or denied

7. HTTP actions being assigned

Given all the pieces that are being tied into one permission declaration, it is easy to see why these are the most complicated declarations.

Of those pieces, only the HTTP actions have not been talked about yet. HTTP security permissions concern only valid HTTP request methods: GET, POST, PUT, DELETE, HEAD, TRACE, OPTIONS.

The Mechanics

To declare a granted permission on /foo/index.html for user1 for GET and POST, type:
realm perm -w /myService -realm testRealm1 -s /myService/contexts/myContext -n user1 -u /foo/index.html + get,post

To declare a denied permission on /foo/* for user1 for PUT and DELETE, type:
realm perm -w /myService -realm testRealm1 -s /myService/contexts/myContext -n user1 -u /foo/* - put,delete

To clear granted permissions on /foo/index.html for user1, type:
realm perm -w /myService -realm testRealm1 -s /myService/contexts/myContext -n user1 -u /foo/index.html +

To list all permissions for a user, type:
realm perm -w /myService -realm testRealm1 -s /myService/contexts/myContext -n user1

More Details

In the policy subcontext of a servlet context, there will be an entry, config. This is the entry used to create the object responsible for all permission declaration checks. Again, the object is used as a key into the permissions table, JAVA$HTTP$REALM$POLICY$

Declaring A Security Servlet

All HTTP Security is declared through JNDI namespace entries. This is also true for the servlet that does the enforcing of security. In the servlet context, if there is a PrivilegedServlet named httpSecurity, that servlet is added as the first pre-filter for all requests within that servlet context.

Any customization is allowed as long as the PrivilegedServlet interface is implemented.The main responsibility of this servlet is to either:

• raise an AccessControlException during its service(HttpRequest.PrivilegedAccess, HttpRequest, HttpResponse) if there is a perceived security violation

  or

• not raise an exception if the request is to be allowed

After authentication and authorization have taken place, the servlet must set specific authenticated principal values on the request itself. This is the user information that can be retrieved from the request by any executing servlet.

The Mechanics

To create a security servlet, type:
realm secure -s /myService/contexts/myContext

Removing the security servlet removes all security enforcement in a servlet context. If the entry is missing, the webserver continues execution with no security enforcement.
To remove a security servlet, type:
rm /myDomain/contexts/myContext/httpSecurity

Note: The servlet is not published in named_servlets but within the servlet context directory itself.

Trouble Shooting

There are several layers of suspected problems to eliminate when debugging HTTP Security. This minimal checklist can help you start your trouble shooting quest.

Check spelling (for instance, realm names, user names, or URI specifications).

If using a DBUSER realm, check the case considerations.

Set your browser cache to check for newer versions of pages every time.

Clear browser cache(s).

After setting a Web server sessions property, make sure you are testing against a new Web server session. The information may not be propagated to current active sessions. This can be done by closing all running browsers and starting a new browser.

Be sure that all four stages of security declarations are in place. If any are missing or incorrect, the results are unpredictable.

Be sure that the type of authentication specified is supported by your browser. For example, by default, Netscape 4.7 does not support Digest authentication. Netscape will treat it as just Basic authentication (raising a dialog box). However, the Basic authentication response does not work for Digest authentication. This is misleading when the expected Netscape prompt displays, as it actually appeared for the wrong reasons.

Use the shell to query the entities involved. Check that the information is declared in a way that defines your security goals.
For example, if /doc/index.html is to only be accessible to user1 in myRealm using Basic authentication then there has to be the following:

1. a realm named myRealm is within the domain

2. the realm has to contain a user named, user1, with a known password

3. a mapping of /doc/index.html or some more general path to a protection scheme basic:myRealm within the servlet context

4. a security servlet declared for the servlet context

5. a permission granting GET rights to the user user1 for/doc/index.html (or a more general path)

---