B Generate an MBean Type Using the WebLogic MBeanMaker

This appendix explains how to create the MBean type for your custom security provider.

This appendix includes the following sections:

Overview of Steps

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 security provider by completing the following steps:

  1. Create an MBean Definition File (MDF)

  2. Use the WebLogic MBeanMaker to Generate the MBean Type

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

  4. Install the MBean Type Into the WebLogic Server Environment

Note:

Several sample security providers are available to 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:

  1. Copy the MDF for the sample security provider to a text file.

    For each of the sample security providers, note the following MDF file names:

    Table B-1 MDF File Name

    Sample Security Provider Type MDF File Name

    Authentication provider

    SimpleSampleAuthenticator.xml

    Identity Assertion provider

    SampleIdentityAsserter.xml

    Authorization provider

    SimpleSampleAuthorizer.xml

    Adjudication provider

    There is currently no sample adjudication provider, but you can use the MDF file for the sample authentication provider, SimpleSampleAuthenticator.xml.

    Role Mapping provider

    SimpleSampleRoleMapper.xml

    Auditing provider

    SampleAuditor.xml

    Credential Mapping provider

    There is currently no sample credential mapping provider, but you can use the MDF file for the sample authentication provider, SimpleSampleAuthenticator.xml.

    CertPath provider

    There is currently no sample CertPath provider, but you can use the MDF file for the sample authentication provider, SimpleSampleAuthenticator.xml.

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

    Note the following:

    • If you are creating a custom identity assertion provider, consider the following fragment to set the Base64DecodingRequired attribute to false:

      <MBeanAttribute
        Name         = "Base64DecodingRequired"
        Type         = "boolean"
        Writeable    = "false"
        Default      = "false"
        Description  = "See MyIdentityAsserter-doc.xml."
      />
      
    • If you are creating a custom CertPath provider, you need to extend or implement CertPathBuilderMBean or CertPathValidatorMBean.

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

  4. 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 generates a set of intermediate Java files, including the following:

  • An MBean interface

  • An MBean implementation

  • 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 security provider. Follow the instructions that are appropriate to your situation:

No Custom Operations

This section applies to custom adjudication, role mapping, and auditing providers.

If the MDF for your custom security provider does not include any custom operations, complete the following steps:

  1. Create a new DOS shell.
  2. Type the following command:
    java -DMDF=xmlfile -Dfiles=filesdir -DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker
    

    In the preceding command:

    • The -DMDF flag indicates that the WebLogic MBeanMaker should translate the MDF into code.

    • xmlFile represents the XML MBean description file (MDF).

    • filesdir represents the location where the WebLogic MBeanMaker places the intermediate files for the MBean type.

    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.

    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 for a given security provider type (for example, multiple adjudication providers).

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

No Optional SSPI MBeans and No Custom Operations

This section applies to the following custom security provider types:

  • Authentication providers

  • Identity assertion providers

  • Authorization providers

  • Credential mapping providers

  • CertPath providers

If the MDF for your custom security provider does not implement any optional SSPI MBeans and does not include any custom operations, complete the following steps:

  1. Create a new DOS shell.
  2. Type the following command:
    java -DMDF=xmlfile -Dfiles=filesdir -DcreateStubs=true
     weblogic.management.commo.WebLogicMBeanMaker
    

    In the preceding command:

    • The -DMDF flag indicates that the WebLogic MBeanMaker should translate the MDF into code.

    • xmlFile represents the XML MBean description file (MDF).

    • filesdir represents the location where the WebLogic MBeanMaker places the intermediate files for the MBean type.

    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:

    As of version 9.0 of WebLogic Server, you can also provide a directory that contains multiple MDFs by using the -DMDFDIR <MDF directory name> option. In prior versions of WebLogic Server, the WebLogic MBeanMaker processed only one MDF at a time. Therefore, you had to repeat this process if you had multiple MDFs for a given security provider type (for example, multiple authentication providers).

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

Optional SSPI MBeans or Custom Operations

This section applies to all custom security provider types.

