Developing Security Providers for WebLogic Server

Identity Assertion Providers

An Identity Assertion provider is a specific form of Authentication provider that allows users or system processes to assert their identity using tokens (in other words, perimeter authentication). You can use an Identity Assertion provider in place of an Authentication provider if you create a LoginModule for the Identity Assertion provider, or in addition to an Authentication provider if you want to use the Authentication provider's LoginModule. Identity Assertion providers enable perimeter authentication and support single sign-on.

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

Identity Assertion Concepts

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

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. For more information, see Authentication Providers.
Part of the WebLogic Authentication provider BEA developed and packaged with WebLogic Server. For more information, see Do You Need to Develop a Custom Authentication Provider?.
Part of a third-party security vendor's Authentication provider.

Unlike in a simple authentication situation (described in The Authentication Process), 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 LoginModules.

Identity Assertion and Tokens

You develop Identity Assertion providers to support the specific types of tokens that you will be using to assert the identities of users or system processes. You can develop an Identity Assertion provider to support multiple token types, but you or an administrator 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 realm with the ability to validate the same token type, only one Identity Assertion provider can actually perform this validation.

Note: "Supporting" token types means that the Identity Assertion provider's runtime class (that is, the IdentityAsserter SSPI implementation) can validate the token type its assertIdentity method. For more information, see Implement the IdentityAsserter SSPI.

The following sections will help you work with new token types:

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 WebLogic 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 variables of type String., as shown in Listing 4-1. The PerimeterIdentityAsserterTokenTypes.java file defines the names of the token types Test 1, Test 2, and Test 3 as strings.

Listing 4-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";
}

Note: If you are defining only one new token type, you can also do it right in the Identity Assertion provider's runtime class, as shown in Listing 4-4.

How to Make New Token Types Available for Identity Assertion Provider Configurations

When you or an administrator configure a custom Identity Assertion provider (see Configure the Custom Identity Assertion Provider Using the Administration Console), the Supported Types field displays a list of the token types that the Identity Assertion provider supports. You enter one of the supported types in the Active Types field, as shown in Figure 4-1.

Figure 4-1 Configuring the Sample Identity Assertion Provider

Configuring the Sample Identity Assertion Provider

The content for the Supported Types field is obtained from the SupportedTypes attribute of the MBean Definition File (MDF), which you use to generate your custom Identity Assertion provider's MBean type. An example from the sample Identity Assertion provider is shown in Listing 4-2. (For more information about MDFs and MBean types, see Generate an MBean Type Using the WebLogic MBeanMaker.)

Listing 4-2 SampleIdentityAsserter MDF: SupportedTypes 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 or an administrator can default the ActiveTypes attribute in the MDF so that it does not have to be set manually with the WebLogic Server Administration Console. An example from the sample Identity Assertion provider is shown in Listing 4-3.

Listing 4-3 SampleIdentityAsserter MDF: ActiveTypes Attribute with Default

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

