Skip navigation.
Downloads | Product Documentation | Support

Developing Security Providers

# Security Provider Concepts

To develop custom security providers, you need to know and understand the security concepts that relate to the type of security providers you are developing. This section describes the concepts of each type of security provider.

- Authentication Concepts
- Identity Assertion Concepts
- Principal Validation Concepts
- Authorization Concepts
- Role Mapping Concepts
- Auditing Concepts
- Credential Mapping Concepts

# Authentication Concepts

Before delving into the specifics of developing custom Authentication providers, it is important to understand the following concepts:

- Users and Groups, Principals and Subjects
- Java Authentication and Authorization Service (JAAS)

## Users and Groups, Principals and Subjects

A user typically represents a person. A group is a category of users, classified by common traits such as job title. Categorizing users into groups makes it easier to control the access permissions for large numbers of users. Both users and groups can be used as principals. A principal is an identity assigned to a user or group as a result of authentication. The Java Authentication and Authorization Service (JAAS) requires that subjects be used as containers for authentication information, including principals. Each principal stored in the same subject represents a separate aspect of the same user's identity, much like cards in a person's wallet. (For example, an ATM card identifies someone to their bank, while a membership card identifies them to a professional organization to which they belong.) For more information about JAAS, see Java Authentication and Authorization Service (JAAS). For additional information on the relationship of users and groups and the authorization service, see the Security Services in the Introduction to WebLogic Enterprise Security.

As part of a successful authentication, principals are signed and stored in a subject for future use. A Principal Validation provider signs principals, and an Authentication provider LoginModule actually stores the principals in the subject. Later, when a caller attempts to access a principal stored within a subject, a Principal Validation provider verifies that the principal has not been altered since it was signed, and the principal is returned to the caller (assuming all other security conditions are met).

Note: For more information about Principal Validation providers and LoginModules, see Principal Validation Concepts and Writing a JAAS LoginModule.

Any principal that is going to represent a user or group needs to implement the `WLSUser` and `WLSGroup` interfaces, available in the `weblogic.security.spi` package.

## Java Authentication and Authorization Service (JAAS)

Whether the client is an application, applet, Enterprise JavaBean (EJB), or servlet that requires authentication, the Java Authentication and Authorization Service (JAAS) classes allow you to reliably and securely authenticate to the client. JAAS implements a Java version of the Pluggable Authentication Module (PAM) framework that permits applications to remain independent from underlying authentication technologies. Therefore, the PAM framework allows the use of new or updated authentication technologies without requiring modifications to your application. Authentication providers use JAAS internally for authentication. Therefore, only developers of custom Authentication providers need to be concerned with JAAS implementation.

This section covers the following topics:

- Writing a JAAS LoginModule
- LoginModule Interface
- JAAS Control Flags
- CallbackHandlers

### Writing a JAAS LoginModule

Each Authentication Provider requires a LoginModule. LoginModules are responsible for authenticating users within the policy domain and for populating a subject with the necessary principals (users and groups). LoginModules that are not used for perimeter authentication also verify the proof material submitted (for example, a password).

If there are multiple Authentication Providers configured within a policy domain, each one requires a LoginModule to store principals within the same subject. Therefore, if a principal that represents a user named Joe is added to the subject by one Authentication Provider LoginModule, any other Authentication Provider in the policy domain should be referring to the same person when they encounter Joe. In other words, the other Authentication Provider LoginModule should not attempt to add another principal to the subject that represents a user (for example, named Joseph) to refer to the same person. However, it is acceptable for another Authentication Provider LoginModule to add a principal of a type other than the name Joseph.

### LoginModule Interface

You can write LoginModules that handle a variety of authentication mechanisms, including username and password combinations, smart cards, and biometric devices. You develop LoginModules by implementing the `javax.security.auth.spi.LoginModule` interface, that is based on the Java Authentication and Authorization Service (JAAS) and uses a subject as a container for authentication information. The LoginModule interface enables you to plug in different kinds of authentication technologies for use with a single application and the security framework supports multiple LoginModule implementations for multi-part authentication.

You can also have dependencies across LoginModule instances or share credentials across those instances. However, the relationship between LoginModules and Authentication providers is one-to-one. In other words, to have a LoginModule that handles a retina scan authentication and a LoginModule that interfaces to a hardware device like a smart card, you must develop and configure two Authentication providers, each of which includes an implementation of the LoginModule interface. For more information, see Implementing the JAAS LoginModule Interface.

Note: You can also obtain LoginModules from third-party security vendors instead of developing your own.

### JAAS Control Flags

