3 Design Considerations

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:

• General Architecture of a Security Provider

• Security Services Provider Interfaces (SSPIs)

• Security Service Provider Interface (SSPI) MBeans

• Security Data Migration

• Management Utilities Available to Developers of Security Providers

• Security Providers and WebLogic Resources

• Initialization of the Security Provider Database

• Differences In Attribute Validators

General Architecture of a Security Provider

Although there are different types of security providers you can create (see "Types of Security Providers" in Understanding Security for Oracle WebLogic Server), all security providers follow the same general architecture. Figure 3-1 illustrates the general architecture of a security provider, and an explanation follows.

Figure 3-1 Security Provider Architecture

Description of "Figure 3-1 Security Provider Architecture"

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.

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:

1. Locates the MBean type associated with the security provider in the security realm.

2. Obtains the name of the security provider's runtime class (the one that implements the "Provider" SSPI, if there are two runtime classes) from the MBean type.

3. Passes in the appropriate MBean instance, which the security provider uses to initialize (read configuration data).

Therefore, both the runtime class (or classes) and the MBean type form what is called the "security provider."

Security Services Provider Interfaces (SSPIs)

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:

• Understand Two Important Restrictions

• Understand the Purpose of the "Provider" SSPIs

• Understand the Purpose of the Bulk Access Providers

• Determine Which "Provider" Interface You Will Implement

• Understand the SSPI Hierarchy and Determine Whether You Will Create One or Two Runtime Classes

Additionally, this section provides SSPI Quick Reference that indicates which SSPIs can be implemented for each type of security provider.

Understand Two Important Restrictions

Security providers must adhere to the following restrictions:

• A custom security provider's runtime class implementation must not contain any code that requires a security check to be performed by the WebLogic Security Framework. Doing so causes infinite recursion, because the security providers are the components of the WebLogic Security Framework that actually perform the security checks and grant access to WebLogic resources.

• No local (where local refers to the same server, cluster, or domain) Java Platform, Enterprise Edition (Java EE) Version 5 services are available for use within a security provider's implementation. Any attempt to use them is unsupported. For example, this prohibits calling an EJB in the current domain from your security provider.

  Java EE services in other domains are accessible and can be used within a security provider.

Understand the Purpose of the "Provider" SSPIs

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

Figure 3-2 "Provider" SSPIs

Description of "Figure 3-2 "Provider" SSPIs"

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

  public void initialize(ProviderMBean providerMBean, SecurityServices securityServices) 
  

  The 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 Chapter 10, "Auditing Providers" and Chapter 12, "Auditing Events From Custom Security Providers."

• getDescription

  public String getDescription()
  

  This method returns a brief textual description of the custom security provider.

• shutdown

  public void shutdown()
  

  This method shuts down the custom security provider.

Because they extend SecurityProvider, a runtime class that implements any SSPI ending in "Provider" must provide implementations for these inherited methods.

Understand the Purpose of the Bulk Access Providers

This release of WebLogic Server includes bulk access versions of the following Authorization, Adjudication, and Role Mapping provider SSPI interfaces:

• BulkAuthorizationProvider

• BulkAccessDecision

• BulkAdjudicationProvider

• BulkAdjudicator

• BulkRoleProvider

• BulkRoleMapper

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.

Determine Which "Provider" Interface You Will Implement

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.

The DeployableAuthorizationProviderV2 SSPI

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 Resources Using Roles and Policies for Oracle WebLogic Server.

The DeployableRoleProviderV2 SSPI

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 Resources Using Roles and Policies for Oracle WebLogic Server.

The DeployableCredentialProvider SSPI

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.

Note:

For more information about credentials, see Credential Mapping Concepts. For more information about security policies, see "Security Policies" in Securing Resources Using Roles and Policies for Oracle WebLogic Server.

Understand the SSPI Hierarchy and Determine Whether You Will Create One or Two Runtime Classes

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, Oracle 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.

Figure 3-3 Credential Mapping SSPIs and a Single Runtime Class

Description of "Figure 3-3 Credential Mapping SSPIs and a Single Runtime Class"

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.

Figure 3-4 Credential Mapping SSPIs and Two Runtime Classes

