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). Identity Assertion providers enable perimeter authentication and support single sign-on. 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.

If you want to allow the Identity Assertion provider to be configured separately from the Authentication provider, write two providers. If your Identity Assertion provider and Authentication provider cannot work independently, then write one provider.

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.

The LoginModules in this configuration must:

Populate the Subject with required Principals, such as those of type WLSGroup.
Must trust that the user has submitted sufficient proof to login and not require a password or some other proof material.

You must implement the AuthenticationProviderV2.getAssertionModuleConfiguration method in your custom Authentication provider, as described in Implement the AuthenticationProviderV2 SSPI. This method is called for identity assertion, such as when an X.509 certificate is being used, and to process the run-as tag in deployment descriptors. Other single signon strategies use it as well.

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 IdentityAsserterV2 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. The token types currently defined for the WebLogic Identity Assertion provider include, but are not limited to: X.509, CSI.PrincipalName, CSI.ITTAnonymous, CSI.X509CertChain, CSI.DistinguishedName, AUTHORIZATION_NEGOTIATE, SAML.Assertion64, SAML.Assertion.DOM, SAML.Assertion, and WWW-AUTHENTICATE_NEGOTIATE.

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 provider 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.

WebLogic Server is designed to extend the single sign-on concept all the way to the perimeter through support for identity assertion. Identity assertion allows WebLogic Server to use the authentication mechanism provided by perimeter authentication schemes such as the Security Assertion Markup Language (SAML), the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO), or enhancements to protocols such as Common Secure Interoperability (CSI) v2 to achieve this functionality.

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 Understanding 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 providers support certificate authentication using X509 certificates, SPNEGO tokens, SAML assertion tokens, and CORBA Common Secure Interoperability version 2 (CSIv2) identity assertion.

The LDAP X509 Identity Assertion provider receives an X509 certificate, looks up the LDAP object for the user associated with that certificate, ensures that the certificate in the LDAP object matches the presented certificate, and then retrieves the name of the user from the LDAP object for the purpose of authentication.

The Negotiate Identity Assertion provider is used for SSO with Microsoft clients that support the SPNEGO protocol. The Negotiate Identity Assertion provider decodes SPNEGO tokens to obtain Kerberos tokens, validates the Kerberos tokens, and maps Kerberos tokens to WebLogic users. The Negotiate Identity Assertion provider utilizes the Java Generic Security Service (GSS) Application Programming Interface (API) to accept the GSS security context via Kerberos. The Negotiate Identity Assertion provider is for Windows NT Integrated Login.

The SAML Identity Assertion provider handles SAML assertion tokens when WebLogic Server acts as a SAML destination site. The SAML Identity Assertion provider consumes and validates SAML assertion tokens and determines if the assertion is to be trusted (using either the proof material available in the SOAP message, the client certificate, or some other configuration indicator).

The default 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.

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.
AUTHORIZATION_NEGOTIATE—for a SPNEGO internal token used as a token.
SAML_ASSERTION_B64_TYPE—for a Base64 encoded SAML.assertion used as a token.
SAML_ASSERTION_DOM_TYPE—for a SAML DOM element used as a token.
SAML_ASSERTION_TYPE—for a SAML string XML form used as a token.
SAML_SSO_CREDENTIAL_TYPE—for a SAML string consisting of the TARGET parameter concatenated with the assertion itself and used as a token.
WSSE_PASSWORD_DIGEST_TYPE—for a username token with a password type of password digest used as a token.
WWW_AUTHENTICATE_NEGOTIATE—for a SPNEGO internal token 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

Consider whether you need to implement Challenge Identity Assertion, as described in Challenge Identity Assertion.

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 AuthenticationProviderV2 SSPI

Note: The AuthenticationProvider SSPI is deprecated in this release of WebLogic Server. Use the AuthenticationProviderV2 SSPI instead.

To implement the AuthenticationProviderV2 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 AuthenticationProviderV2 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 API Reference Javadoc.

Implement the IdentityAsserterV2 SSPI

Note: The IdentityAsserterV2 SSPI includes additional token types and a handler parameter to the assertIdentity method that can optionally be used to obtain additional information when asserting the identity. Although the IdentityAsserter SSPI is still supported, you should consider using the IdentityAsserterV2 SSPI instead.

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

assertIdentity