While defaulting the ActiveTypes attribute is convenient, you should only do this if no other Identity Assertion provider will ever validate that token type. Otherwise, it would be easy to configure an invalid security realm (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 will fail. For more information about configuring an Identity Assertion provider, see Configure the Custom Identity Assertion Provider Using the Administration Console.

Passing Tokens for Perimeter Authentication

An Identity Assertion providers can pass tokens from Java clients to servlets for the purpose of perimeter authentication. Tokens can be passed 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.

If the token is passed through HTTP headers or cookies, the token is equal to the header or cookie name, and the resource container passes the token to the part of the WebLogic Security Framework that handles authentication. The WebLogic Security Framework then passes the token to the Identity Assertion provider, unchanged.

Common Secure Interoperability Version 2 (CSIv2)

WebLogic Server provides support for an Enterprise JavaBean (EJB) interoperability protocol based on Internet Inter-ORB (IIOP) (GIOP version 1.2) and the CORBA Common Secure Interoperability version 2 (CSIv2) specification. CSIv2 support in WebLogic Server:

Interoperates with the Java 2 Enterprise Edition (J2EE) version 1.4 reference implementation.
Allows WebLogic Server IIOP clients to specify a username and password in the same manner as T3 clients.
Supports Generic Security Services Application Programming Interface (GSSAPI) initial context tokens. For this release, only usernames and passwords and GSSUP (Generic Security Services Username Password) tokens are supported.

Note: The CSIv2 implementation in WebLogic Server passed Java 2 Enterprise Edition (J2EE) Compatibility Test Suite (CTS) conformance testing.

The external interface to the CSIv2 implementation is a JAAS LoginModule that retrieves the username and password of the CORBA object. The JAAS LoginModule can be used in a WebLogic Java client or in a WebLogic Server instance that acts as a client to another J2EE application server. The JAAS LoginModule for the CSIv2 support is called UsernamePasswordLoginModule, and is located in the weblogic.security.auth.login package.

CSIv2 works in the following manner:

When creating a Security Extensions to Interoperable Object Reference (IOR), WebLogic Server adds a tagged component identifying the security mechanisms that the CORBA object supports. This tagged component includes transport information, client authentication information, and identity token/authorization token information.

The client evaluates the security mechanisms in the IOR and selects the mechanism that supports the options required by the server.

The client uses the SAS protocol to establish a security context with WebLogic Server. The SAS protocol defines messages contained within the service context of requests and replies. A context can be stateful or stateless.

For information about using CSIv2, see Common Secure Interoperability Version 2 in Introduction to WebLogic Security. For more information about JAAS LoginModules, see LoginModules.

The Identity Assertion Process

In perimeter authentication, a system outside of WebLogic Server establishes trust via tokens (as opposed to the type of authentication described in The Authentication Process, where WebLogic Server establishes trust via usernames and passwords). Identity Assertion providers are used as part of perimeter authentication process, which works as follows (see Figure 4-2):

A token from outside of WebLogic Server is passed to an Identity Assertion provider that is responsible for validating tokens of that type and that is configured as "active".

If the token is successfully validated, the Identity Assertion provider maps the token to a WebLogic Server username, and sends that username back to WebLogic Server, which then continues the authentication process as described in The Authentication Process. Specifically, the username is sent via a Java Authentication and Authorization Service (JAAS) CallbackHandler and passed to each configured Authentication provider's LoginModule, so that the LoginModule can populate the subject with the appropriate principals.

Figure 4-2 Perimeter Authentication

Perimeter Authentication

As Figure 4-2 also shows, perimeter authentication requires the same components as the authentication process described in The Authentication Process, but also adds an Identity Assertion provider.

Do You Need to Develop a Custom Identity Assertion Provider?

The WebLogic Identity Assertion provider supports certificate authentication using X509 certificates and CORBA Common Secure Interoperability version 2 (CSIv2) identity assertion.

The WebLogic Identity Assertion provider validates the token type, then maps X509 digital certificates and X501 distinguished names to WebLogic usernames. It also specifies a list of trusted client principals to use for CSIv2 identity assertion. The wildcard character (*) can be used to specify that all principals are trusted. If a client is not listed as a trusted client principal, the CSIv2 identity assertion fails and the invoke is rejected.

Note: To use the WebLogic Identity Assertion provider for X.501 and X.509 certificates, you have the option of using the default user name mapper that is supplied with the WebLogic Server product (weblogic.security.providers.authentication. DefaultUserNameMapperImpl) or providing you own implementation of the weblogic.security.providers.authentication.UserNameMapper interface. This interface maps a X.509 certificate to a WebLogic Server user name according to whatever scheme is appropriate for your needs. You can also use this interface to map from an X.501 distinguished name to a user name. You specify your implementation of this interface when you use the Administration Console to configure an Identity Assertion provider. For more information, see Configuring a User Name Mapper and Configuring a Custom User Name Mapper in Managing WebLogic Security.

The WebLogic Identity Assertion provider supports the following token types:

AU_TYPE—for a WebLogic AuthenticatedUser used as a token.
X509_TYPE—for an X509 client certificate used as a token.
CSI_PRINCIPAL_TYPE—for a CSIv2 principal name identity used as a token.
CSI_ANONYMOUS_TYPE—for a CSIv2 anonymous identity used as a token.
CSI_X509_CERTCHAIN_TYPE—for a CSIv2 X509 certificate chain identity used as a token.
CSI_DISTINGUISHED_NAME_TYPE—for a CSIv2 distinguished name identity used as a token.

If you want to perform additional identity assertion tasks or create new token types, then you need to develop a custom Identity Assertion provider.

How to Develop a Custom Identity Assertion Provider

If the WebLogic Identity Assertion provider does not meet your needs, you can develop a custom Identity Assertion provider by following these steps:

Create Runtime Classes Using the Appropriate SSPIs

Generate an MBean Type Using the WebLogic MBeanMaker

Configure the Custom Identity Assertion Provider Using the Administration Console

Create Runtime Classes Using the Appropriate SSPIs

Before you start creating runtime classes, you should first:

When you understand this information and have made your design decisions, create the runtime classes for your custom Identity Assertion provider by following these steps:

Note: If you want to create a separate LoginModule for your custom Identity Assertion provider (that is, not use the LoginModule from your Authentication provider), you also need to implement the JAAS LoginModule interface, as described in Implement the JAAS LoginModule Interface.

For an example of how to create a runtime class for a custom Identity Assertion provider, see Example: Creating the Runtime Class for the Sample Identity Assertion Provider.

Implement the AuthenticationProvider SSPI

To implement the AuthenticationProvider SSPI, provide implementations for the methods described in Understand the Purpose of the Provider SSPIs and the following methods:

getLoginModuleConfiguration; getAssertionModuleConfiguration; getPrincipalValidator; getIdentityAsserter

Note: When the LoginModule used for the Identity Assertion provider is the same as that used for an existing Authentication provider, implementations for the methods in the AuthenticationProvider SSPI (excluding the getIdentityAsserter method) for Identity Assertion providers can just return null. An example of this is shown in Listing 4-4.

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

Implement the IdentityAsserter SSPI

To implement the IdentityAsserter SSPI, provide implementations for the following method:

assertIdentity

public CallbackHandler assertIdentity(String type, Object token) throws IdentityAssertionException;

The assertIdentity method asserts an identity based on the token identity information that is supplied. In other words, the purpose of this method is to validate any tokens that are not currently trusted against trusted client principals. The type parameter represents the token type to be used for the identity assertion. Note that identity assertion types are case insensitive. The token parameter contains the actual identity information. The CallbackHandler returned from the assertIdentity method is passed to all configured Authentication providers' LoginModules to perform principal mapping, and should contain the asserted username. If the CallbackHandler is null, this signifies that the anonymous user should be used.

Note: In 8.1 versions prior to 8.1 SP05, Identity Assertion calls fail when trying to look up a cached identity if the callback handler does not support the JAAS NameCallback. This is because the name returned by the callback handler is used as the key to find the associated subject in the subject cache; callback handlers that do not support the JAAS NameCallback return a name key that fails to find the subject.

A CallbackHandler is a highly-flexible JAAS standard that allows a variable number of arguments to be passed as complex objects to a method. For more information about CallbackHandlers, see the Java 2 Enterprise Edition, v1.4.1 API Specification Javadoc for the CallbackHandler interface.

For more information about the IdentityAsserter SSPI and the method described above, see the WebLogic Server 8.1 API Reference Javadoc.

Example: Creating the Runtime Class for the Sample Identity Assertion Provider

Listing 4-4 shows the SampleIdentityAsserterProviderImpl.java class, which is the runtime class for the sample Identity Assertion provider. This runtime class includes implementations for:

The three methods inherited from the SecurityProvider interface: initialize, getDescription, and shutdown (as described in Understand the Purpose of the Provider SSPIs.)
The four methods in the AuthenticationProvider SSPI: the getLoginModuleConfiguration, getAssertionModuleConfiguration, getPrincipalValidator, and getIdentityAsserter methods (as described in Implement the AuthenticationProvider SSPI).
The method in the IdentityAsserter SSPI: the assertIdentity method (described in Implement the IdentityAsserter SSPI).

Note: The bold face code in Listing 4-4 highlights the class declaration and the method signatures.

Listing 4-4 SampleIdentityAsserterProviderImpl.java

package examples.security.providers.identityassertion;

import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.login.AppConfigurationEntry;
import weblogic.management.security.ProviderMBean;
import weblogic.security.spi.AuthenticationProvider;
import weblogic.security.spi.IdentityAsserter;
import weblogic.security.spi.IdentityAssertionException;
import weblogic.security.spi.PrincipalValidator;
import weblogic.security.spi.SecurityServices;

public final class SampleIdentityAsserterProviderImpl implements AuthenticationProvider, IdentityAsserter
{
   final static private String TOKEN_TYPE   = "SamplePerimeterAtnToken";
   final static private String TOKEN_PREFIX = "username=";

   private String description;

   public void initialize(ProviderMBean mbean, SecurityServices services)
   {
      System.out.println("SampleIdentityAsserterProviderImpl.initialize");
      SampleIdentityAsserterMBean myMBean = (SampleIdentityAsserterMBean)mbean;
      description = myMBean.getDescription() + "\n" + myMBean.getVersion();
   }

   public String getDescription()
   {
      return description;
   }

   public void shutdown()
   {
      System.out.println("SampleIdentityAsserterProviderImpl.shutdown");
   }

   public AppConfigurationEntry getLoginModuleConfiguration()
   {
      return null;
   }

   public AppConfigurationEntry getAssertionModuleConfiguration()
   {
      return null;
   }

   public PrincipalValidator getPrincipalValidator() 
   {
      return null;
   }

   public IdentityAsserter getIdentityAsserter()
   {
      return this;
   }

   public CallbackHandler assertIdentity(String type, Object token) throws 
   IdentityAssertionException
   {
      System.out.println("SampleIdentityAsserterProviderImpl.assertIdentity");
      System.out.println("\tType\t\t= "  + type);
      System.out.println("\tToken\t\t= " + token);

      if (!(TOKEN_TYPE.equals(type))) {
         String error = "SampleIdentityAsserter received unknown token type \"" 
            + type + "\"." + " Expected " + TOKEN_TYPE;
         System.out.println("\tError: " + error);
         throw new IdentityAssertionException(error);
      }

      if (!(token instanceof byte[])) {
         String error = "SampleIdentityAsserter received unknown token class \"" 
            + token.getClass() + "\"." + " Expected a byte[].";
         System.out.println("\tError: " + error);
         throw new IdentityAssertionException(error);
      }

      byte[] tokenBytes = (byte[])token;
      if (tokenBytes == null || tokenBytes.length < 1) {
         String error = "SampleIdentityAsserter received empty token byte array";
         System.out.println("\tError: " + error);
         throw new IdentityAssertionException(error);
      }

      String tokenStr = new String(tokenBytes);

      if (!(tokenStr.startsWith(TOKEN_PREFIX))) {
         String error = "SampleIdentityAsserter received unknown token string \"" 
            + type + "\"." + " Expected " + TOKEN_PREFIX + "username";
         System.out.println("\tError: " + error);
         throw new IdentityAssertionException(error);
      }

      String userName = tokenStr.substring(TOKEN_PREFIX.length());
      System.out.println("\tuserName\t= " + userName);
      return new SampleCallbackHandlerImpl(userName);
   }

Listing 4-5 shows the sample CallbackHandler implementation that is used along with the SampleIdentityAsserterProviderImpl.java runtime class. This CallbackHandler implementation is used to send the username back to an Authentication provider's LoginModule.

Listing 4-5 SampleCallbackHandlerImpl.java

package examples.security.providers.identityassertion;

import javax.security.auth.callback.Callback;
import javax.security.auth.callback.NameCallback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;

/*package*/ class SampleCallbackHandler implements CallbackHandler
{
   private String userName;

   /*package*/ SampleCallbackHandlerImpl(String user)
   {
      userName = user;
   }

   public void handle(Callback[] callbacks) throws UnsupportedCallbackException
   {
      for (int i = 0; i < callbacks.length; i++) {

            Callback callback = callbacks[i];

            if (!(callback instanceof NameCallback)) {
               throw new UnsupportedCallbackException(callback, "Unrecognized 
                  Callback");
            }

            NameCallback nameCallback = (NameCallback)callback;
            nameCallback.setName(userName);
      }
   }
}

Generate an MBean Type Using the WebLogic MBeanMaker

Before you start generating an MBean type for your custom security provider, you should first:

When you understand this information and have made your design decisions, create the MBean type for your custom Identity Assertion provider by following these steps:

Create an MBean Definition File (MDF)

Use the WebLogic MBeanMaker to Generate the MBean Type

Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF)

Install the MBean Type Into the WebLogic Server Environment

Notes: Several sample security providers (available under Code Samples: WebLogic Server on the dev2dev Web site) illustrate how to perform these steps.

All instructions provided in this section assume that you are working in a Windows environment.

Create an MBean Definition File (MDF)

To create an MBean Definition File (MDF), follow these steps:

Copy the MDF for the sample Identity Assertion provider to a text file.

Note: The MDF for the sample Identity Assertion provider is called SampleIdentityAsserter.xml.

Modify the content of the <MBeanType> and <MBeanAttribute> elements in your MDF so that they are appropriate for your custom Identity Assertion provider.

Add any custom attributes and operations (that is, additional <MBeanAttribute> and <MBeanOperation> elements) to your MDF.

Save the file.

Note: A complete reference of MDF element syntax is available in MBean Definition File (MDF) Element Syntax.

Use the WebLogic MBeanMaker to Generate the MBean Type

Once you create your MDF, you are ready to run it through the WebLogic MBeanMaker. The WebLogic MBeanMaker is currently a command-line utility that takes as its input an MDF, and outputs some intermediate Java files, including an MBean interface, an MBean implementation, and an associated MBean information file. Together, these intermediate files form the MBean type for your custom security provider.

The instructions for generating an MBean type differ based on the design of your custom Identity Assertion provider. Follow the instructions that are appropriate to your situation:

No Optional SSPI MBeans and No Custom Operations

If the MDF for your custom Identity Assertion provider does not implement any optional SSPI MBeans and does not include any custom operations, follow these steps:

Create a new DOS shell.

Type the following command:

java -DMDF=xmlfile -Dfiles=filesdir -DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker
where the -DMDF flag indicates that the WebLogic MBeanMaker should translate the MDF into code, xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.
Whenever xmlfile is provided, a new set of output files is generated. If files already exist in the location specified by filesdir, you are informed that the existing files will be overwritten and are asked to confirm.
Each time you use the -DcreateStubs=true flag, it overwrites any existing MBean implementation file.

Note: The WebLogic MBeanMaker processes one MDF at a time. Therefore, you may have to repeat this process if you have multiple MDFs (in other words, multiple Identity Assertion providers).

Proceed to Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF).

Optional SSPI MBeans or Custom Operations

If the MDF for your custom Identity Assertion provider does implement some optional SSPI MBeans or does include custom operations, consider the following:

Are you creating an MBean type for the first time? If so, follow these steps:

Create a new DOS shell. You must have the following in your classpath:

WL_HOME\server\lib\weblogic.jar
WL_HOME\server\lib\mbeantypes\wlManagement.jar
JAVA_HOME\..\lib\tools.jar
The filedir that you specify in the -Dfiles flag

Type the following command:

java -DMDF=xmlfile -Dfiles=filesdir -DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker
where the -DMDF flag indicates that the WebLogic MBeanMaker should translate the MDF into code, xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.
Copy WL_HOME\server\lib\commo.dtd to the same directory as the xml file specified by the -DMDF flag.
Whenever xmlfile is provided, a new set of output files is generated.
Each time you use the -DcreateStubs=true flag, it overwrites any existing MBean implementation file.

Note: The WebLogic MBeanMaker processes one MDF at a time. Therefore, you may have to repeat this process if you have multiple MDFs (in other words, multiple Identity Assertion providers).

If you implemented optional SSPI MBeans in your MDF, follow these steps:

Locate the MBean implementation file.

The MBean implementation file generated by the WebLogic MBeanMaker is named MBeanNameImpl.java. For example, for the MDF named SampleIdentityAsserter, the MBean implementation file to be edited is named SampleIdentityAsserterImpl.java.

For each optional SSPI MBean that you implemented in your MDF, copy the method stubs from the Mapping MDF Operation Declarations to Java Method Signatures Document (available on the dev2dev Web site) into the MBean implementation file, and implement each method. Be sure to also provide implementations for any methods that the optional SSPI MBean inherits.

If you included any custom operations in your MDF, implement the methods using the method stubs.

Save the file.

Proceed to Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF).