Description of "Figure 3-4 Credential Mapping SSPIs and Two Runtime Classes"

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.

SSPI Quick Reference

Table 3-1 maps the types of security providers (and their components) with the SSPIs and other interfaces you use to develop them.

Table 3-1 Security Providers, Their Components, and Corresponding SSPIs

Type/Component	SSPIs/Interfaces
Authentication provider	AuthenticationProviderV2
LoginModule (JAAS)	LoginModule
Identity Assertion provider	AuthenticationProviderV2
Identity Asserter	IdentityAsserterV2
Principal Validation provider	PrincipalValidator
Authorization	AuthorizationProvider DeployableAuthorizationProviderV2
Access Decision	AccessDecision
Adjudication provider	AdjudicationProviderV2
Adjudicator	AdjudicatorV2
Role Mapping provider	RoleProvider DeployableRoleProviderV2
Role Mapper	RoleMapper
Auditing provider	AuditProvider
Audit Channel	AuditChannel
Credential Mapping provider	CredentialProviderV2
Credential Mapper	CredentialMapperV2
Cert Path Provider	CertPathProvider
Versionable Application Provider	VersionableApplicationProvider

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.

Security Service Provider Interface (SSPI) MBeans

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:

• Understand Why You Need an MBean Type

• Determine Which SSPI MBeans to Extend and Implement

• Understand the Basic Elements of an MBean Definition File (MDF)

• Understand the SSPI MBean Hierarchy and How It Affects the Administration Console

• Understand What the WebLogic MBeanMaker Provides

Additionally, this section provides 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.

Understand Why You Need an MBean Type

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 that defines a standard management architecture, APIs, and management services. See "Understanding JMX" in Developing Manageable Applications With JMX for Oracle WebLogic Server.

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

Determine Which SSPI MBeans to Extend and Implement

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:

• Required SSPI MBeans, which you must extend because they define the basic methods that allow a security provider to be configured and managed within the WebLogic Server environment.

• Optional SSPI MBeans, which you can implement because they define additional methods for managing security providers. Different types of security providers are able to use different optional SSPI MBeans.

For more information, see SSPI MBean Quick Reference.

Understand the Basic Elements of an MBean Definition File (MDF)

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.

Example 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 Appendix A, "MBean Definition File (MDF) Element Syntax."

Example 3-1 DefaultCredentialMapper.xml

<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.&lt;p&gt;"
>
<MBeanAttribute
 Name = "ProviderClassName"
 Type = "java.lang.String"
 Writeable = "false"
 Default = "&quot;weblogic.security.providers.credentials. DefaultCredentialMapperProviderImpl&quot;"
 Description = "The name of the Java class that loads the WebLogic Credential Mapping 
provider."
/>
<MBeanAttribute
 Name = "Description"
 Type = "java.lang.String"
 Writeable = "false"
 Default = "&quot;Provider that performs Default Credential Mapping&quot;"
 Description = "A short description of the WebLogic Credential Mapping provider."
/>
<MBeanAttribute
 Name = "Version"
 Type = "java.lang.String"
 Writeable = "false"
 Default = "&quot;1.0&quot;"
 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 Example 3-1 is DefaultCredentialMapperProviderImpl.java.

While not shown in Example 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 at https://codesamples.samplecode.oracle.com/servlets/tracking?id=S224 on the Oracle Technology Network Web site) provides an example of adding a custom attribute.

Custom Providers and Classpaths

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.

Throwing Exceptions from MBean Operations

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.

• For typed exceptions, you must throw only the exact types from the throw clause of your MBean's method, as opposed to deriving and throwing your own exception type from that type.

• For nested exceptions, you must throw only JDK exception types or weblogic.management.utils exceptions.

• For runtime exceptions, you must throw or pass through only JDK exceptions.

Specifying Non-Clear Text Values for MBean Attributes

As described in Table A-1, 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     = "&quot;&quot;"
Description = "The Keystore password."
/>

Understand the SSPI MBean Hierarchy and How It Affects the Administration Console

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.

Figure 3-5 SSPI MBean Hierarchy for Credential Mapping Providers

Description of "Figure 3-5 SSPI MBean Hierarchy for Credential Mapping Providers"

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

Figure 3-6 DefaultCredentialMapper Administration Console Page