If a policy domain has multiple Authentication Providers configured, the Control Flag attribute on the Authenticator Provider determines the order of execution. Generally, you configure the control flow of multiple Authentication providers using the Administration Console. For more information on specifying the order or authentication providers, see JAAS Control Flags. Setting each LoginModule control flag specifies how to handle a failure during the authentication process. The values for the Control Flag attribute are:

- REQUIRED—This LoginModule must succeed. Even if it fails, authentication proceeds down the list of LoginModules for the configured Authentication Providers. This setting is the default.
- REQUISITE—This LoginModule must succeed. If other Authentication Providers are configured and this LoginModule succeeds, authentication proceeds down the list of LoginModules. Otherwise, return control to the application.
- SUFFICIENT—This LoginModule needs not succeed. If it does succeed, return control to the application. If it fails and other Authentication Providers are configured, authentication proceeds down the LoginModule list.
- OPTIONAL—The user is allowed to pass or fail the authentication test of this Authentication Providers. However, if all Authentication Providers configured in a policy domain have the Control Flag set to OPTIONAL, the user must pass the authentication test of one of the configured providers.

Figure 2-1 illustrates a sample flow involving three different LoginModules that are part of three Authentication providers, and illustrates what happens to the subject for different authentication outcomes.

Figure 2-1 Sample LoginModule Flow

If you set the control flag for Custom Authentication Provider #1 to Required, the authentication failure in the User Authentication step causes the entire authentication process to fail. Also, if the user was not authenticated by the WebLogic Authentication provider (or custom Authentication provider #2), the entire authentication process fails. If the authentication process had failed in any of these ways, all three LoginModules would have been rolled back and the subject would not contain any principals.

Note: For more information about the LoginModule control flag setting and the LoginModule interface, see the Java Authentication and Authorization Service (JAAS) 1.0 LoginModule Developer's Guide and the Java 2 Enterprise Edition, v1.4.2 API Specification Javadoc for the LoginModule interface, respectively.

### CallbackHandlers

A `CallbackHandler` is a highly-flexible JAAS standard that allows a variable number of arguments to be passed as complex objects to a method. An application implements a `CallbackHandler` and passes it to underlying security services so that they may interact with the application to retrieve specific authentication data, such as usernames and passwords, or to display certain information, such as error and warning messages.

`CallbackHandlers` are implemented in an application-dependent fashion and the application developer must implement one for his application. For example, an HTML form (such as, a login page) could prompt the user for information or display an error message. Another implementation might choose to obtain information from an alternate source without asking the user.

Underlying security services make requests for different types of information by passing individual Callbacks to the `CallbackHandler`. The `CallbackHandler` implementation decides how to retrieve and display information depending on the Callbacks passed to it. For example, if the underlying service needs a username and password to authenticate a user, the service uses a `NameCallback` and `PasswordCallback`. The `CallbackHandler` can then request a username and password serially, or request both from a single pop-up window.

### How JAAS Works

Authentication using the JAAS classes and the security framework is performed in the following manner:

1. The client application creates a callback handler containing a callback that allows a provider to request authentication information from the application.
2. The client application passes the callback handler through the authentication service of the Java API into the security framework.
3. The security framework presents the callback handler to the LoginModule for the appropriate authentication provider.
4. The LoginModule uses the callback handler to request specific authentication information (e.g., username or password).
5. The client application is responsible for collecting the appropriate information to respond to the authentication callback. For example, this may include prompting for a username or password.
6. After the LoginModule collects all of the information required, it does one of the following:

Authentication success, returns a valid subject:

- Principals (users and groups) are signed by a Principal Validation provider to ensure their authenticity between programmatic server invocations. For more information about Principal Validation providers, see Principal Validation Concepts.
- The LoginModule associates the signed principals with a subject representing the user or system process being authenticated. For more information about subjects and principals, see Users and Groups, Principals and Subjects.

Authentication failure, throws a exception (`LoginException`)

Note: For more information about LoginModules, see Java Authentication and Authorization Service (JAAS).

# Identity Assertion Concepts

Before you develop an Identity Assertion provider, you need to understand the following concepts:

- Identity Assertion Providers and LoginModules
- Identity Assertion and Tokens
- Passing Tokens for Perimeter Authentication

## Identity Assertion Providers and LoginModules

When used with a LoginModule, Identity Assertion providers support single sign-on. For example, an Identity Assertion provider can generate a token from a digital certificate and that token can be passed around the system so that users are not asked to sign on more than once.

The LoginModule that an Identity Assertion provider uses can be:

- Part of a custom Authentication provider you develop.
- Part of the Authentication provider BEA developed and supplied with WebLogic Enterprise Security product.
- Part of a third-party Authentication provider.