Are you updating an existing MBean type? If so, follow these steps:

Copy your existing MBean implementation file to a temporary directory so that your current method implementations are not overwritten by the WebLogic MBeanMaker.

Create a new DOS shell. You must have the following in your classpath:

WL_HOME\server\lib\weblogic.jar
WL_HOME\server\lib\mbeantypes\wlManagement.jar
JAVA_HOME\..\lib\tools.jar
The filedir that you specify in the -Dfiles flag

Type the following command:

java -DMDF=xmlfile -Dfiles=filesdir -DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker
where the -DMDF flag indicates that the WebLogic MBeanMaker should translate the MDF into code, xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.
Copy WL_HOME\server\lib\commo.dtd to the same directory as the xml file specified by the -DMDF flag.
Whenever xmlfile is provided, a new set of output files is generated.
Each time you use the -DcreateStubs=true flag, it overwrites any existing MBean implementation file.

Note: The WebLogic MBeanMaker processes one MDF at a time. Therefore, you may have to repeat this process if you have multiple MDFs (in other words, multiple Identity Assertion providers).

If you implemented optional SSPI MBeans in your MDF, follow these steps:

Locate and open the MBean implementation file.

The MBean implementation file generated by the WebLogic MBeanMaker is named MBeanNameImpl.java. For example, for the MDF named SampleIdentityAsserter, the MBean implementation file to be edited is named SampleIdentityAsserterImpl.java.