Description of "Figure 3-6 DefaultCredentialMapper Administration Console Page"

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.

Understand What the WebLogic MBeanMaker Provides

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:

• Any attributes inherited from required SSPI MBeans—as well as any custom attributes you added to the MDF—cause the WebLogic MBeanMaker to generate complete getter/setter methods in the MBean type's information file. (The MBean information file is not shown in Figure 3-7.) For more information about the MBean information file, see About the MBean Information File.

  Necessary developer action: None. No further work must be done for these methods.

• Any operations inherited from optional SSPI MBeans cause the MBean implementation file to inherit their methods, whose implementations you must supply from scratch.

  Necessary developer action: Currently, the WebLogic MBeanMaker does not generate method stubs for these inherited methods, so you will need to supply the appropriate implementations.

• Any custom operations you added to the MDF will cause the WebLogic MBeanMaker to generate method stubs.

  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.

Figure 3-7 What the WebLogic MBeanMaker Provides

Description of "Figure 3-7 What the WebLogic MBeanMaker Provides"

About the MBean Information File

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:

MBean + tags
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.

SSPI MBean Quick Reference

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.

Table 3-2 Required SSPI MBeans

Type	Package Name	Required SSPI MBean
Authentication provider	authentication	Authenticator
Identity Assertion provider	authentication	IdentityAsserter
Authorization provider	authorization	Authorizer or DeployableAuthorizer
Adjudication provider	authorization	Adjudicator
Role Mapping provider	authorization	RoleMapper or DeployableRoleMapper
Auditing provider	audit	Auditor
Credential Mapping provider	credentials	CredentialMapper or DeployableCredentialMapper
Cert Path Provider	pk	CertPathBuilder or CertPathValidator

Note:

The required SSPI MBeans shown in Table 3-2 are located in the weblogic.management.security.<Package_Name> package.

Table 3-3 Optional Authentication SSPI MBeans

Optional SSPI MBeans	Purpose
GroupEditor	Create a group. If the group already exists, an exception is thrown.
GroupMemberLister	List a group's members.
GroupReader	Read data about groups.
GroupRemover	Remove groups.
MemberGroupLister	List the groups containing a user or a group.
UserEditor	Create, edit and remove users.
UserPasswordEditor	Change a user's password.
UserReader	Read data about users.
UserRemover	Remove users.

Note:

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.