For more information about the IdentityAsserterV2 SSPI and the method described above, see the WebLogic Server 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 AuthenticationProviderV2 SSPI: the getLoginModuleConfiguration, getAssertionModuleConfiguration, getPrincipalValidator, and getIdentityAsserter methods (as described in Implement the AuthenticationProviderV2 SSPI.
The method in the IdentityAsserterV2 SSPI: the assertIdentity method (described in Implement the IdentityAsserterV2 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.simple;

import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.login.AppConfigurationEntry;
import weblogic.management.security.ProviderMBean;
import weblogic.security.service.ContextHandler;
import weblogic.security.spi.AuthenticationProviderV2;
import weblogic.security.spi.IdentityAsserterV2;
import weblogic.security.spi.IdentityAssertionException;
import weblogic.security.spi.PrincipalValidator;
import weblogic.security.spi.SecurityServices;

public final class SimpleSampleIdentityAsserterProviderImpl implements AuthenticationProviderV2, IdentityAsserterV2
{
   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("SimpleSampleIdentityAsserterProviderImpl.initialize");
      SimpleSampleIdentityAsserterMBean myMBean = (SimpleSampleIdentityAsserterMBean)mbean;
      description = myMBean.getDescription() + "\n" + myMBean.getVersion();
   }

   public String getDescription()
   {
      return description;
   }

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

   public IdentityAsserterV2 getIdentityAsserter()
   {
      return this;
   }

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

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

      if (!(token instanceof byte[])) {
         String error = "SimpleSampleIdentityAsserter 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 = "SimpleSampleIdentityAsserter 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 = "SimpleSampleIdentityAsserter 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 SimpleSampleCallbackHandlerImpl(userName);
   }

   public AppConfigurationEntry getLoginModuleConfiguration()
   {
      return null;
   }

   public AppConfigurationEntry getAssertionModuleConfiguration()
   {
      return null;
   }

   public PrincipalValidator getPrincipalValidator()
   {
      return null;
   }

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.simple;

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 SimpleSimpleSampleCallbackHandler implements CallbackHandler
{
   private String userName;

   /*package*/ SimpleSampleCallbackHandlerImpl(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: As of this version 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 (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.

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: As of this version 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 (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.

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: As of this version 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 (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.

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: 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 will conflict with those provided by BEA. 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, 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. (Beginning with 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 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.

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 Weblogic Security Providers in Securing WebLogic Server.

Challenge Identity Assertion

The Challenge Identity Asserter interface supports challenge response schemes in which multiple challenges, responses messages, and state are required. The Challenge Identity Asserter interface allows Identity Assertion providers to support authentication protocols such as Microsoft's Windows NT Challenge/Response (NTLM), Simple and Protected GSS-API Negotiation Mechanism (SPNEGO), and other challenge/response authentication mechanisms.

Challenge/Response Limitations in the Java Servlet API 2.3 Environment

The WebLogic Security Framework allows you to provide a custom Authentication and Identity Assertion provider. However, due to the nature of the Java Servlet API 2.3 specification, the interaction between the Authentication provider and the client or other servers is architecturally limited during the authentication process. This restricts authentication mechanisms to those that are compatible with the authentication mechanisms the Servlet container offers: basic, form, and certificate.

Servlet authentication filters, which are described in Servlet Authentication Filters, have fewer architecturally-dependence limitations; that is, they are not dependent on the authentication mechanisms offered by the servlet container. By allowing filters to be invoked prior to the container beginning the authentication process, a security realm can implement a wider scope of authentication mechanisms. For example, a servlet authentication filter could redirect the user to a SAML provider site for authentication.

Servlet authentication filters provide a convenient way to implement a challenge/response protocol in your environment. Filters allow your Challenge Identity Assertion interface to loop through your challenge/response mechanism as often as needed to complete the challenge.

Filters and The Role of the weblogic.security.services.Authentication Class

Servlet authentication filters allow you to implement a challenge/response protocol without being limited to the authentication mechanisms compatible with the Servlet container. However, because servlet authentication filters operate outside of the authentication environment provided by the Security Framework, they cannot depend on the Security Framework to determine provider context, and require an API to drive the multiple-challenge Identity Assertion process.

In this release, the weblogic.security.services.Authentication class has been extended to allow multiple challenge/response identity assertion from a servlet authentication filter. The new methods and interface provide a wrapper for the ChallengeIdentityAsserterV2 and ProviderChallengeContext interfaces so that you can invoke them from a servlet authentication filter.

There is no other documented way to perform a multiple challenge/response dialog from a servlet authentication filter within the context of the Security Framework. Your servlet authentication filter cannot directly invoke the ChallengeIdentityAsserterV2 and ProviderChallengeContext interfaces.

Therefore, you need to implement the ChallengeIdentityAsserterV2 and ProviderChallengeContext interfaces, and then use the weblogic.security.services.Authentication methods and AppChallengeContext interface to invoke them from a servlet authentication filter.

How to Develop a Challenge Identity Asserter

To develop a Challenge Identity Asserter:

Implement the ChallengeIdentityAsserterV2 Interface

The ChallengeIdentityAsserterV2 interface extends the IdentityAsserterV2 SSPI. You must implement the ChallengeIdentityAsserterV2 interface in addition to the IdentityAsserterV2 SSPI.

Provide an implementation for all of the IdentityAsserterV2 methods, and the following methods:

assertChallengeIdentity

ProviderChallengeContext assertChallengeIdentity(String tokenType, Object token, ContextHandler handler)

Use the supplied client token to establish client identity, possibly with multiple challenges. This method returns your implementation of the ProviderChallengeContext interface. The ProviderChallengeContext interface provides a means to query the state of the challenges.

continueChallengeIdentity

void continueChallengeIdentity(ProviderChallengeContext context, String tokenType, Object token, ContextHandler handler)

Use the supplied provider context and client token to continue establishing client identity.

getChallengeToken

Object getChallengeToken(String type, ContextHandler handler)

This method returns the Identity Assertion provider's challenge token.

Implement the ProviderChallengeContext Interface

The ProviderChallengeContext interface provides a means to query the state of the challenges. It allows the assertChallengeIdentity and continueChallengeIdentity methods of the ChallengeIdentityAsserterV2 interface to return either the callback handler or a new challenge to which the client must respond.

To implement the ProviderChallengeContext interface, provide implementations for the following methods:

getCallbackHandler

CallbackHandler getCallbackHandler()

This method returns the callback handler for the challenge identity assertion. Call this method only when the hasChallengeIdentityCompleted method returns true.

getChallengeToken

Object getChallengeToken()

This method returns the challenge token for the challenge identity assertion. Call this method only when the hasChallengeIdentityCompleted method returns false.

hasChallengeIdentityCompleted

boolean hasChallengeIdentityCompleted

This method returns whether the challenge identity assertion has completed. It returns true if the challenge identity assertion has completed, false if not. If true, the caller should use the getCallbackHandler method. If false, then the caller should use the getChallengeToken method.

Invoke the weblogic.security.services Challenge Identity Methods

Have your servlet authentication filter invoke the following weblogic.security.services.Authentication methods instead of calling the ChallengeIdentityAsserterV2 SSPI directly:

assertChallengeIdentity

AppChallengeContext assertChallengeIdentity(String tokenType, Object token, AppContext appContext)

Use the supplied client token to establish client identity, possibly with multiple challenges. This method returns the context of the challenge identity assertion. This result may contain either the authenticated subject or an additional challenge to which the client must respond. The AppChallengeContext interface provides a means to query the state of the challenges.

continueChallengeIdentity

void continueChallengeIdentity(AppChallengeContext context, String tokenType, Object token, AppContext appContext)

Use the supplied provider context and client token to continue establishing client identity.

getChallengeToken

Object getChallengeToken

This method returns the initial challenge token for the challenge identity assertion.

Invoke the weblogic.security.services AppChallengeContext Methods

Have your servlet authentication filter invoke the following AppChallengeContext methods instead of invoking the ProviderChallengeContext interface directly:

getAuthenticatedSubject

Subject getAuthenticatedSubject()

Returns the authenticated subject for the challenge identity assertion. Call this method only when the hasChallengeIdentityCompleted method returns true.

getChallengeToken

Object getChallengeToken()

This method returns the challenge token for the challenge identity assertion. Call this method only when the hasChallengeIdentityCompleted method returns false.

hasChallengeIdentityCompleted

boolean hasChallengeIdentityCompleted()

This method returns whether the challenge identity assertion has completed. It returns true if the challenge identity assertion has completed, false if not. If true, the caller should use the getCallbackHandler method. If false, then the caller should use the getChallengeToken method.

Implementing Challenge Identity Assertion from a Filter

In the following code flow, assume that the servlet authentication filter, which is described in Servlet Authentication Filters, handles the HTTP level interactions (Authorization and WWW-Authenticate) and is also responsible for calling the weblogic.security.services.Authentication methods and interfaces to drive the Challenge Identity Assertion process.

Browser sends a request

Filter sees requests and no Authorization header, so it calls the weblogic.security.services.Authentication getChallengeToken method to get an initial token and sends a 401 response with a WWW-Authenticate negotiate header back

Browser sees 401 with WWW-Authenticate and responds with a new request and a Authorization Negotiate token.

Filter sees this and calls the weblogic.security.services.Authentication assertChallengeIdentity method. assertChallengeIdentity takes the token as input, processes it according to whatever rules it needs to follow for the assertion process it is following (for example, if NTLM, then do whatever NTLM requires to process the token), and determine if that succeeded or not. assertChallengeIdentity returns your implementation of the AppChallengeContext interface.

Filter calls appChallengeContext hasChallengeCompleted method. Use the AppChallengeContext hasChallengeIdentityCompleted method to see if the challenge has completed. For example, it can determine if the callback handler is not null, meaning that it contains a username, and return true. In this use it returns false, so it must issue another challenge to the client. The filter then calls AppChallengeContext getChallengeToken to get the token to challenge back with.

Filter likely stores the AppChallengeContext somewhere such as a session attribute.

Filter sends a 401 response with an WWW-Authenticate negotiate and the new token.

Browser sees the new challenge and responds again with an Authorization header.

Filter sees this and calls the weblogic.security.services.Authentication continueChallengeIdentity method.

Filter calls the AppChallengeContext hasChallengeCompleted method. If it returns false another challenge is in order, so call the AppChallengeContext getChallengeToken method to get the token to challenge back with, and so forth. If it returned true, then the challenge has completed and the filter would then call AppChallengeContext getAuthenticatedSubject method and perform a runAs(subject, request).