Open your existing MBean implementation file (which you saved to a temporary directory in step 1).

Synchronize the existing MBean implementation file with the MBean implementation file generated by the WebLogic MBeanMaker.

Accomplishing this task may include, but is not limited to: copying the method implementations from your existing MBean implementation file into the newly-generated MBean implementation file (or, alternatively, adding the new methods from the newly-generated MBean implementation file to your existing MBean implementation file), and verifying that any changes to method signatures are reflected in the version of the MBean implementation file that you are going to use (for methods that exist in both MBean implementation files).

If you modified the MDF to implement optional SSPI MBeans that were not in the original MDF, copy the method stubs from the Mapping MDF Operation Declarations to Java Method Signatures Document (available on the dev2dev Web site) into the MBean implementation file, and implement each method. Be sure to also provide implementations for any methods that the optional SSPI MBean inherits.

If you modified the MDF to include any custom operations that were not in the original MDF, implement the methods using the method stubs.

Save the version of the MBean implementation file that is complete (that is, has all methods implemented).

Copy this MBean implementation file into the directory where the WebLogic MBeanMaker placed the intermediate files for the MBean type. You specified this as filesdir in step 3. (You will be overriding the MBean implementation file generated by the WebLogic MBeanMaker as a result of step 3.)

Proceed to Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF).