Unlike in a simple authentication situation, the LoginModules that Identity Assertion providers use do not verify proof material such as usernames and passwords; they simply verify that the user exists.

Note: For more information about LoginModules, see Writing a JAAS LoginModule.

## Identity Assertion and Tokens

You develop Identity Assertion providers to support the specific types of tokens that you want to use to assert the identities of users or system processes. You can develop an Identity Assertion provider to support multiple token types, but you can configure the Identity Assertion provider so that it validates only one "active" token type. While you can have multiple Identity Assertion providers in a security service module with the ability to validate the same token type, only one Identity Assertion provider can actually perform the validation.

Note: Supporting token types means that the Identity Assertion provider runtime class (that is, the `IdentityAsserter` SSPI implementation) can validate the token type with its `assertIdentity` method. For more information, see Implementing the AuthenticationProvider SSPI.

The following sections show how to work with new token types:

- How to Create New Token Types
- How to Make New Token Types Available

### How to Create New Token Types

If you develop a custom Identity Assertion provider, you can also create new token types. A token type is simply a piece of data represented as a string. The token types you create and use are completely up to you. As examples, the following token types are currently defined for the X.509 Identity Assertion provider: `X.509`, `CSI.PrincipalName`, `CSI.ITTAnonymous`, `CSI.X509CertChain`, and `CSI.DistinguishedName`.

To create new token types, you create a new Java file and declare any new token types as constant variables of type `String`., as shown in Listing 2-1. The `PerimeterIdentityAsserterTokenTypes.java` file defines the names of the token types `Test 1`, `Test 2`, and `Test 3` as strings.

Listing 2-1 PerimeterIdentityAsserterTokenTypes.java

>     package sample.security.providers.authentication.perimeterATN;

>     public class PerimeterIdentityAsserterTokenTypes
>     {

>        public final static String TEST1_TYPE = "Test 1";
>        public final static String TEST2_TYPE = "Test 2";
>        public final static String TEST3_TYPE = "Test 3";
>     }

### How to Make New Token Types Available

When you configure a custom Identity Assertion provider, the Supported Types field displays a list of the token types that the Identity Assertion provider supports. To configure the provider, use the Administration Console to select the token type that you want to make active.

The content for the Supported Types field is obtained from the `SupportedTypes` attribute of the MBean Definition File (MDF) that you use to generate your custom Identity Assertion provider MBean type. An example from the sample Identity Assertion provider is shown in Listing 2-2.

Listing 2-2 SampleIdentityAsserter MDF: Supported Types Attribute

>     <MBeanType>

>     ...

>        <MBeanAttribute
>         Name = "SupportedTypes"
>         Type = "java.lang.String[]"
>         Writeable = "false"
>         Default = "new String[] {&quot;SamplePerimeterAtnToken&quot;}"
>        />

>     ...

>     </MBeanType>

Similarly, the content for the Active Types field is obtained from the `ActiveTypes` attribute of the MBean Definition File (MDF). You can specify a default `ActiveTypes` attribute in the MDF so that it does not have to be set manually through the Administration Console. An example from the sample Identity Assertion provider is shown in Listing 2-3.

Listing 2-3 Sample Identity Asserter MDF: Active Types Attribute Default Value

>     <MBeanAttribute
>      Name= "ActiveTypes"
>      Type= "java.lang.String[]"
>      Default = "new String[] { &quot;SamplePerimeterAtnToken&quot; }"
>     />

While setting a default value for the `ActiveTypes` attribute is convenient, only do this if you do not use another Identity Assertion provider to validate that token type. Otherwise, you may configure an invalid Security Service Module (where more than one Identity Assertion provider attempts to validate the same token type). Best practice dictates that all MDFs for Identity Assertion providers turn off the token type by default; then an administrator can manually make the token type active by configuring the Identity Assertion provider that validates it.

Note: If an Identity Assertion provider is not developed and configured to validate and accept a token type, the authentication process fails.

## Passing Tokens for Perimeter Authentication

To perform perimeter authentication, clients can pass tokens using HTTP headers, cookies, SSL certificates, or other mechanisms. For example, a string that is base 64-encoded, which enables the sending of binary data, can be sent to a servlet through an HTTP header. The value of this string can be a username or some other string representation of a user's identity. The Identity Assertion provider used for perimeter authentication can then take that string and extract the username.

For example, when using the WebLogic Server 8.1 Security Service Module, if the token is passed through HTTP headers or cookies, the token is equal to the header or cookie value, and the resource container passes the token to the part of the Security Framework that handles authentication. The Security Framework then passes the token to the Identity Assertion provider, unchanged.

# 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

