Skip navigation.
Downloads | Product Documentation | Support

Developing Security Providers for WebLogic Server

# Principal Validation Providers

Authentication providers rely on Principal Validation providers to sign and verify the authenticity of principals (users and groups) contained within a subject. Such verification provides an additional level of trust and may reduce the likelihood of malicious principal tampering. Verification of the subject's principals takes place during the WebLogic Server's demarshalling of RMI client requests for each invocation. The authenticity of the subject's principals is also verified when making authorization decisions.

The following sections describe Principal Validation provider concepts and functionality, and provide step-by-step instructions for developing a custom Principal Validation provider:

- Principal Validation Concepts
- The Principal Validation Process
- Do You Need to Develop a Custom Principal Validation Provider?
- How to Develop a Custom Principal Validation Provider

# Principal Validation Concepts

Before you develop a Principal Validation provider, you need to understand the following concepts:

- Principal Validation and Principal Types
- How Principal Validation Providers Differ From Other Types of Security Providers
- Security Exceptions Resulting from Invalid Principals

## Principal Validation and Principal Types

Like Identity Assertion providers support specific types of tokens, Principal Validation providers support specific types of principals. For example, the WebLogic Principal Validation provider (described in Do You Need to Develop a Custom Principal Validation Provider?) signs and verifies the authenticity of WebLogic Server principals.

The Principal Validation provider that is associated with the configured Authentication provider (as described in How Principal Validation Providers Differ From Other Types of Security Providers) will sign and verify all the principals stored in the subject that are of the type the Principal Validation provider is designed to support.

## How Principal Validation Providers Differ From Other Types of Security Providers

A Principal Validation provider is a special type of security provider that primarily acts as a "helper" to an Authentication provider. The main function of a Principal Validation provider is to prevent malicious individuals from tampering with the principals stored in a subject.

The `AuthenticationProvider` SSPI (as described in Implement the AuthenticationProvider SSPI) includes a method called `getPrincipalValidator`. In this method, you specify the Principal Validation provider's runtime class to be used with the Authentication provider. The Principal Validation provider's runtime class can be the one BEA provides (called the WebLogic Principal Validation provider) or one you develop (called a custom Principal Validation provider). An example of using the WebLogic Principal Validation provider in an Authentication provider's `getPrincipalValidator` method is shown in Listing 3-1.

Because you generate MBean types for Authentication providers and configure Authentication providers using the WebLogic Server Administration Console, you do not have to perform these steps for a Principal Validation provider.

## Security Exceptions Resulting from Invalid Principals

When the WebLogic Security Framework attempts an authentication (or authorization) operation, it checks the subject's principals to see if they are valid. If a principal is not valid, the WebLogic Security Framework throws a security exception with text indicating that the subject is invalid. A subject may be invalid because:

- A principal in the subject does not have a corresponding Principal Validation provider configured (which means there is no way for the WebLogic Security Framework to validate the subject).

Note: Because you can have multiple principals in a subject, each stored by the LoginModule of a different Authentication provider, the principals can have different Principal Validation providers.

- A principal was signed in another WebLogic Server security domain (with a different credential from this security domain) and the caller is trying to use it in the current domain.
- A principal with an invalid signature was created as part of an attempt to compromise security.
- A subject never had its principals signed.

# The Principal Validation Process

As shown in Figure 5-1, a user attempts to log into a system using a username/password combination. WebLogic Server establishes trust by calling the configured Authentication provider's LoginModule, which validates the user's username and password and returns a subject that is populated with principals per Java Authentication and Authorization Service (JAAS) requirements.

Figure 5-1 The Principal Validation Process

WebLogic Server passes the subject to the specified Principal Validation provider, which signs the principals and then returns them to the client application via WebLogic Server. Whenever the principals stored within the subject are required for other security operations, the same Principal Validation provider will verify that the principals stored within the subject have not been modified since they were signed.

# Do You Need to Develop a Custom Principal Validation Provider?

The default (that is, active) security realm for WebLogic Server includes a WebLogic Principal Validation provider. Much like an Identity Assertion provider supports a specific type of token, a Principal Validation provider signs and verifies the authenticity of a specific type of principal. The WebLogic Principal Validation provider signs and verifies WebLogic Server principals. In other words, it signs and verifies principals that represent WebLogic Server users or WebLogic Server groups.

