|
|
Careful planning of development activities can greatly reduce the time and effort you spend developing custom security providers. The following sections describe security provider concepts and functionality in more detail to help you get started:
Although there are different types of security providers you can create (see Types of Security Providers in Understanding WebLogic Security), all security providers follow the same general architecture. Figure 3-1 illustrates the general architecture of a security provider, and an explanation follows.
| Note: | The SSPIs and the runtime classes (that is, implementations) you will create using the SSPIs are shown on the left side of Figure 3-1 and are .java files. |
| Note: | Like the other files on the right side of Figure 3-1, MyFooMBean begins as a .xml file, in which you will extend (and optionally implement) SSPI MBeans. When this MBean Definition File (MDF) is run through the WebLogic MBeanMaker utility, the utility generates the .java files for the MBean type, as described in
Generating an MBean Type to Configure and Manage the Custom Security Provider. |
Figure 3-1 shows the relationship between a single runtime class (MyFooProviderImpl) and an MBean type (MyFooMBean) you create when developing a custom security provider. The process begins when a WebLogic Server instance starts, and the WebLogic Security Framework:
Therefore, both the runtime class (or classes) and the MBean type form what is called the "security provider."
As described in Overview of the Development Process, you develop a custom security provider by first implementing a number of security services provider interfaces (SSPIs) to create runtime classes. This section helps you:
Additionally, this section provides an SSPI Quick Reference that indicates which SSPIs can be implemented for each type of security provider.
Security providers must adhere to the following restrictions:
J2EE services in other domains are accessible and can be used within a security provider.
Each SSPI that ends in the suffix "Provider" (for example, CredentialProvider) exposes the services of a security provider to the WebLogic Security Framework. This allows the security provider to be manipulated (initialized, started, stopped, and so on).
As shown in Figure 3-2, the SSPIs exposing security services to the WebLogic Security Framework are provided by WebLogic Server, and all extend the SecurityProvider interface, which includes the following methods:
initialize method takes as an argument a ProviderMBean, which can be narrowed to the security provider's associated MBean instance. The MBean instance is created from the MBean type you generate, and contains configuration data that allows the custom security provider to be managed in the WebLogic Server environment. If this configuration data is available, the initialize method should be used to extract it.
The securityServices argument is an object from which the custom security provider can obtain and use the Auditor Service. For more information about the Auditor Service and auditing, see
Auditing Providers and Auditing Events From Custom Security Providers.
Because they extend SecurityProvider, a runtime class that implements any SSPI ending in "Provider" must provide implementations for these inherited methods.
Version 9.2 of WebLogic Server includes bulk access versions of the following Authorization, Adjudication, and Role Mapping provider SSPI interfaces:
The bulk access SSPI interfaces allow Authorization, Adjudication, and Role Mapping providers to receive multiple decision requests in one call rather than through multiple calls, typically in a 'for' loop. The intent of the bulk SSPI variants is to allow provider implementations to take advantage of internal performance optimizations, such as detecting that many of the passed-in Resource objects are protected by the same policy and will generate the same decision result.
See Bulk Authorization Providers, Bulk Adjudication Providers, and Bulk Role Mapping Providers for additional information.
Implementations of SSPIs that begin with the prefix "Deployable" and end with the suffix "Provider" (for example, DeployableRoleProviderV2) expose the services of a custom security provider into the WebLogic Security Framework as explained in
Understand the Purpose of the Provider SSPIs. However, implementations of these SSPIs also perform additional tasks. These SSPIs also provide support for security in deployment descriptors, including the servlet deployment descriptors (web.xml, weblogic.xml), the EJB deployment descriptors (ejb-jar.xml, weblogic-ejb.jar.xml) and the EAR deployment descriptors (application.xml, weblogic-application.xml).
Authorization providers, Role Mapping providers, and Credential Mapping providers have deployable versions of their "Provider" SSPIs.
| Note: | If your security provider database (which stores security policies, security roles, and credentials) is read-only, you can implement the non-deployable version of the SSPI for your Authorization, Role Mapping, and Credential Mapping security providers. However, you will still need to configure deployable versions of these security provider that do handle deployment. |
An Authorization provider that supports deploying security policies on behalf of Web application or Enterprise JavaBean (EJB) deployments needs to implement the DeployableAuthorizationProviderV2 SSPI instead of the AuthorizationProvider SSPI. (However, because the DeployableAuthorizationProviderV2 SSPI extends the AuthorizationProvider SSPI, you actually will need to implement the methods from both SSPIs.) This is because Web application and EJB deployment activities require the Authorization provider to perform additional tasks, such as creating and removing security policies. In a security realm, at least one Authorization provider must support the DeployableAuthorizationProviderV2 SSPI, or else it will be impossible to deploy Web applications and EJBs.
| Note: | For more information about security policies, see Security Policies in Securing WebLogic Resources Using Roles and Policies. |
A Role Mapping provider that supports deploying security roles on behalf of Web application or Enterprise JavaBean (EJB) deployments needs to implement the DeployableRoleProviderV2 SSPI instead of the RoleProvider SSPI. (However, because the DeployableRoleProviderV2 SSPI extends the RoleProvider SSPI, you will actually need to implement the methods from both SSPIs.) This is because Web application and EJB deployment activities require the Role Mapping provider to perform additional tasks, such as creating and removing security roles. In a security realm, at least one Role Mapping provider must support this SSPI, or else it will be impossible to deploy Web applications and EJBs.
| Note: | For more information about security roles, see Users, Groups, and Security Roles in Securing WebLogic Resources Using Roles and Policies. |
| Note: | The DeployableCredentialProvider interface is deprecated in this release of WebLogic Server. |
A Credential Mapping provider that supports deploying security policies on behalf of Resource Adapter (RA) deployments needs to implement the DeployableCredentialProvider SSPI instead of the CredentialProvider SSPI. (However, because the DeployableCredentialProvider SSPI extends the CredentialProvider SSPI, you will actually need to implement the methods from both SSPIs.) This is because Resource Adapter deployment activities require the Credential Mapping provider to perform additional tasks, such as creating and removing credentials and mappings. In a security realm, at least one Credential Mapping provider must support this SSPI, or else it will be impossible to deploy Resource Adapters.
| Notes: | For more information about credentials, see Credential Mapping Concepts. For more information about security policies, see Security Policies in Securing WebLogic Resources Using Roles and Policies. |
Figure 3-3 uses a Credential Mapping provider to illustrate the inheritance hierarchy that is common to all SSPIs, and shows how a runtime class you supply can implement those interfaces. In this example, BEA supplies the SecurityProvider interface, and the CredentialProviderV2 and CredentialMapperV2 SSPIs. Figure 3-3 shows a single runtime class called MyCredentialMapperProviderImpl that implements the CredentialProviderV2 and CredentialMapperV2 SSPIs.
However, Figure 3-3 illustrates only one way you can implement SSPIs: by creating a single runtime class. If you prefer, you can have two runtime classes (as shown in Figure 3-4): one for the implementation of the SSPI ending in "Provider" (for example, CredentialProviderV2), and one for the implementation of the other SSPI (for example, the CredentialMapperV2 SSPI).
When there are separate runtime classes, the class that implements the SSPI ending in "Provider" acts as a factory for generating the runtime class that implements the other SSPI. For example, in Figure 3-4, MyCredentialMapperProviderImpl acts as a factory for generating MyCredentialMapperImpl.
| Note: | If you decide to have two runtime implementation classes, you need to remember to include both runtime implementation classes in the MBean JAR File (MJF) when you generate the security provider's MBean type. For more information, see Generating an MBean Type to Configure and Manage the Custom Security Provider. |
Table 3-1 maps the types of security providers (and their components) with the SSPIs and other interfaces you use to develop them.
| Note: | The SSPIs you use to create runtime classes for custom security providers are located in the weblogic.security.spi package. For more information about this package, see the WebLogic Server API Reference Javadoc. |
As described in Overview of the Development Process, the second step in developing a custom security provider is generating an MBean type for the custom security provider. This section helps you:
Additionally, this section provides an SSPI MBean Quick Reference that indicates which required SSPI MBeans must be extended and which optional SSPI MBeans can be implemented for each type of security provider.
In addition to creating runtime classes for a custom security provider, you must also generate an MBean type. The term MBean is short for managed bean, a Java object that represents a Java Management eXtensions (JMX) manageable resource.
| Note: | JMX is a specification created by Sun Microsystems that defines a standard management architecture, APIs, and management services. For more information, see the Java Management Extensions White Paper. |
An MBean type is a factory for instances of MBeans, the latter of which you or an administrator can create using the WebLogic Server Administration Console. Once they are created, you can configure and manage the custom security provider using the MBean instance, through the Administration Console.
| Note: | All MBean instances are aware of their parent type, so if you modify the configuration of an MBean type, all instances that you or an administrator may have created using the Administration Console will also update their configurations. (For more information, see Understand the SSPI MBean Hierarchy and How It Affects the Administration Console.) |
You use MBean interfaces called SSPI MBeans to create MBean types. There are two types of SSPI MBeans you can use to create an MBean type for a custom security provider:
For more information, see SSPI MBean Quick Reference.
An MBean Definition File (MDF) is an XML file used by the WebLogic MBeanMaker utility to generate the Java files that comprise an MBean type. All MDFs must extend a required SSPI MBean that is specific to the type of the security provider you have created, and can implement optional SSPI MBeans.
Listing 3-1 shows a sample MBean Definition File (MDF), and an explanation of its content follows. (Specifically, it is the MDF used to generate an MBean type for the WebLogic Credential Mapping provider. Note that the DeployableCredentialProvider interface is deprecated in this release of WebLogic Server.)
| Note: | A complete reference of MDF element syntax is available in MBean Definition File (MDF) Element Syntax. |
<?xml version="1.0" ?>
<!DOCTYPE MBeanType SYSTEM "commo.dtd">
<MBeanType
Name = "DefaultCredentialMapper"
DisplayName = "DefaultCredentialMapper"
Package = "weblogic.security.providers.credentials"
Extends = "weblogic.management.security.credentials. DeployableCredentialMapper"
Implements = "weblogic.management.security.credentials. UserPasswordCredentialMapEditor,
weblogic.management.security.credentials.UserPasswordCredentialMapExtendedReader,
weblogic.management.security.ApplicationVersioner,
weblogic.management.security.Import,
weblogic.management.security.Export"
PersistPolicy = "OnUpdate"
Description = "This MBean represents configuration attributes for the WebLogic Credential Mapping provider.<p>"
>
<MBeanAttribute
Name = "ProviderClassName"
Type = "java.lang.String"
Writeable = "false"
Default = ""weblogic.security.providers.credentials. DefaultCredentialMapperProviderImpl""
Description = "The name of the Java class that loads the WebLogic Credential Mapping provider."
/>
<MBeanAttribute
Name = "Description"
Type = "java.lang.String"
Writeable = "false"
Default = ""Provider that performs Default Credential Mapping""
Description = "A short description of the WebLogic Credential Mapping provider."
/>
<MBeanAttribute
Name = "Version"
Type = "java.lang.String"
Writeable = "false"
Default = ""1.0""
Description = "The version of the WebLogic Credential Mapping provider."
/>
:
:
</MBeanType>
The bold attributes in the <MBeanType> tag show that this MDF is named DefaultCredentialMapper and that it extends the required SSPI MBean called DeployableCredentialMapper. It also includes additional management capabilities by implementing the UserPasswordCredentialMapEditor optional SSPI MBean.
The ProviderClassName, Description, and Version attributes defined in the <MBeanAttribute> tags are required in any MDF used to generate MBean types for security providers because they define the security provider's basic configuration methods, and are inherited from the base required SSPI MBean called Provider (see Figure 3-5). The ProviderClassName attribute is especially important. The value for the ProviderClassName attribute is the Java filename of the security provider's runtime class (that is, the implementation of the appropriate SSPI ending in "Provider"). The example runtime class shown in Listing 3-1 is DefaultCredentialMapperProviderImpl.java.
While not shown in Listing 3-1, you can include additional attributes and operations in an MDF using the <MBeanAttribute> and <MBeanOperation> tags. Most custom attributes will automatically appear in the Provider Specific tab for your custom security provider in the WebLogic Server Administration Console. To display custom operations, however, you need to write a console extension. (See Writing Console Extensions.)
| Note: | The Sample Auditing provider (available under Code Samples: WebLogic Server on the dev2dev Web site) provides an example of adding a custom attribute. |
Classes loaded from WL_HOME\server\lib\mbeantypes are not visible to other JAR and EAR files deployed on WebLogic Server. If you have common utility classes that you want to share, you must place them in the system classpath.
| 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. JAR files loaded from the ...\domaindir\lib\mbeantypes directory can be shared across applications. They do not need to be explicitly placed in the system classpath. |
Your custom provider MBeans must throw only JDK exception types or weblogic.management.utils exception types. Otherwise, JMX clients may not include the code necessary to receive your exceptions.
weblogic.management.utils exceptions. As described in Table A-2, you can use the Encrypted attribute to specify that the value of an MBean attribute should not be displayed as clear text. For example, you encrypt the value of the MBean attribute when getting input for a password. The following code fragment shows an example of using the Encrypted attribute:
<MBeanAttribute
Name = "PrivatePassPhrase"
Type = "java.lang.String"
Encrypted = "true"
Default = """"
Description = "The Keystore password."
/>
All attributes and operations that are specified in the required SSPI MBeans that your MBean Definition File (MDF) extends (all the way up to the Provider base SSPI MBean) automatically appear in a WebLogic Server Administration Console page for the associated security provider. You use these attributes and operations to configure and manage your custom security providers.
| Note: | For Authentication security providers only, the attributes and operations that are specified in the optional SSPI MBeans your MDF implements are also automatically supported by the Administration Console. For other types of security providers, you must write a console extension in order to make the attributes and operations inherited from the optional SSPI MBeans available in the Administration Console. For more information, see Writing Console Extensions. |
Figure 3-5 illustrates the SSPI MBean hierarchy for security providers (using the WebLogic Credential Mapping MDF as an example), and indicates what attributes and operations will appear in the Administration Console for the WebLogic Credential Mapping provider.
Implementing the hierarchy of SSPI MBeans in the DefaultCredentialMapper MDF (shown in Figure 3-5) produces the page in the Administration Console that is shown in Figure 3-6. (A partial listing of the DefaultCredentialMapper MDF is shown in Listing 3-1.)
The Name, Description, and Version fields come from attributes with these names inherited from the base required SSPI MBean called Provider and specified in the DefaultCredentialMapper MDF. Note that the DisplayName attribute in the DefaultCredentialMapper MDF generates the value for the Name field, and that the Description and Version attributes generate the values for their respective fields as well. The Credential Mapping Deployment Enabled field is displayed (on the Provider Specific page) because of the CredentialMappingDeploymentEnabled attribute in the DeployableCredentialMapper required SSPI MBean, which the DefaultCredentialMapper MDF extends. Notice that this Administration Console page does not display a field for the DefaultCredentialMapper implementation of the UserPasswordCredentialMapEditor optional SSPI MBean.
The WebLogic MBeanMaker is a command-line utility that takes an MBean Definition File (MDF) as input and outputs files for an MBean type. When you run the MDF you created through the WebLogic MBeanMaker, the following occurs:
Necessary developer action: None. No further work must be done for these methods.
Necessary developer action: Currently, the WebLogic MBeanMaker does not generate method stubs for these inherited methods, so you will need to use the Mapping MDF Operation Declarations to Java Method Signatures Document (available under Code Samples: WebLogic Server on the dev2dev Web site) to supply the appropriate implementations.
Necessary developer action: You must provide implementations for these methods. (However, because the WebLogic MBeanMaker generates the stubs, you do not need to look up the Java method signatures.)
This is illustrated in Figure 3-7.
The MBean information file contains a compiled definition of the data in the MBean Definition File in a form that JMX Model MBeans require. The format of this file is a list of attributes, operations, and notifications, each of which also has a set of descriptor tags that describe that entity. In addition, the MBean itself also has a set of descriptor tags. An example of this format is as follows:
attribute1 + tags, attribute2 + tags ...
operation1 + tags, operation2 + tags ...
notification1 + tags, notification2 + tags ...
If desired, you can access this information at runtime by calling the standard JMX server getMBeanInfo method to obtain the ModelMBeanInfo.
| Note: | Be sure to reference the JMX specification to determine how to interpret the returned structure. |
Based on the list of SSPIs you need to implement as part of developing your custom security provider, locate the required SSPI MBeans you need to extend in Table 3-2. Using Table 3-3 through Table 3-5, locate any optional SSPI MBeans you also want to implement for managing your security provider.
| Note: | The required SSPI MBeans shown in Table 3-2 are located in the weblogic.management.security.<Package_Name> package. |
| Notes: | The optional Authentication SSPI MBeans shown in Table 3-3 are located in the weblogic.management.security.authentication package. They are also supported in the WebLogic Server Administration Console. |
| Note: | For an example of how to implement the optional Authentication SSPI MBeans shown in Table 3-3, review the code for the Manageable Sample Authentication provider (available under Code Samples: WebLogic Server on the dev2dev Web site). |
| Note: | The optional Authorization SSPI MBeans shown in Table 3-4 are located in the weblogic.management.security.authorization package. |
| Note: | The optional Credential Mapping SSPI MBeans shown in Table 3-5 are located in the weblogic.management.security.credentials package. |
Several of the WebLogic security providers have been developed to support security data migration. This means that administrators can export users and groups (for the WebLogic Authentication provider), security policies (for the WebLogic Authorization provider), security roles (for the WebLogic Role Mapping provider), or credential mappings (for the Credential Mapping provider) from one security realm, and then import them into another security realm. Administrators can migrate security data for each of these WebLogic security providers individually, or migrate security data for all the WebLogic security providers at once (that is, security data for the entire security realm).
The migration of security data may be helpful to administrators when:
The following sections provide more information about security data migration:
Before you start to work with security data migration, you need to understand the following concepts:
A format is simply a data format that specifies how security data should be exported or imported. Currently, WebLogic Server does not provide any standard, public formats for developers of security providers. Therefore, the format you use is entirely up to you. Keep in mind, however, that for data to be exported from one security provider and later imported to another security provider, both security providers must understand how to process the same format. Supported formats are the list of data formats that a given security provider understands how to process.
| Notes: | Because the data format used for the WebLogic security providers is unpublished, you cannot currently migrate security data from a WebLogic security provider to a custom security provider, or visa versa. Additionally, security vendors wanting to exchange security data with security providers from other vendors will need to collaborate on a standard format to do so. |
Constraints are key/value pairs used to specify options to the export or import process. Constraints allow administrators to control which security data is exported or imported from the security provider's database. For example, an administrator may want to export only users (not groups) from an Authentication provider's database, or a subset of those users. Supported constraints are the list of constraints that administrators may specify during the migration process for a particular security provider. For example, an Authentication provider's database can be used to import users and groups, but not security policies.
Export files are the files to which security data is written (in the specified format) during the export portion of the migration process. Import files are the files from which security data is read (also in the specified format) during the import portion of the migration process. Both export and import files are simply temporary storage locations for security data as it is migrated from one security provider's database to another.
| Caution: | The migration files are not protected unless you take additional measures to protect them. Because migration files may contain sensitive data, take extra care when working with them. |
If you want to develop custom security providers that support security data migration like the WebLogic security providers do, you need to extend the weblogic.management.security.ImportMBean and weblogic.management.security.ExportMBean optional SSPI MBeans in the MBean Definition File (MDF) that you use to generate MBean types for your custom security providers, then implement their methods. These optional SSPI MBeans include the attributes and operations described in Table 3-6 and Table 3-7, respectively.
| Note: | For more information, see the WebLogic Server API Reference Javadoc for the ExportMBean interface. |
A parameter on the
importData operation that specifies the full path to the filename used to import provider-specific data.
|
|||
| Note: | For more information, see the WebLogic Server API Reference Javadoc for the ImportMBean interface. |
Unlike other optional SSPI MBeans you may extend in the MDF for your custom security providers, the attributes and operations inherited from the ExportMBean and ImportMBean optional SSPI MBeans automatically appear in a WebLogic Server Administration Console page for the associated security provider, under a Migration tab (see Figure 3-8 for an example). This allows administrators to export and import security data for each security provider individually.
| Notes: | If a security provider does not have migration capabilities, the Migration tab for that security provider will not appear in the Administration Console. For instructions about how to migrate security data for individual security providers using the Administration Console, see Migrating Security Data. |
Additionally, if any of the security providers configured in your security realm have migration capabilities, the Migration tab at the security realm level (see Figure 3-9 for an example) allows administrators to export or import security data for all the security providers configured in the security realm at once.
| Notes: | The Migration tab at the security realm level always appears in the Administration Console, whether or not any security providers with migration capabilities are configured in the security realm. However, it is only operational if one or more security providers have migration capabilities. For instructions about how to migrate security data for all security providers at once, see Migrating Security Data in Securing WebLogic Server. |
| Note: | Administrators can also use the WebLogic Scripting Tool (WLST) (rather than the Administration Console) to migrate security data when you extend the ExportMBean and ImportMBean optional SSPI MBeans. For more information, see
WebLogic Scripting Tool. |
As always, if you add additional attributes or operations to your MDF, you must write a console extension in order to make them available in the Administration Console.
The weblogic.management.utils package contains additional management interfaces and exceptions that developers might find useful, particularly when generating MBean types for their custom security providers. Implementation of these interfaces and exceptions is not required to develop a custom security provider (unless you inherit them by implementing optional SSPI MBeans in your custom security provider's MDF).
| Note: | The interfaces and classes are located in this package (rather than in weblogic.management.security) because they are general purpose utilities; in other words, these utilities can also be used for non-security MBeans. The various types of MBeans are described in
Overview of WebLogic Server Subsystem MBeans in Developing Custom Management Utilities with JMX. |
The weblogic.management.utils package contains the following utilities:
| Note: | The Manageable Sample Authentication Provider, one of the sample security providers available under
Code Samples: WebLogic Server on the dev2dev Web site, uses the weblogic.management.utils package for exceptions as well as to handle lists of data. |
For more information, see the WebLogic Server API Reference Javadoc for the weblogic.management.utils package.
A WebLogic resource is a structured object used to represent an underlying WebLogic Server entity that can be protected from unauthorized access. Developers of custom Authorization, Role Mapping, and Credential Mapping providers need to understand how these security providers interact with WebLogic resources and the security policies used to secure those resources.
| Note: | Security policies replace the access control lists (ACLs) and permissions that were used to protect WebLogic resources in previous releases of WebLogic Server. |
The following sections provide information about security providers and WebLogic resources:
| Note: | For more information, see Securing WebLogic Resources Using Roles and Policies. |
The Resource interface, located in the weblogic.security.spi package, provides the definition for an object that represents a WebLogic resource, which can be protected from unauthorized access. The ResourceBase class, located in the weblogic.security.service package, is an abstract base class for more specific WebLogic resource types, and facilitates the model for extending resources. (See Figure 3-10 and Types of WebLogic Resources for more information.)
The ResourceBase class includes the BEA-provided implementations of the getID, getKeys, getValues, and toString methods. For more information, see the WebLogic Server API Reference Javadoc for the
ResourceBase class.
This architecture allows you to develop security providers without requiring that they be aware of any particular WebLogic resources. Therefore, when new resource types are added, you should not need to modify the security providers.
As shown in Figure 3-10, certain classes in the weblogic.security.service package extend the ResourceBase class, and therefore provide you with implementations for specific types of WebLogic resources. WebLogic resource implementations are available for:
| Notes: | For more information about each of these WebLogic resources, see Securing WebLogic Resources Using Roles and Policies and the WebLogic Server API Reference Javadoc for the weblogic.security.service package. |
Each WebLogic resource (described in Types of WebLogic Resources) can identified in two ways: by its toString() representation or by an ID obtained using the getID() method.
If you use the toString() method of any WebLogic resource implementation, a description of the WebLogic resource will be returned in the form of a String. First, the type of the WebLogic resource is printed in pointy-brackets. Then, each key is printed, in order, along with its value. The keys are comma-separated. Values that are lists are comma-separated and delineated by open and close curly braces. Each value is printed as is, except that commas (,), open braces ({), close braces (}), and back slashes (\) are each escaped with a back slash. For example, the EJB resource:
EJBResource ("myApp",
"MyJarFile",
"myEJB",
"myMethod",
"Home",
new String[] {"argumentType1", "argumentType2"}
);
will produce the following toString output:
type=<ejb>, app=myApp, module="MyJarFile", ejb=myEJB, method="myMethod", methodInterface="Home", methodParams={argumentType1, argumentType2}
The format of the WebLogic resource description provided by the toString() method is public (that is, you can construct one without using a Resource object) and is reversible (meaning that you can convert the String form back to the original WebLogic resource).
| Note: | Listing 3-2 illustrates how to use the toString() method to identify a WebLogic resource. |
The getID() method on each of the defined WebLogic resource types returns a 64-bit hashcode that can be used to uniquely identify the WebLogic resource in a security provider. The resource ID can be effectively used for fast runtime caching, using the following algorithm:
| Note: | Listing 3-3 illustrates how to use the getID() method to identify a WebLogic resource in Authorization provider, and provides a sample implementation of this algorithm. |
Because it is not guaranteed stable across multiple runs, you should not use the resource ID to store information about the WebLogic resource in a security provider database. Instead, BEA recommends that you store any resource-to-security policy and resource-to-security role mappings in their corresponding security provider database using the WebLogic resource's toString() method.
| Notes: | For more information about security provider databases, see Initialization of the Security Provider Database. For more information about the toString method, see The toString() Method. |
When writing a runtime class for a custom Authentication provider, there are several default groups that you are required to create. Table 3-8 provides information to assist you with this task.
When writing a runtime class for a custom Role Mapping provider, there are several default global roles that you are required to create. Table 3-9 provides information to assist you with this task.
| Note: | For more information about global and scoped security roles, see Users, Groups, and Security Roles in Securing WebLogic Resources Using Roles and Policies. |
When writing a runtime class for a custom Authorization provider, there are several default security policies that you are required to create. These default security policies initially protect the various types of WebLogic resources. Table 3-10 provides information to assist you with this task.
| Note: | Application and COM resources should not have default security policies (that is, they should not grant permission to anyone by default). |
Listing 3-2 illustrates how to look up a WebLogic resource in the runtime class of an Authorization provider. This algorithm assumes that the security provider database for the Authorization provider contains a mapping of WebLogic resources to security policies. It is not required that you use the algorithm shown in Listing 3-2, or that you utilize the call to the getParentResource method. (For more information about the getParentResource method, see Single-Parent Resource Hierarchies.)
Policy findPolicy(Resource resource) {
Resource myResource = resource;
while (myResource != null) {
String resourceText = myResource.toString();
Policy policy = lookupInDB(resourceText);
if (policy != null) return policy;
myResource = myResource.getParentResource();
}
return null;
}
You can optimize the algorithm for looking up a WebLogic resource by using the getID method for the resource. (Use of the toString method alone, as shown in Listing 3-2, may impact performance due to the frequency of string concatenations.) The getID method may be quicker and more efficient because it is a hash operation that is calculated and cached within the WebLogic resource itself. Therefore, when the getID method is used, the toString value only needs to be calculated once per resource (as shown in Listing 3-3).
Policy findPolicy(Resource resource) {
Resource myResource = resource;
while (myResource != null) {
long id = myResource.getID();
Policy policy = lookupInCache(id);
if (policy != null) return policy;
String resourceText = myResource.toString();
Policy policy = lookupInDB(resourceText);
if (policy != null) {
addToCache(id, policy);
return policy;
}
myResource = myResource.getParentResource();
}
return null;
}| Note: | The getID method is not guaranteed between service packs or future WebLogic Server releases. Therefore, you should not store getID values in your security provider database. |
The level of granularity for WebLogic resources is up to you. For example, you can consider an entire Web application, a particular Enterprise JavaBean (EJB) within that Web application, or a single method within that EJB to be a WebLogic resource.
WebLogic resources are arranged in a hierarchical structure ranging from most specific to least specific. You can use the getParentResource method for each of the WebLogic resource types if you like, but it is not required.
The WebLogic security providers use the single-parent resource hierarchy as follows: If a WebLogic security provider attempts to access a specific WebLogic resource and that resource cannot be located, the WebLogic security provider will call the getParentResource method of that resource. The parent of the current WebLogic resource is returned, and allows the WebLogic security provider to move up the resource hierarchy to protect the next (less-specific) resource. For example, if a caller attempts to access the following URL resource:
type=<url>, application=myApp, contextPath="/mywebapp", uri=foo/bar/my.jsp
and that exact URL resource cannot be located, the WebLogic security provider will progressively attempt to locate and protect the following resources (in order):
type=<url>, application=myApp, contextPath="/mywebapp", uri=/foo/bar/*
type=<url>, application=myApp, contextPath="/mywebapp", uri=/foo/*
type=<url>, application=myApp, contextPath="/mywebapp", uri=*.jsp
type=<url>, application=myApp, contextPath="/mywebapp", uri=/*
type=<url>, application=myApp, contextPath="/mywebapp"
type=<url>, application=myApp
type=<app>, application=myApp
type=<url>| Note: | For more information about the getParentResource method, see the WebLogic Server API Reference Javadoc for any of the predefined WebLogic resource types or the
Resource interface. |
Sections SRV.11.1 and SRV.11.2 of the Java Servlet 2.3 Specification describe the servlet container's pattern matching rules. These rules are used for URL resources as well. The following examples illustrate some important concepts with regard to URL resource pattern matching.
For the URL resource type=<url>, application=myApp, contextPath=/mywebapp, uri=/foo/my.jsp, httpMethod=GET, the resource hierarchy used is as follows. (Note lines 3 and 4, which contain URL patterns that may be different from what is expected.)
type=<url>, application=myApp, contextPath=/mywebapp, uri=/foo/my.jsp, httpMethod=GETtype=<url>, application=myApp, contextPath=/mywebapp, uri=/foo/my.jsptype=<url>, application=myApp, contextPath=/mywebapp, uri=/foo/my.jsp/*, httpMethod=GETtype=<url>, application=myApp, contextPath=/mywebapp, uri=/foo/my.jsp/*type=<url>, application=myApp, contextPath=/mywebapp, uri=/foo/*, httpMethod=GETtype=<url>, application=myApp, contextPath=/mywebapp, uri=/foo/*type=<url>, application=myApp, contextPath=/mywebapp, uri=*.jsp, httpMethod=GETtype=<url>, application=myApp, contextPath=/mywebapp, uri=*.jsptype=<url>, application=myApp, contextPath=/mywebapp, uri=/*, httpMethod=GETtype=<url>, application=myApp, contextPath=/mywebapp, uri=/*type=<url>, application=myApp, contextPath=/mywebapptype=<url>, application=myApptype=<app>, application=myApptype=<url>
For the URL resource type=<url>, application=myApp, contextPath=/mywebapp, uri=/foo, the resource hierarchy used is as follows. (Note line 2, which contains a URL pattern that may be different from what is expected.)
type=<url>, application=myApp, contextPath=/mywebapp, uri=/footype=<url>, application=myApp, contextPath=/mywebapp, uri=/foo/*type=<url>, application=myApp, contextPath=/mywebapp, uri=/*type=<url>, application=myApp, contextPath=/mywebapptype=<url>, application=myApptype=<app>, application=myApptype=<url>
A ContextHandler is a high-performing WebLogic class that obtains additional context and container-specific information from the resource container, and provides that information to security providers making access or role mapping decisions. The ContextHandler interface provides a way for an internal WebLogic resource container to pass additional information to a WebLogic Security Framework call, so that a security provider can obtain contextual information beyond what is provided by the arguments to a particular method. A ContextHandler is essentially a name/value list and as such, it requires that a security provider know what names to look for. (In other words, use of a ContextHandler requires close cooperation between the WebLogic resource container and the security provider.) Each name/value pair in a ContextHandler is known as a context element, and is represented by a ContextElement object.
| Note: | For more information about the ContextHandler interface and ContextElement class, see the WebLogic Server API Reference Javadoc for the
weblogic.security.service package. |
Resource types have different context elements whose values you can inspect as part of developing a custom provider. That is, not all containers pass all context elements.
Table 3-11 lists the available ContextHandler entries.
The SSL framework has validated the certificate chain, meaning that the certificates in the chain have signed each other properly; the chain terminates in a certificate that is one of the server's trusted CAs; the chain honors the basic constraints rules; and the certificates in the chain have not expired.
|
|
Listing 3-4 illustrates how you can access HttpServletRequest and HttpServletResponse context element objects via a URL (Web) resource's ContextHandler. For example, you might use this code in the isAccessAllowed() method of your AccessDecision SSPI implementation. (For more information, see Implement the AccessDecision SSPI.)
static final String SERVLETREQUESTNAME = "com.bea.contextelement.servlet.HttpServletRequest";
if (resource instanceof URLResource) {
HttpServletRequest req =
(HttpServletRequest)handler.getValue(SERVLETREQUESTNAME);
}| Note: | You might also want to access these context elements in the getRoles() method of the RoleMapper SSPI implementation or the getContext() method of the AuditContext interface implementation. (For more information, see Implement the RoleMapper SSPI and Audit Context, respectively.) |
The ContextHandler interface provides a way to pass additional information to a WebLogic Security Framework call, so that a security provider or interface can obtain additional context information beyond what is provided by the arguments to a particular method.
Table 3-12 describes the context handler support.
An implementation of the AdjudicatorV2 SSPI interface is the part of an Adjudication provider that is called after all the Access Decisions'
isAccessAllowed methods have been called and returned successfully (that is, without throwing exceptions). The AdjudicatorV2 SSPI accepts the resource and ContextHandler as additional arguments. When the AuthorizationManager calls the Adjudicator, it passes the same resource and ContextHandler as it passed to AccessDecision. This allows the Adjudicator to have all of the information that is available to AccessDecision.
|
|
Because the JAAS
LoginModule.login() method and the IdentityAsserter.assertIdentity() method have access to the ContextHandler, the AuditAtnEventV2 interface also gets this data so it can audit relevant information. The getContext() method is inherited from weblogic.security.spi.AuditContext. The getContext() method gets a ContextHandler object from which additional audit information can be obtained.
|
|
The IdentityAsserterV2 provider allows the Security Framework to pass a ContextHandler in the assertIdentity method. The ContextHandler object can optionally be used to obtain additional information that may be used in asserting the identity. For example, the ContextHandler allows users to extract extra information from the HttpServletRequest and to set cookies in the HttpServletResponse.
|
|
A ContextHandler can be passed to the JAAS CallbackHandler parameter. A CallbackHandler is a variable-argument data structure that is passed to the login() method. Adding the ContextHandler in this manner allows users to extract extra information from the HttpServletRequest and to set cookies in the HttpServletResponse, for example. The implementation includes LoginModules used both for authentication and identity assertion.
The EJB and Servlet containers must add the ContextHandler to the CallbackHandler when calling the Principal Authenticator. Specifically, they must instantiate and pass a weblogic.security.auth.callback.ContextHandlerCallback to the invokeCallback method of a CallbackHandler to retrieve the ContextHandler related to this security operation. If no ContextHandler is associated with this operation, j
avax.security.auth.callback.UnsupportedCallbackException is thrown.
|
|
The
getRoles() method accepts a ContextHandler object that can optionally be used by the Role Mapping provider to obtain additional information that may be used in making the authorization decision. If the caller is unable to provide additional information, a null value should be specified.ation about the credential mapping audit event.
|
|
As of WebLogic Server version 9.0, the
weblogic.security.URLCallbackHandler and weblogic.security.SimpleCallbackHandler classes were updated to handle the ContextHandler.
|
| Note: | Prior to reviewing this section, be sure you have read Security Provider Databases in the Understanding WebLogic Security. |
At minimum, you must initialize security providers' databases with the default users, groups, security policies, security roles, or credentials that your Authentication, Authorization, Role Mapping, and Credential Mapping providers expect. You will need to initialize a given security provider's database before the security provider can be used, and should think about how this will work as you are writing the runtime classes for your custom security providers. The method you use to initialize a security provider's database depends upon many factors, including whether or not an externally administered database will be used to store the user, group, security policy, security role, or credential information, and whether or not the database already exists or needs to be created.
The following sections explain some best practices for initializing a security provider database:
The first time an Authentication, Authorization, Role Mapping, or Credential Mapping provider is used, it attempts to locate a database with the information it needs to provide its security service. If the security provider fails to locate the database, you can have it create one and automatically populate it with the default users, groups, security policies, security roles, and credentials. This option may be useful for development and testing purposes.
Both the WebLogic security providers and the sample security providers follow this practice. The WebLogic Authentication, Authorization, Role Mapping, and Credential Mapping providers store the user, group, security policy, security role, and credential information in the embedded LDAP server. If you want to use any of these WebLogic security providers, you will need to follow the Configuring the Embedded LDAP Server instructions in Securing WebLogic Server.
| Note: | The sample security providers, available under
Code Samples: WebLogic Server on the dev2dev Web site, simply create and use a properties file as their database. For example, the sample Authentication provider creates a file called SampleAuthenticatorDatabase.java that contains the necessary information about users and groups. |
If you already have a database (such as an external LDAP server), you can populate that database with the users, groups, security policies, security roles, and credentials that your Authentication, Authorization, Role Mapping, and Credential Mapping providers require. (Populating an existing database is accomplished using whatever tools you already have in place for performing these tasks.)
Once your database contains the necessary information, you must configure the security providers to look in that database. You accomplish this by adding custom attributes in your security provider's MBean Definition File (MDF). Some examples of custom attributes are the database's host, port, password, and so on. After you run the MDF through the WebLogic MBeanMaker and complete a few other steps to generate the MBean type for your custom security provider, you or an administrator use the WebLogic Server Administration Console to set these attributes to point to the database.
| Note: | For more information about MDFs, MBean types, and the WebLogic MBeanMaker, see Generating an MBean Type to Configure and Manage the Custom Security Provider. |
As an example, Listing 3-5 shows some custom attributes that are part of the WebLogic LDAP Authentication provider's MDF. These attributes enable an administrator to specify information about the WebLogic LDAP Authentication provider's database (an external LDAP server), so it can locate information about users and groups.
...
<MBeanAttribute
Name = "UserObjectClass"
Type = "java.lang.String"
Default = ""person""
Description = "The LDAP object class that stores users."
/>
<MBeanAttribute
Name = "UserNameAttribute"
Type = "java.lang.String"
Default = ""uid""
Description = "The attribute of an LDAP user object that specifies the name of
the user."
/>
<MBeanAttribute
Name = "UserDynamicGroupDNAttribute"
Type = "java.lang.String"
Description = "The attribute of an LDAP user object that specifies the
distinguished names (DNs) of dynamic groups to which this user belongs.
If such an attribute does not exist, WebLogic Server determines if a
user is a member of a group by evaluating the URLs on the dynamic group.
If a group contains other groups, WebLogic Server evaluates the URLs on
any of the descendents of the group."
/>
<MBeanAttribute
Name = "UserBaseDN"
Type = "java.lang.String"
Default = ""ou=people, o=example.com""
Description = "The base distinguished name (DN) of the tree in the LDAP directory
that contains users."
/>
<MBeanAttribute
Name = "UserSearchScope"
Type = "java.lang.String"
Default = ""subtree""
LegalValues = "subtree,onelevel"
Description = "Specifies how deep in the LDAP directory tree to search for Users.
Valid values are <code>subtree</code>
and <code>onelevel</code>."
/>
...
If possible, initialization calls between a security provider and the security provider's database should be done by an intermediary class, referred to as a database delegator. The database delegator should interact with the runtime class and the MBean type for the security provider, as shown in Figure 3-11.
A database delegator is used by the WebLogic Authentication and Credential Mapping providers. The WebLogic Authentication provider, for example, calls into a database delegator to initialize the embedded LDAP server with default users and groups, which it requires to provide authentication services for the default security realm.
Use of a database delegator is suggested as a convenience to application developers and security vendors who are developing custom security providers, because it hides the security provider's database and centralizes calls into the database.
A validator is an interface that is implemented by a class that can validate various types of expressions. In this release of WebLogic Server, the inheritance rules for security provider attribute validator methods differ from the rules that existed in 8.1.
In 8.1, a derived MBean had only to customize an attribute validator method in its MBean implementation file to make it take effect. As of version 9.0, the derived MBean must also explicitly declare the attribute validator in its MDF file to make it take effect. Otherwise, the customized method code is ignored.
Consider the following example of the base class of all identity assert MBean implementations, weblogic.management.security.authentication.IdentityAsserterImpl.
IdentityAsserterImpl extends the authentication provider MBean implementation and gives the authenticator's MBean implementation access to its configuration attributes.
In 8.1, you could do the following:
Therefore, the MBean inherits the activeTypes attribute, which has an attribute validator method. The validateActiveTypes(String[] activeTypes) method ensures that activeTypes includes only supported types).
As of version 9.0, the base IdentityAsserter's validateActiveTypes implementation is used instead. That is, IdentityAsserter1's validateActiveTypes implementation is silently ignored.
To work around this difference in version 9.0 and later, redeclare the attribute validator in IdentityAsserter1's MDF file in an MBeanOperation subelement.
The difference in inheritance rules for security provider attribute validators also applies to custom validators. You could have a provider declare an attribute with a custom validator. Then you could derive another provider from that one and write another implementation of the validator. In 8.1, the derived provider's validator would be used. As of version 9.0, the base provider's validator is used instead, and the derived one is silently ignored.
|