bea.com | products | dev2dev | support | askBEA |
|
e-docs > WebLogic Server > Developing Security Providers for WebLogic Server > Credential Mapping Providers |
Developing Security Providers for WebLogic Server |
Credential mapping is the process whereby a legacy system's database is used to obtain an appropriate set of credentials to authenticate users to a target resource. In WebLogic Server, a Credential Mapping provider is used to provide credential mapping services and bring new types of credentials into the WebLogic Server environment.
The following sections describe Credential Mapping provider concepts and functionality, and provide step-by-step instructions for developing a custom Credential Mapping provider:
A subject, or source of a WebLogic resource request, has security-related attributes called credentials. A credential may contain information used to authenticate the subject to new services. Such credentials include username/password combinations, Kerberos tickets, and public key certificates. Credentials might also contain data that allows a subject to perform certain activities. Cryptographic keys, for example, represent credentials that enable the subject to sign or encrypt data.
A credential map is a mapping of credentials used by WebLogic Server to credentials used in a legacy (or any remote) system, which tell WebLogic Server how to connect to a given resource in that system. In other words, credential maps allow WebLogic Server to log in to a remote system on behalf of a subject that has already been authenticated. You can map credentials in this way by developing a Credential Mapping provider.
The Credential Mapping Process
Figure 10-1 illustrates how Credential Mapping providers interact with the WebLogic Security Framework during the credential mapping process, and an explanation follows.
Figure 10-1 Credential Mapping Providers and the Credential Mapping Process
Generally, credential mapping is performed in the following manner:
The application component uses the credentials to access the external system. The external system might be a database resource, such as an Oracle or SQL Server.
Do You Need to Develop a Custom Credential Mapping Provider?
The default (that is, active) security realm for WebLogic Server includes a WebLogic Credential Mapping provider. The WebLogic Credential Mapping provider maps WebLogic Server users and groups to the appropriate username/password credentials that may be required by other, external systems. If the type of credential mapping you want is between WebLogic Server users and groups and username/password credentials in another system, then the WebLogic Credential Mapping provider is sufficient. However, if you want to map WebLogic Server users and groups to other types of credentials (for example, Kerberos tickets), then you need to develop a custom Credential Mapping provider.
How to Develop a Custom Credential Mapping Provider
If the WebLogic Credential Mapping provider does not meet your needs, you can develop a custom Credential Mapping provider by following these steps:
Create Runtime Classes Using the Appropriate SSPIs
Before you start creating runtime classes, you should first:
When you understand this information and have made your design decisions, create the runtime classes for your custom Credential Mapping provider by following these steps:
Note: At least one Credential Mapping provider in a security realm must implement the DeployableCredentialProvider SSPI, or else it will be impossible to deploy Resource Adapters.
Implement the CredentialProvider SSPI
To implement the CredentialProvider SSPI, provide implementations for the methods described in Understand the Purpose of the "Provider" SSPIs and the following method:
For more information about the CredentialProvider SSPI and the getCredentialProvider method, see the WebLogic Server 7.0 API Reference Javadoc.
Implement the DeployableCredentialProvider SSPI
To implement the DeployableCredentialProvider SSPI, provide implementations for the methods described in Understand the Purpose of the "Provider" SSPIs, Implement the CredentialProvider SSPI, and the following methods:
Note: The deployCredentialMapping/undeployCredentialMappings methods operate on username/password credentials only.
For more information about the DeployableCredentialProvider SSPI and the deployCredentialMapping/undeployCredentialMappings methods, see the WebLogic Server 7.0 API Reference Javadoc.
Implement the CredentialMapper SSPI
To implement the CredentialMapper SSPI, you must provide implementations for the following methods:
For more information about the CredentialMapper SSPI and the getCredentials methods, see the WebLogic Server 7.0 API Reference Javadoc.
Generate an MBean Type Using the WebLogic MBeanMaker
Before you start generating an MBean type for your custom security provider, you should first:
When you understand this information and have made your design decisions, create the MBean type for your custom Credential Mapping provider by following these steps:
Notes: Several sample security providers (available under "Code Direct" on the dev2dev Web site) illustrate how to perform these steps.
All instructions provided in this section assume that you are working in a Windows environment.
Create an MBean Definition File (MDF)
To create an MBean Definition File (MDF), follow these steps:
Note: A complete reference of MDF element syntax is available in MBean Definition File (MDF) Element Syntax.
Use the WebLogic MBeanMaker to Generate the MBean Type
Once you create your MDF, you are ready to run it through the WebLogic MBeanMaker. The WebLogic MBeanMaker is currently a command-line utility that takes as its input an MDF, and outputs some intermediate Java files, including an MBean interface, an MBean implementation, and an associated MBean information file. Together, these intermediate files form the MBean type for your custom security provider.
The instructions for generating an MBean type differ based on the design of your custom Credential Mapping provider. Follow the instructions that are appropriate to your situation:
No Optional SSPI MBeans and No Custom Operations
If the MDF for your custom Credential Mapping provider does not implement any optional SSPI MBeans and does not include any custom operations, follow these steps:
java -DMDF=xmlfile -DFiles=filesdir -DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker
where xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.
Whenever xmlfile is provided, a new set of output files is generated. If files already exist in the location specified by filesdir, you are informed that the existing files will be overwritten and are asked to confirm.
Each time you use the -DcreateStubs=true flag, it overwrites any existing MBean implementation file.
Optional SSPI MBeans or Custom Operations
If the MDF for your custom Credential Mapping provider does implement some optional SSPI MBeans or does include custom operations, consider the following:
java -DMDF=xmlfile -DFiles=filesdir -DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker
where xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.
Whenever xmlfile is provided, a new set of output files is generated. If files already exist in the location specified by filesdir, you are informed that the existing files will be overwritten and are asked to confirm.
Each time you use the -DcreateStubs=true flag, it overwrites any existing MBean implementation file.
The MBean implementation file generated by the WebLogic MBeanMaker is named MBeanNameImpl.java. For example, for the MDF named MyCredentialMapper, the MBean implementation file to be edited is named MyCredentialMapperImpl.java.
java -DMDF=xmlfile -DFiles=filesdir -DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker
where xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.
Whenever xmlfile is provided, a new set of output files is generated. If files already exist in the location specified by filesdir are informed that the existing files will be overwritten and are asked to confirm.
Each time you use the -DcreateStubs=true flag, it overwrites any existing MBean implementation file.
The MBean implementation file generated by the WebLogic MBeanMaker is named MBeanNameImpl.java. For example, for the MDF named SampleCredentialMapper, the MBean implementation file to be edited is named SampleCredentialMapperImpl.java.
Accomplishing this task may include, but is not limited to: copying the method implementations from your existing MBean implementation file into the newly-generated MBean implementation file (or, alternatively, adding the new methods from the newly-generated MBean implementation file to your existing MBean implementation file), and verifying that any changes to method signatures are reflected in the version of the MBean implementation file that you are going to use (for methods that exist in both MBean implementation files).
About the Generated MBean Interface File
The MBean interface file is the client-side API to the MBean that your runtime class or your MBean implementation will use to obtain configuration data. It is typically used in the initialize method as described in Understand the Purpose of the "Provider" SSPIs.
Because the WebLogic MBeanMaker generates MBean types from the MDF you created, the generated MBean interface file will have the name of the MDF, plus the text "MBean" appended to it. For example, the result of running the MyCredentialMapper MDF through the WebLogic MBeanMaker will yield an MBean interface file called MyCredentialMapperMBean.java.
Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF)
Once your have run your MDF through the WebLogic MBeanMaker to generate your intermediate files, and you have edited the MBean implementation file to supply implementations for the appropriate methods within it, you need to package the MBean files and the runtime classes for the custom Credential Mapping provider into an MBean JAR File (MJF). The WebLogic MBeanMaker also automates this process.
To create an MJF for your custom Credential Mapping provider, follow these steps:
java -DMJF=jarfile -DFiles=filesdir weblogic.management.commo.WebLogicMBeanMaker
where jarfile is the name for the MJF and filesdir is the location where the WebLogic MBeanMaker looks for the files to JAR into the MJF.
Compilation occurs at this point, so errors are possible. If jarfile is provided, and no errors occur, an MJF is created with the specified name.
Notes: If you want to update an existing MJF, simply delete the MJF and regenerate it. The WebLogic MBeanMaker also has a -DIncludeSource option, which controls whether source files are included into the resulting MJF. Source files include both the generated source and the MDF itself. The default is false. This option is ignored when -DMJF is not used.
The resulting MJF can be installed into your WebLogic Server environment, or distributed to your customers for installation into their WebLogic Server environments.
Install the MBean Type Into the WebLogic Server Environment
To install an MBean type into the WebLogic Server environment, copy the MJF into the WL_HOME\server\lib\mbeantypes directory, where WL_HOME is the top-level installation directory for WebLogic Server. This "deploys" your custom Credential Mapping provider—that is, it makes the custom Credential Mapping provider manageable from the WebLogic Server Administration Console.
You can create instances of the MBean type by configuring your custom Credential Mapping provider (see Configure the Custom Credential Mapping Provider Using the Administration Console), and then use those MBean instances from a GUI, from other Java code, or from APIs. For example, you can use the WebLogic Server Administration Console to get and set attributes and invoke operations, or you can develop other Java objects that instantiate MBeans and automatically respond to information that the MBeans supply. We recommend that you back up these MBean instances. For more information, see "Backing Up Security Configuration Data" under "Recovering Failed Servers" in Creating and Configuring WebLogic Server Domains.
Configure the Custom Credential Mapping Provider Using the Administration Console
Configuring a custom Credential Mapping provider means that you are adding the custom Credential Mapping provider to your security realm, where it can be accessed by applications requiring credential mapping services.
Configuring custom security providers is an administrative task, but it is a task that may also be performed by developers of custom security providers. This section contains information that is important for the person configuring your custom Credential Mapping providers:
Note: The steps for configuring a custom Credential Mapping provider using the WebLogic Server Administration Console are described under "Configuring a Custom Security Provider" in Managing WebLogic Security.
Managing Credential Mapping Providers, Resource Adapters, and Deployment Descriptors
Some application components, such as Resource Adapters and Web applications, store relevant deployment information in Java 2 Enterprise Edition (J2EE) deployment descriptors. For Resource Adapters, the deployment descriptor file (called weblogic-ra.xml) contains information such as username/password combinations that are used to create credential mappings. Typically, you will want to include this credential mapping information when first configuring your Credential Mapping provider in the WebLogic Server Administration Console.
The Administration Console provides an Ignore Security Data in Deployment Descriptors flag for this purpose, which you or an administrator should deselect the first time a custom Credential Mapping provider is configured. (To locate this flag, click Security
Listing 10-1 Sample weblogic-ra.xml File
<weblogic-connection-factory-dd>
<connection-factory-name>LogicalNameOfBlackBoxNoTx</connection-factory-name>
<jndi-name>eis/BlackBoxNoTxConnectorJNDINAME</jndi-name>
<map-config-property>
<map-config-property-name>ConnectionURL</map-config-property-name>
<map-config-property-value>jdbc:pointbase:server://localhost/demo
<map-config-property-value>
</map-config-property>
<security-principal-map>
<map-entry>
<initiating-principal>*</initiating-principal>
<resource-principal>
<resource-username>examples</resource-username>
<resource-password>examples</resource-password>
</resource-principal>
</map-entry>
</security-principal-map>
</weblogic-connection-factory-dd>
Note: The sample Resource Adapter deployment descriptor shown in Listing 10-1 is located in WL_HOME\samples\server\src\examples\jconnector\simple\rars\META-INF, where WL_HOME is the top-level installation directory for WebLogic Server.
While you can set additional credential mappings in deployment descriptors and in the Administration Console, BEA recommends that you copy the credential mappings defined in the Resource Adapter's deployment descriptor once, then use the Administration Console to define subsequent credential mappings. This is because any changes made to the credential mappings through the Administration Console during configuration of a Credential Mapping provider will not be persisted to the weblogic-ra.xml file. Before you deploy the application again (which will happen if you redeploy it through the Administration Console, modify it on disk, or restart WebLogic Server), you should select the Ignore Security Data in Deployment Descriptors flag. If you do not, the credential mappings defined using the Administration Console will be overwritten by those defined in the deployment descriptor.
Note: The Ignore Security Data in Deployment Descriptors flag also affects Role Mapping and Authorization providers. For more information, see Managing Authorization Providers and Deployment Descriptors and Managing Role Mapping Providers and Deployment Descriptors, respectively.
Enabling Deployable Credential Mappings
If you implemented the DeployableCredentialProvider SSPI and want to support deployable credential mappings with your custom Credential Mapping provider, the person configuring the custom Credential Mapping provider (that is, you or an administrator) must be sure that the Credential Mapping Deployment Enabled flag in the Administration Console is checked. Otherwise, deployment for the Credential Mapping provider is considered "turned off." Therefore, if multiple Credential Mapping providers are configured, the Credential Mapping Deployment Enabled flag can be used to control which Credential Mapping provider is used for credential mapping deployment.
The Credential Mapping Deployment Enabled flag performs the same function as the Ignore Security Data in Deployment Descriptors flag (described in Managing Credential Mapping Providers, Resource Adapters, and Deployment Descriptors), but is specific to Credential Mapping providers.
Note: If both the Credential Mapping Deployment Enabled flag and the Ignore Security Data in Deployment Descriptors flag are checked, the Ignore Security Data in Deployment Descriptors flag takes precedence. In other words, if the Ignore Security Data in Deployment Descriptors flag is checked, the Credential Mapping provider will not do deployment even if its Credential Mapping Deployment Enabled flag is checked.