Notes: You can use the `WLSPrincipals` class (located in the `weblogic.security` package) to determine whether a principal (user or group) has special meaning to WebLogic Server. (That is, whether it is a predefined WebLogic Server user or WebLogic Server group.) Furthermore, any principal that is going to represent a WebLogic Server user or group needs to implement the `WLSUser` and `WLSGroup` interfaces (available in the `weblogic.security.spi` package).

`WLSPrincipals` is used only by `PrincipalValidatorImpl`, not by the Security Framework. An Authentication provider can implement its own principal validator, or it can use the `PrincipalValidatorImpl`. If you configure an Authentication provider with custom principal validators, then the `WLSPrincipals` interface is not used.

An Authentication provider needs to implement the `WLSPrincipals` interface if the provider is going to use `PrincipalValidatorImpl`.

The WebLogic Principal Validation provider includes implementations of the `WLSUser` and `WLSGroup` interfaces, named `WLSUserImpl` and `WLSGroupImpl`. These are located in the `weblogic.security.principal` package. It also includes an implementation of the `PrincipalValidator` SSPI called `PrincipalValidatorImpl` (located in the `weblogic.security.provider` package). The `sign()` method in the `PrincipalValidatorImpl` class generates a random seed and computes a digest based on that random seed. (For more information about the `PrincipalValidator` SSPI, see Implement the PrincipalValidator SSPI.)

## How to Use the WebLogic Principal Validation Provider

If you have simple user and group principals (that is, they only have a name), and you want to use the WebLogic Principal Validation provider:

- Use the `weblogic.security.principal.WLSUserImpl` and `weblogic.security.principal.WLSGroupImpl` classes.
- Use the `weblogic.security.provider.PrincipalValidatorImpl` class.

If you have user or group principals with extra data members (that is, in addition to a name), and you want to use the WebLogic Principal Validation provider:

- Write your own `UserImpl` and `GroupImpl` classes.
- Extend the `weblogic.security.principal.WLSAbstractPrincipal` class.
- Implement the `weblogic.security.spi.WLSUser` and `weblogic.security.spi.WLSGroup` interfaces.
- Implement the `equals()` method to include your extra data members. Your implementation should call the `super.equals()` method when complete so the `WLSAbstractPrincipal` can validate the remaining data.

Note: By default, only the user or group name will be validated. If you want to validate your extra data members as well, then implement the `getSignedData()` method.

- Use the `weblogic.security.provider.PrincipalValidatorImpl` class.

If you have your own validation scheme and do not want to use the WebLogic Principal Validation provider, or if you want to provide validation for principals other than WebLogic Server principals, then you need to develop a custom Principal Validation provider.

# How to Develop a Custom Principal Validation Provider

To develop a custom Principal Validation provider:

- Write your own `UserImpl` and `GroupImpl` classes by:

- Implementing the `weblogic.security.spi.WLSUser` and `weblogic.security.spi.WLSGroup` interfaces.
- Implementing the `java.io.Serializable` interfaces.

- Write your own `PrincipalValidationImpl` class by implementing the `weblogic.security.spi.PrincipalValidator` SSPI. (See Implement the PrincipalValidator SSPI.)

## Implement the PrincipalValidator SSPI

To implement the `PrincipalValidator` SSPI, provide implementations for the following methods:

  validate

  `public boolean validate(Principal principal) throws SecurityException;`

  The `validate` method takes a principal as an argument and attempts to validate it. In other words, this method verifies that the principal was not altered since it was signed.

  sign

  `public boolean sign(Principal principal);`

  The `sign` method takes a principal as an argument and signs it to assure trust. This allows the principal to later be verified using the `validate` method.

  Your implementation of the `sign` method should be a secret algorithm that malicious individuals cannot easily recreate. You can include that algorithm within the `sign` method itself, have the `sign` method call out to a server for a token it should use to sign the principal, or implement some other way of signing the principal.

  getPrincipalBaseClass

  `public Class getPrincipalBaseClass();`

  The `getPrincipalBaseClass` method returns the base class of principals that this Principal Validation provider knows how to validate and sign.

For more information about the `PrincipalValidator` SSPI and the methods described above, see the WebLogic Server 8.1 API Reference Javadoc.