If the MDF for your custom security 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:

  1. Create a new DOS shell.

  2. Type the following command:

    java -DMDF=xmlfile -Dfiles=filesdir -DcreateStubs=true
    weblogic.management.commo.WebLogicMBeanMaker
    

    In the preceding command:

    • The -DMDF flag indicates that the WebLogic MBeanMaker should translate the MDF into code.

    • xmlFile represents the XML MBean description file (MDF).

    • filesdir represents the location where the WebLogic MBeanMaker places the intermediate files for the MBean type.

    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:

    As of version 9.0 of WebLogic Server, you can also provide a directory that contains multiple MDFs by using the -DMDFDIR <MDF directory name> option. In prior versions of WebLogic Server, the WebLogic MBeanMaker processed only one MDF at a time. Therefore, you had to repeat this process if you had multiple MDFs for a given security provider type (for example, multiple authentication providers).

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

    1. Locate the MBean implementation file.

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

    2. For each optional SSPI MBean that you implemented in your MDF, implement each method. Be sure to also provide implementations for any methods that the optional SSPI MBean inherits.

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

  5. Save the file.

  6. 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:

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

  2. Create a new DOS shell.

  3. Type the following command:

    java -DMDF=xmlfile -Dfiles=filesdir -DcreateStubs=true
    weblogic.management.commo.WebLogicMBeanMaker
    

    In the preceding command:

    • The -DMDF flag indicates that the WebLogic MBeanMaker should translate the MDF into code.

    • xmlFile represents the XML MBean description file (MDF).

    • filesdir represents the location where the WebLogic MBeanMaker places the intermediate files for the MBean type.

    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:

    As of version 9.0 of WebLogic Server, you can also provide a directory that contains multiple MDF's by using the -DMDFDIR <MDF directory name> option. In prior versions of WebLogic Server, the WebLogic MBeanMaker processed only one MDF at a time. Therefore, you had to repeat this process if you had multiple MDFs for a given security provider type (for example, multiple authentication providers).

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

    1. Locate and open the MBean implementation file.

      The MBean implementation file generated by the WebLogic MBeanMaker is named <MBeanName>Impl.java. For example, for the MDF named SampleAuthenticator, the MBean implementation file to be edited is named SampleAuthenticatorImpl.java.

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

    3. 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).

    4. If you modified the MDF to implement optional SSPI MBeans that were not in the original MDF, implement each method. Be sure to also provide implementations for any methods that the optional SSPI MBean inherits.

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

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

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

  8. 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 run-time class or your MBean implementation uses 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 has the name of the MDF along with the text MBean appended to it. For example, the result of running the SimpleSampleAuthenticator MDF through the WebLogic MBeanMaker yields the MBean interface file SimpleSampleAuthenticatorMBean.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 run-time classes for the custom security provider into an MBean JAR File (MJF). The WebLogic MBeanMaker also automates this process.

To create an MJF for your custom security provider, complete the following steps:

  1. Create a new DOS shell.

  2. Type the following command:

    java -DMJF=jarfile -Dfiles=filesdir
    weblogic.management.commo.WebLogicMBeanMaker
    

    In the preceding command:

    • The -DMJF flag indicates that the WebLogic MBeanMaker should build a JAR file containing the new MBean types.

    • jarfile represents the name for the MJF.

    • filesdir represents 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.

    Note:

    When you create a JAR file for a custom security provider, a set of XML binding classes and a schema are also generated. You can choose a namespace to associate with that schema. Doing so avoids the possibility that your custom classes conflict with those provided by Oracle. The default for the namespace is vendor. You can change this default by passing the -targetNameSpace argument to the WebLogicMBeanMaker or the associated WLMBeanMaker ant task.

    If you want to update an existing MJF, you must delete the MJF and regenerate it. Do not rename the MJF. 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 WebLogic Server installation directory. This deploys your custom security provider — that is, it makes the custom security provider manageable from the WebLogic Server Administration Console.

Note:

WL_HOME\server\lib\mbeantypes is the default directory for installing MBean types. (Beginning with WebLogic Server 9.0, security providers can be loaded from ...\domaindir\lib\mbeantypes as well.) 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 always loads MBean types from WL_HOME\server\lib\mbeantypes first, then looks in the additional directories and loads all valid archives present in those directories (regardless of their extension).

For example, if -Dweblogic.alternateTypesDirectory = dirX,dirY, WebLogic Server first loads 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). See Using Java Security to Protect WebLogic Resources in Developing Applications with the WebLogic Security Service.

You can create instances of the MBean type by configuring your custom security provider using the WebLogic Server 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.