bea.com | products | dev2dev | support | askBEA |
|
e-docs > WebLogic Server > Developing Security Providers for WebLogic Server > Identity Assertion Providers |
Developing Security Providers for WebLogic Server |
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:
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:
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.
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:
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
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[] {"SamplePerimeterAtnToken"}"
/>
...
</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[] { "SamplePerimeterAtnToken" }"
/>
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:
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:
For information about using CSIv2, see "Using CORBA Common Secure Interoperability Version 2 in EJBs" in Programming 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):
Figure 4-2 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.
The WebLogic Identity Assertion provider supports the following token types:
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
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:
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 7.0 API Reference Javadoc.
Implement the IdentityAsserter SSPI
To implement the IdentityAsserter SSPI, provide implementations for the following method:
For more information about the IdentityAsserter SSPI and the method described above, see the WebLogic Server 7.0 API Reference Javadoc.
Example: Creating the Runtime Class for the Sample Identity Assertion Provider
Listing Note: shows the SampleIdentityAsserterProviderImpl.java class, which is the runtime class for the sample Identity Assertion provider. This runtime class includes implementations for:
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:
Notes: Several sample security providers (available under "Code Direct" 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:
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:
java -DMDF=xmlfile -DFiles=filesdir -DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker
where 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.
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:
java -DMDF=xmlfile -DFiles=filesdir -DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker
where 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.
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.
java -DMDF=xmlfile -DFiles=filesdir -DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker
where 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.
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.
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).
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:
java -DMJF=jarfile -DFiles=filesdir weblogic.management.commo.WebLogicMBeanMaker
where 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.
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 Security Configuration Data" under "Recovering Failed Servers" in Creating and Configuring WebLogic Server Domains.
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.