The Principal Validation provider that is associated with the configured Authentication provider signs and verifies all the principals stored in the subject that are the type that the Principal Validation provider is designed to support. A Principal Validation provider is a special type of security provider that acts primarily 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.

Principal Validation providers support specific types of principals. For example, the WebLogic Principal Validation provider signs and verifies the authenticity of WebLogic Enterprise Security principals.

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

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

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

## Security Exceptions Resulting from Invalid Principals

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

- A principal in the subject does not have a corresponding Principal Validation provider configured (which means there is no way for the 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 with an invalid signature was created as part of an attempt to compromise security.
- A subject never had its principals signed.

# Authorization Concepts

An Access Decision is the component of an Authorization provider that actually answers the question, "Is access allowed?" Specifically, an Access Decision asks whether a subject has permission to perform a given operation on a resource, with specific parameters in an application. Given this information, the Access Decision responds with a result of `PERMIT`, `DENY`, or `ABSTAIN`. For more information about Access Decisions, see Implement the AccessDecision SSPI.

# Role Mapping Concepts

Before you develop a Role Mapping provider, you need to understand the following concepts:

- Security Roles
- Dynamic Security Role Computation

## Security Roles

A security role is a named collection of users or groups that have similar permissions to access resources. Like groups, security roles allow you to control access to resources for several users at once. However, unlike groups, security roles can be scoped to resources and actions and are defined dynamically.

The `SecurityRole` interface in the `weblogic.security.service` package is used to represent the abstract notion of a security role. (For more information, see the Javadocs for Security Service Provider Interfaces for the `SecurityRole` interface.)

Mapping a principal to a security role grants the associated access permissions to that principal, as long as the principal is "in" the security role. For example, an application may define a security role called `AppAdmin`, which provides write access to a small subset of that application's resources. Any principal in the `AppAdmin` security role would then have write access to those resources.

Many principals can be mapped to a single security role. For more information about principals, see Users and Groups, Principals and Subjects. Security roles are specified in the Administration Application. For more information, see the Administration Console online help.

## Dynamic Security Role Computation

Dynamic security role computation is the term for the late binding of principals to security roles at runtime. The late binding occurs just prior to an authorization decision for a protected resource, regardless of whether the principal-to-security role association is statically defined or dynamically computed. Because of its placement in the invocation sequence, the result of any principal-to-security role computations can be taken as an authentication identity, as part of the authorization decision made for the request.

This dynamic computation of security roles provides a very important benefit: users or groups can be granted a security role based on business rules. For example, a user may be allowed to be in a `Manager` security role only while the actual manager is away on an extended business trip. Dynamically computing this security role means that you do not need to change or redeploy your application to allow for such a temporarily arrangement. Further, you do not need to remember to revoke the special privileges when the actual manager returns, as you would if you temporarily added the user to a `Managers` group.

Note: You typically grant users or groups security roles using the role conditions available in the Administration Console.

The role mapping provider can access information that comprises the context of the request, including the identity of the target (if available) and the parameter values of the request. The context information is typically used as values of parameters in an expression that is evaluated by the Role Mapping provider. You can define role mapping expressions or rules used by the WebLogic Enterprise Security Role Mapping provider through the Administration Console.

# Auditing Concepts

Before you develop an Auditing provider, you need to understand the following concepts:

- Audit Channels
- Auditing Events from Custom Security Providers

## Audit Channels

An audit channel is the component of an Auditing provider that determines whether a security event is audited and performs the actual recording of audit information.

Note: For more information about Audit Channels, see Implement the AuditChannel SSPI.

## Auditing Events from Custom Security Providers

Each type of security provider can call the configured Auditing providers with a request to write out information about security-related events, before or after these events take place. For example, if a user attempts to access a `withdraw` method in a bank account application (to which they do not have access), the Authorization provider can request that this operation be recorded. Security-related events are only recorded when they meet or exceed the severity level specified in the configuration of the Auditing providers.

For information about how to post audit events from a custom security provider, see Auditing Events from Custom Security Providers.

# Credential Mapping Concepts

A subject or source of a resource request has security-related attributes called credentials. A credential may contain information used to authenticate the subject to new services. Such credentials include username and password combinations, Kerberos tickets, and public key certificates. Credentials can also contain data that allows a subject to perform certain activities. Cryptographic keys, for example, represent credentials that enable the subject to sign or encrypt data.

A credential map is a mapping of credentials used by WebLogic Enterprise Security to credentials used in a legacy or any remote system that tells the WebLogic Enterprise Security system how to connect to a given resource in that system. In other words, credential maps allow WebLogic Enterprise Security to log in to a remote system on behalf of a subject that has already been authenticated. You can map credentials in this way by developing a Credential Mapping provider.