About the Generated MBean Interface File

The MBean interface file is the client-side API to the MBean that your runtime class or your MBean implementation will use to obtain configuration data. It is typically used in the initialize method as described in Understand the Purpose of the Provider SSPIs.

Because the WebLogic MBeanMaker generates MBean types from the MDF you created, the generated MBean interface file will have the name of the MDF, plus the text "MBean" appended to it. For example, the result of running the SampleIdentityAsserter MDF through the WebLogic MBeanMaker will yield an MBean interface file called SampleIdentityAsserterMBean.java.

Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF)

Once your have run your MDF through the WebLogic MBeanMaker to generate your intermediate files, and you have edited the MBean implementation file to supply implementations for the appropriate methods within it, you need to package the MBean files and the runtime classes for the custom Identity Assertion provider into an MBean JAR File (MJF). The WebLogic MBeanMaker also automates this process.

To create an MJF for your custom Identity Assertion provider, follow these steps:

Create a new DOS shell. You must have the following in your classpath:

WL_HOME\server\lib\weblogic.jar
WL_HOME\server\lib\mbeantypes\wlManagement.jar
JAVA_HOME\..\lib\tools.jar
The filedir that you specify in the -Dfiles flag

Type the following command:

java -DMJF=jarfile -Dfiles=filesdir weblogic.management.commo.WebLogicMBeanMaker
where the -DMJF flag indicates that the WebLogic MBeanMaker should build a JAR file containing the new MBean types, jarfile is the name for the MJF and filesdir is the location where the WebLogic MBeanMaker looks for the files to JAR into the MJF.
Compilation occurs at this point, so errors are possible. If jarfile is provided, and no errors occur, an MJF is created with the specified name.