For an example of how to implement the optional Authentication SSPI MBeans shown in Table 3-4, review the code for the Manageable Sample Authentication Provider (available at https://codesamples.samplecode.oracle.com/servlets/tracking?id=S224 on the Oracle Technology Network Web site).

Table 3-4 Optional Authorization SSPI MBeans

Optional SSPI MBeans	Purpose
PolicyConsumer	Indicates that the provider supports policy consumption.
PolicyEditor	Create, edit and remove security policies.
PolicyLister	List data about policies.
PolicyReader	Read data about security policies.
PolicyStore	Manages policies in a policy store.
RoleEditor	Create, edit and remove security roles.
RoleReader	Read data about security roles.
RoleLister	List data about roles.

Note:

The optional Authorization SSPI MBeans shown in Table 3-4 are located in the weblogic.management.security.authorization package.

Table 3-5 Optional Credential Mapping SSPI MBeans

Optional SSPI MBeans	Purpose
UserPasswordCredentialMapEditor	Edit credential maps that map a WebLogic user to a remote username and password.
UserPasswordCredentialMapExtendedReader	Read credential maps that map a WebLogic user to a remote username and password.
UserPasswordCredentialMapReader	Read credential maps that map a WebLogic user to a remote username and password.

Note:

The optional Credential Mapping SSPI MBeans shown in Table 3-5 are located in the weblogic.management.security.credentials package.

Security Data Migration

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:

• Transitioning from development mode to production mode

• Proliferating production mode security configurations to security realms in new WebLogic Server domains

• Moving data to a new security realm in the same WebLogic Server domain or in a different WebLogic Server domain.

• Moving from one security realm to a new security realm in the same WebLogic Server domain, where one or more of the WebLogic security providers will be replaced with custom security providers. (In this case, administrators need to copy security data for the security providers that are not being replaced.)

The following sections provide more information about security data migration:

• Migration Concepts

• Adding Migration Support to Your Custom Security Providers

• Administration Console Support for Security Data Migration

Migration Concepts

Before you start to work with security data migration, you need to understand the following concepts:

• Formats

• Constraints

• Migration Files

Formats

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.

Note:

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

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.

Migration Files

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.

Adding Migration Support to Your Custom Security Providers

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.

Table 3-6 Attributes and Operations of the ExportMBean Optional SSPI MBean

Attributes/Operations	Description
SupportedExportFormats	A list of export data formats that the security provider supports.
SupportedExportConstraints	A list of export constraints that the security provider supports.
exportData	Exports provider-specific security data in a specified format.
format	A parameter on the exportData operation that specifies the format to use for exporting provider-specific data.
filename	A parameter on the exportData operation that specifies the full path to the filename used to export provider-specific data. Notes: The WebLogic security providers that support security data migration are implemented in a way that allows you to specify a relative path (from the directory relative to the server you are working on). You must specify a directory that already exists; WebLogic Server will not create one for you.
constraints	A parameter on the exportData operation that specifies the constraints to be used when exporting provider-specific data.

Note:

For more information, see the WebLogic Server API Reference Javadoc for the ExportMBean interface.

Table 3-7 Attributes and Operations of the ImportMBean Optional SSPI MBean

Attributes/Operations	Description
SupportedImportFormats	A list of import data formats that the security provider supports.
SupportedImportConstraints	A list of import constraints that the security provider supports.
importData	Imports provider-specific data from a specified format.
format	A parameter on the importData operation that specifies the format to use for importing provider-specific data.
filename	A parameter on the importData operation that specifies the full path to the filename used to import provider-specific data. Note: The WebLogic security providers that support security data migration are implemented in a way that allows you to specify a relative path (from the directory relative to the server you are working on). You must specify a directory that already exists; WebLogic Server will not create one for you.
constraints	A parameter on the importData operation that specifies the constraints to be used when importing provider-specific data.

Note:

For more information, see the WebLogic Server API Reference Javadoc for the ImportMBean interface.

Administration Console Support for Security Data Migration

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.

Note:

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" in Securing Oracle WebLogic Server.

Figure 3-8 Migration Tab for the WebLogic Authentication Provider

Description of "Figure 3-8 Migration Tab for the WebLogic Authentication Provider"

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.

Note:

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 Oracle WebLogic Server.

Figure 3-9 Migration Tab for a Security Realm

Description of "Figure 3-9 Migration Tab for a Security Realm"

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

Management Utilities Available to Developers of Security Providers

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 for Oracle WebLogic Server.

The weblogic.management.utils package contains the following utilities:

• Common exceptions.

• Interfaces that provide methods for handling large lists of data.

• An interface containing configuration attributes that are required to communicate with an external LDAP server.

  Note:

  The Manageable Sample Authentication provider (available at https://codesamples.samplecode.oracle.com/servlets/tracking?id=S224 on the Oracle Technology Network 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.

Security Providers and WebLogic Resources

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:

• The Architecture of WebLogic Resources

• Types of WebLogic Resources

• WebLogic Resource Identifiers

• Creating Default Groups for WebLogic Resources

• Creating Default Security Roles for WebLogic Resources

• Creating Default Security Policies for WebLogic Resources

• Single-Parent Resource Hierarchies

• ContextHandlers and WebLogic Resources

  Note:

  For more information, see Securing Resources Using Roles and Policies for Oracle WebLogic Server.

The Architecture of WebLogic Resources

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

Figure 3-10 Architecture of WebLogic Resources

Description of "Figure 3-10 Architecture of WebLogic Resources"

The ResourceBase class includes the Oracle-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.

Types of WebLogic Resources

As shown in Figure 3-10, "Architecture of WebLogic Resources", 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:

• Administrative resources

• Application resources

• COM resources

• Control resources

• EIS resources

• EJB resources

• JDBC resources

• JMS resources

• JNDI resources

• Remote resources

• Server resources

• URL resources

• Web service resources

• Work Context resources

  Note:

  For more information about each of these WebLogic resources, see Securing Resources Using Roles and Policies for Oracle WebLogic Server and the WebLogic Server API Reference Javadoc for the weblogic.security.service package.

WebLogic Resource Identifiers

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.

The toString() 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:

Example 3-2 illustrates how to use the toString() method to identify a WebLogic resource.

Resource IDs and the getID() Method

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:

1. Obtain a WebLogic resource.

2. Get the resource ID for the WebLogic resource using the getID method.

3. Look up the resource ID in the cache.

4. If the resource ID is found, then return the security policy.

5. If the resource ID is not found, then:

   1. Use the toString() method to look up the WebLogic resource in the security provider database.

   2. Store the resource ID and the security policy in cache.

   3. Return the security policy.

      Note:

      Example 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, Oracle 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.

Note:

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.

Creating Default Groups for WebLogic Resources

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.

Table 3-8 Default Groups and Group Membership

Group Name	Group Membership
Administrators	Empty, or an administrative user.
Deployers	Empty
Monitors	Empty
Operators	Empty
AppTesters	Empty
OracleSystemGroup	OracleSystemUser

Creating Default Security Roles for WebLogic Resources

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.

Table 3-9 Default Global Roles and Group Associations

Global Role Name	Group Association
Admin	Administrators group
AdminChannelUser	AdminChannelUsers, Administrators, Deployers, Operators, Monitors, and AppTesters groups
Anonymous	weblogic.security.WLSPrincipals.getEveryoneGroupname() group
CrossDomainConnector	CrossDomainConnectors group
Deployer	Deployers group
Monitor	Monitors group
Operator	Operators group
AppTester	AppTesters group
OracleSystemRole	OracleSystemGroup

Note:

For more information about global and scoped security roles, see "Users, Groups, and Security Roles" in Securing Resources Using Roles and Policies for Oracle WebLogic Server.

Creating Default Security Policies for WebLogic Resources

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.

Table 3-10 Default Security Policies for WebLogic Resources

WebLogic Resource Constructor	Security Policy
new AdminResource(null, null, null)	Admin global role
new AdminResource("Configuration", null, null)	Admin, Deployer, Monitor, or Operator global roles
new AdminResource('FileDownload", null, null)	Admin or Deployer global role
new AdminResource('FileUpload", null, null)	Admin or Deployer global role
New AdminResource('ViewLog", null, null)	Admin or Deployer global role
new ControlResource(null, null, null)	weblogic.security.WLSPrincipals.getEveryoneGroupname() group
new EISResource(null, null, null)	weblogic.security.WLSPrincipals.getEveryoneGroupname() group
new EJBResource(null, null, null, null, null, null)	weblogic.security.WLSPrincipals.getEveryoneGroupname() group
new JDBCResource(null, null, null, null, null)	weblogic.security.WLSPrincipals.getEveryoneGroupname() group
new JNDIResource(null, null, null)	weblogic.security.WLSPrincipals.getEveryoneGroupname() group
new JMSResource(null, null, null, null)	weblogic.security.WLSPrincipals.getEveryoneGroupname() group
new ServerResource(null, null, null)	Admin or Operator global roles
new URLResource(null, null, null, null, null)	weblogic.security.WLSPrincipals.getEveryoneGroupname() group
new WebServiceResource(null, null, null, null)	weblogic.security.WLSPrincipals.getEveryoneGroupname() group
new WorkContext(null, null)	weblogic.security.WLSPrincipals.getEveryoneGroupname() group

Note:

Application and COM resources should not have default security policies (that is, they should not grant permission to anyone by default).

Looking Up WebLogic Resources in a Security Provider's Runtime Class

Example 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 Example 3-2, or that you utilize the call to the getParentResource method. (For more information about the getParentResource method, see Single-Parent Resource Hierarchies.)

Example 3-2 How to Look Up a WebLogic Resource in an Authorization Provider: Using the toString Method

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

Example 3-3 How to Look Up a WebLogic Resource in an Authorization Provider: Using the getID Method

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 patch sets or future WebLogic Server releases. Therefore, you should not store getID values in your security provider database.

Single-Parent Resource Hierarchies

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.

Pattern Matching for URL Resources

Sections SRV.11.1 and SRV.11.2 of the Java Servlet 2.3 Specification (http://jcp.org/aboutJava/communityprocess/first/jsr053/index.html) 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.

Example 1

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

1. type=<url>, application=myApp, contextPath=/mywebapp, uri=/foo/my.jsp, httpMethod=GET

2. type=<url>, application=myApp, contextPath=/mywebapp, uri=/foo/my.jsp

3. type=<url>, application=myApp, contextPath=/mywebapp, uri=/foo/my.jsp/*, httpMethod=GET

4. type=<url>, application=myApp, contextPath=/mywebapp, uri=/foo/my.jsp/*

5. type=<url>, application=myApp, contextPath=/mywebapp, uri=/foo/*, httpMethod=GET

6. type=<url>, application=myApp, contextPath=/mywebapp, uri=/foo/*

7. type=<url>, application=myApp, contextPath=/mywebapp, uri=*.jsp, httpMethod=GET

8. type=<url>, application=myApp, contextPath=/mywebapp, uri=*.jsp

9. type=<url>, application=myApp, contextPath=/mywebapp, uri=/*, httpMethod=GET

10. type=<url>, application=myApp, contextPath=/mywebapp, uri=/*

11. type=<url>, application=myApp, contextPath=/mywebapptype=<url>, application=myApp

12. type=<app>, application=myApp

13. type=<url>

Example 2

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

1. type=<url>, application=myApp, contextPath=/mywebapp, uri=/foo

2. type=<url>, application=myApp, contextPath=/mywebapp, uri=/foo/*

3. type=<url>, application=myApp, contextPath=/mywebapp, uri=/*

4. type=<url>, application=myApp, contextPath=/mywebapp

5. type=<url>, application=myApp

6. type=<app>, application=myApp

7. type=<url>

ContextHandlers and WebLogic Resources

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.

Table 3-11 Context Handler Entries

Context Element Name	Description and Type
com.bea.contextelement. servlet.HttpServletRequest	A servlet access request or SOAP message via HTTP javax.http.servlet.HttpServletRequest
com.bea.contextelement. servlet.HttpServletResponse	A servlet access response or SOAP message via HTTP javax.http.servlet.HttpServletResponse
com.bea.contextelement. wli.Message	A WebLogic Integration message. The message is streamed to the audit log. java.io.InputStream
com.bea.contextelement. channel.Port	The internal listen port of the network channel accepting or processing the request java.lang.Integer
com.bea.contextelement. channel.PublicPort	The external listen port of the network channel accepting or processing the request java.lang.Integer
com.bea.contextelement. channel.RemotePort	The port of the remote end of the TCP/IP connection of the network channel accepting or processing the request java.lang.Integer
com.bea.contextelement. channel.Protocol	The protocol used to make the request of the network channel accepting or processing the request java.lang.String
com.bea.contextelement. channel.Address	The internal listen address of the network channel accepting or processing the request java.lang.String
com.bea.contextelement. channel.PublicAddress	The external listen address of the network channel accepting or processing the request java.lang.String
com.bea.contextelement. channel.RemoteAddress	The remote address of the TCP/IP connection of the network channel accepting or processing the request java.lang.String
com.bea.contextelement. channel.ChannelName	The name of the network channel accepting or processing the request java.lang.String
com.bea.contextelement. channel.Secure	Is the network channel accepting or processing the request using SSL? java.lang.Boolean
com.bea.contextelement. ejb20.Parameter[1-N]	Object based on parameter
com.bea.contextelement. wsee.SOAPMessage	javax.xml.rpc.handler.MessageContext
com.bea.contextelement. entitlement.EAuxiliaryID	Used by WebLogic Server internal process. weblogic.entitlement.expression.EAuxiliary
com.bea.contextelement. security.ChainPrevalidatedBySSL	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. java.lang.Boolean
com.bea.contextelement. xml.SecurityToken	Not used in this release of WebLogic Server. weblogic.xml.crypto.wss.provider.SecurityToken
com.bea.contextelement. xml.SecurityTokenAssertion	Not used in this release of WebLogic Server. java.util.Map
com.bea.contextelement. webservice.Integrity{id:XXXXX}	javax.security.auth.Subject
com.bea.contextelement. saml.SSLClientCertificateChain	The SSL client certificate chain obtained from the SSL connection over which a sender-vouches SAML assertion was received. java.security.cert.X509Certificate[]
com.bea.contextelement. saml.MessageSignerCertificate	The certificate used to sign a Web service message. java.security.cert.X509Certificate
com.bea.contextelement. saml.subject.ConfirmationMethod	The type of SAML assertion: bearer, artifact, sender-vouches, or holder-of-key. java.lang.String
com.bea.contextelement. saml.subject.dom.KeyInfo	The <ds:KeyInfo> element to be used for subject confirmation with holder-of-key SAML assertions. org.w3c.dom.Element

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

Example 3-4 Example: Accessing Context Elements in the URL Resource ContextHandler

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

Providers and Interfaces that Support Context Handlers

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.

Table 3-12 Methods and Classes that Support Context Handlers

Method	Description
AccessDecision.isAccessAllowed()	The isAccessAllowed() method accepts a ContextHandler object that can optionally be used by an Access Decision 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.
AdjudicatorV2.adjudicate()	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.
AuditAtnEventV2.getContext()	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.
AuditCertPathBuilderEvent.getContext(), AuditCertPathValidatorEvent.getContext()	The getContext method gets an optional ContextHandler object that may specify additional data on how to look up and validate the CertPath.
AuditConfigurationEvent.getContext()	The AuditConfigurationEvent.getContext() method gets a ContextHandler object from which additional audit information can be obtained.
AuditContext.getContext()	The AuditContext.getContext() method gets a ContextHandler object from which additional audit information can be obtained.
AuditCredentialMappingEvent.getContext()	The getContext method gets an optional ContextHandler object that may specify additional information about the credential mapping audit event.
CertPathBuilderParameterSpi.getContext and CertPathValidatorParameterSpi.getContext	The CertPathBuilderParameterSpi and CertPathValidatorParameterSpi interfaces include a getContext() method to get a ContextHandler that may pass in extra parameters that can be used for building and validating the Cert Path.
ChallengeIdentityAsserterV2.assertChallengeIdentity(), ChallengeIdentityAsserterV2.continueChallengeIdentity(), and ChallengeIdentityAsserterV2.getChallengeIdentity()	The ChallengeIdentityAsserterV2 methods accept a ContextHandler object that can optionally be user by the Identity assertion provider to obtain additional information that may be used in asserting the challenge identity.
CredentialMapperV2.getCredentials()	The CredentialMapper.getCredentials() and CredentialMapper.getCredential() methods include a ContextHandler parameter with optional extra data.
IdentityAsserterV2.assertIdentity()	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.
LoginModule.login()	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, javax.security.auth.callback.UnsupportedCallbackException is thrown.
RoleMapper.getRoles()	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.
URLCallbackHandler and SimpleCallbackHandler Classes	As of WebLogic Server version 9.0, the weblogic.security.URLCallbackHandler and weblogic.security.SimpleCallbackHandler classes were updated to handle the ContextHandler. URLCallbackHandler is a CallbackHandler used by application developers for returning a username, password, URL, and ContextHandler as part of the Authenticate API. SimpleCallbackHandler is a simple CallbackHandler used by application developers for returning a username, password and ContextHandler as part of the Authenticate API.

Initialization of the Security Provider Database

Note:

Prior to reviewing this section, be sure you have read "Security Provider Databases" in the Understanding Security for Oracle WebLogic Server.

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:

• Best Practice: Create a Simple Database If None Exists

• Best Practice: Configure an Existing Database

• Best Practice: Delegate Database Initialization

• Best Practice: Use the JDBC Connection Security Service API to Obtain Database Connections

Best Practice: Create a Simple Database If None Exists

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 Oracle WebLogic Server.

Note:

The sample security providers (available at https://codesamples.samplecode.oracle.com/servlets/tracking?id=S224 on the Oracle Technology Network 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.

Best Practice: Configure an Existing Database

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, Example 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.

Example 3-5 LDAPAuthenticator.xml

...
<MBeanAttribute
 Name = "UserObjectClass"
 Type = "java.lang.String"
 Default = "&quot;person&quot;"
 Description = "The LDAP object class that stores users."
/>
<MBeanAttribute
 Name = "UserNameAttribute"
 Type = "java.lang.String"
 Default = "&quot;uid&quot;"
 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 = "&quot;ou=people, o=example.com&quot;"
 Description = "The base distinguished name (DN) of the tree in the LDAP directory
   that contains users."
/>
<MBeanAttribute
 Name = "UserSearchScope"
 Type = "java.lang.String"
 Default = "&quot;subtree&quot;"
 LegalValues = "subtree,onelevel"
 Description = "Specifies how deep in the LDAP directory tree to search for Users.
   Valid values are &lt;code&gt;subtree&lt;/code&gt;
   and &lt;code&gt;onelevel&lt;/code&gt;."
/>
...

Best Practice: Delegate Database Initialization

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.

Figure 3-11 Positioning of the Database Delegator Class

Description of "Figure 3-11 Positioning of the Database Delegator Class"

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.

Best Practice: Use the JDBC Connection Security Service API to Obtain Database Connections

As an alternative to the best practices for creating or configuring a database for your custom security provider, you can use the JDBCConnectionService SSPI only during provider initialization to access the JDBC data sources that are configured for your WebLogic domain.

This capability enables your custom security providers to take advantage of full database access and database connection management capabilities provided through JDBC data sources, including multi data sources. See https://download.oracle.com/javase/1.5.0/docs/api/java/sql/Connection.html for information about how SQL statements are executed and how the results are returned within the context of a connection.

When you use the JDBCConnectionService SSPI, note the following:

• Obtain the JDBCConnectionService in the initialize() method of your custom provider.

• Data sources are identified by name (sqlConnectionName), not JNDI path.

• During initialization, JDBC resources may not be available. Direct connections are returned until the JNDI and JDBC subsystems are fully initialized and available.

• When finished with the database connection returned by the JDBC data source, the security provider must invoke the releaseConnection method (and specify the Connection object) to release the connection.

Example 3-6 shows using the JDBCConnectionService SSPI to obtain a database connection from a named JDBC data source.

Although not shown in the example, JDBCConnectionService.getConnection can throw JDBCConnectionServiceException if the named JDBC data source is unavailable, or SQLException if the database connection is unavailable. JDBCConnectionService.releaseConnection can throw SQLException if the database connection is unavailable.

Example 3-6 Using the JDBCConnectionService API to Access JDBC Data Sources

JDBCConnectionService dbService = null;
if (services instanceof SecurityServicesJDBC) {
   try {

     dbService = ((SecurityServicesJDBC)services).getJDBCConnectionService();

     System.out.println("Obtained the JDBCConnectionService, " + dbService);

     Connection conn = dbService.getConnection("oracle-database");

     PreparedStatement statement = conn.prepareStatement("select sysdate from dual");
     ResultSet rs= statement.executeQuery(); 

     while (rs.next()) {
       String s1 = rs.getString(1);  
       System.out.println("Sys date =" + s1);
     }

     dbService.releaseConnection(conn);
   } catch(Exception e) {
     e.printStackTrace();
   }

Implementing a JDBC Connection Security Service: Main Steps

To implement a security service for obtaining access to JDBC data sources:

1. In your provider's initialize() method, invoke the getJDBCConnectionService method of the SecurityServicesJDBC interface to obtain the JDBC connection service.

2. Invoke the getConnection method on the JDBC connection service instance, passing the name of a JDBC data source that is configured in your WebLogic domain.

3. Add appropriate database commands, such as prepared statements, queries, and so on.

4. You must invoke the releaseConnection method on the JDBC connection service instance to release the connection instance.

Differences In Attribute Validators

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:

1. Write an Identity Asserter provider called IdentityAsserter1. In its MDF file, indicate that it extends weblogic.management.security.authentication.IdentityAsserter.

2. Use the WebLogic MBeanMaker to generate the MBean type. The implementation file created by the MBeanMaker, typically named IdentityAsserter1Impl.java, extends weblogic.management.security.authentication.IdentityAsserterImpl.

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

3. Modify the implementation file and specify a different implementation for the validateActiveTypes method. For example, it could further restrict the active types or loosen the rules.

4. In 8.1, IdentityAsserter1's validateActiveTypes implementation is used.

   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.

Differences In Attribute Validators for Custom Validators

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.