Notes: If you want to update an existing MJF, simply delete the MJF and regenerate it. The WebLogic MBeanMaker also has a -DIncludeSource option, which controls whether source files are included into the resulting MJF. Source files include both the generated source and the MDF itself. The default is false. This option is ignored when -DMJF is not used.

The resulting MJF can be installed into your WebLogic Server environment, or distributed to your customers for installation into their WebLogic Server environments.

Install the MBean Type Into the WebLogic Server Environment

To install an MBean type into the WebLogic Server environment, copy the MJF into the WL_HOME\server\lib\mbeantypes directory, where WL_HOME is the top-level installation directory for WebLogic Server. This "deploys" your custom Identity Assertion provider—that is, it makes the custom Identity Assertion provider manageable from the WebLogic Server Administration Console.

Note: WL_HOME\server\lib\mbeantypes is the default directory for installing MBean types. However, if you want WebLogic Server to look for MBean types in additional directories, use the -Dweblogic.alternateTypesDirectory=<dir> command-line flag when starting your server, where <dir> is a comma-separated list of directory names. When you use this flag, WebLogic Server will always load MBean types from WL_HOME\server\lib\mbeantypes first, then will look in the additional directories and load all valid archives present in those directories (regardless of their extension). For example, if -Dweblogic.alternateTypesDirectory = dirX,dirY, WebLogic Server will first load MBean types from WL_HOME\server\lib\mbeantypes, then any valid archives present in dirX and dirY. If you instruct WebLogic Server to look in additional directories for MBean types and are using the Java Security Manager, you must also update the weblogic.policy file to grant appropriate permissions for the MBean type (and thus, the custom security provider). For more information, see Using the Java Security Manager to Protect WebLogic Resources in Programming WebLogic Security.

You can create instances of the MBean type by configuring your custom Identity Assertion provider (see Configure the Custom Identity Assertion Provider Using the Administration Console), and then use those MBean instances from a GUI, from other Java code, or from APIs. For example, you can use the WebLogic Server Administration Console to get and set attributes and invoke operations, or you can develop other Java objects that instantiate MBeans and automatically respond to information that the MBeans supply. We recommend that you back up these MBean instances. For more information, see Backing Up Configuration and Security Data under "Recovering Failed Servers" in Configuring and Managing WebLogic Server.

Configure the Custom Identity Assertion Provider Using the Administration Console

Configuring a custom Identity Assertion provider means that you are adding the custom Identity Assertion provider to your security realm, where it can be accessed by applications requiring identity assertion services.

Configuring custom security providers is an administrative task, but it is a task that may also be performed by developers of custom security providers.

Note: The steps for configuring a custom Identity Assertion provider using the WebLogic Server Administration Console are described under Configuring a Custom Security Provider in Managing WebLogic Security.