Skip navigation.
Downloads | Product Documentation | Support

Developing Security Providers for WebLogic Server

# Credential Mapping Providers

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:

- Credential Mapping Concepts
- The Credential Mapping Process
- Do You Need to Develop a Custom Credential Mapping Provider?
- How to Develop a Custom Credential Mapping Provider

# Credential Mapping Concepts

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:

1. Application components, such as JavaServer Pages (JSPs), servlets, Enterprise JavaBeans (EJBs), or Resource Adapters call into the WebLogic Security Framework through the appropriate resource container. As part of the call, the application component passes in the subject (that is, the "who" making the request), the WebLogic resource (that is, the "what" that is being requested) and information about the type of credentials needed to access the WebLogic resource.
2. The WebLogic Security Framework sends the application component's request for credentials to a configured Credential Mapping provider that handles the type of credentials needed by the application component.
3. The Credential Mapping provider consults the legacy system's database to obtain a set of credentials that match those requested by the application component.
4. The Credential Mapping provider returns the credentials to the WebLogic Security Framework.
5. The WebLogic Security Framework passes the credentials back to the requesting application component through the resource container.

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:

1. Create Runtime Classes Using the Appropriate SSPIs
2. Generate an MBean Type Using the WebLogic MBeanMaker
3. Configure the Custom Credential Mapping Provider Using the Administration Console
4. Provide a Mechanism for Credential Map Management

## Create Runtime Classes Using the Appropriate SSPIs

Before you start creating runtime classes, you should first:

- Understand the Purpose of the Provider SSPIs
- Determine Which Provider Interface You Will Implement
- Understand the SSPI Hierarchy and Determine Whether You Will Create One or Two Runtime Classes

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:

- Implement the CredentialProvider SSPI or Implement the DeployableCredentialProvider SSPI
- Implement the CredentialMapper SSPI

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:

  getCredentialProvider

  `public CredentialMapper getCredentialProvider();`

  The `getCredentialProvider` method obtains the implementation of the `CredentialMapper` SSPI. For a single runtime class called `MyCredentialMapperProviderImpl`.`java` (as in Figure 2-3), the implementation of the `getCredentialProvider` method would be:

  `return this;`

  If there are two runtime classes, then the implementation of the `getCredentialProvider` method could be:

  `return new MyCredentialMapperImpl;`

  This is because the runtime class that implements the `CredentialProvider` SSPI is used as a factory to obtain classes that implement the `CredentialMapper` SSPI.

For more information about the `CredentialProvider` SSPI and the `getCredentialProvider` method, see the WebLogic Server 8.1 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:

  deployCredentialMapping

  `public void deployCredentialMapping(Resource resource, String initiatingPrincipal, String eisUsername, String eisPassword)throws ResourceCreationException;`

  The `deployCredentialMapping` method deploys credential maps (that is, creates a credential mapping on behalf of a deployed Resource Adapter in a database). If the mapping already exists, it is removed and replaced by this mapping. The `resource` parameter represents the WebLogic resource to which the initiating principal (represented as a `String`) is requesting access. The Enterprise Information System (EIS) username and password are the credentials in the legacy (remote) system to which the credential maps are being made.

  undeployCredentialMappings

  `public void undeployCredentialMappings(Resource resource) throws ResourceRemovalException;`

  The `undeployCredentialMappings` method undeploys credential maps (that is, deletes a credential mapping on behalf of an undeployed Resource Adapter from a database). The `resource` parameter represents the WebLogic resource for which the mapping should be removed.

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 8.1 API Reference Javadoc.

### Implement the CredentialMapper SSPI

To implement the `CredentialMapper` SSPI, you must provide implementations for the following methods:

  getCredentials

  `public java.util.Vector getCredentials(Subject requestor, Subject initiator, Resource resource, String[] credentialTypes);`

  The `getCredentials` method obtains the appropriate set of credentials for the target resource, based on the identity of the subject. This version of the method returns a list of matching credentials for all of the principals within the subject (as a vector) by consulting the remote system's database.

  getCredentials

  `public java.lang.Object getCredentials(Subject requestor, String initiator, Resource resource, String[] credentialTypes);`

  The `getCredentials` method obtains the appropriate set of credentials for the target resource, based on the identity of the subject. This version of the method returns one credential for the specified subject (as an object) by consulting the remote system's database.

For more information about the `CredentialMapper` SSPI and the `getCredentials` methods, see the WebLogic Server 8.1 API Reference Javadoc.

#### Developing Custom Credential Mapping Providers That Are Compatible With the Realm Adapter Authentication Provider

An Authentication provider is the security provider responsible for populating a subject with users and groups, which are then extracted from the subject by other types of security providers, including Credential Mapping providers. If the Authentication provider configured in your security realm is a Realm Adapter Authentication provider, the user and group information will be stored in the subject in a way that is slightly different from other Authentication providers. Therefore, this user and group information must also be extracted in a slightly different way.

Listing 10-1 provides code that can be used by custom Credential Mapping providers to check whether a subject matches a user or group name when a Realm Adapter Authentication provider was used to populate the subject. This code belongs in whatever form of the `getCredentials` method you choose to implement.

Listing 10-1 Sample Code to Check if a Subject Matches a User or Group Name

>     /**
>      * Determines if the Subject matches a user/group name.
>      *
>      * @param principalWant A String containing the name of a principal in this role
>      * (that is, the role definition).
>      *
>      * @param subject A Subject that contains the Principals that identify the user
>      * who is trying to access the resource as well as the user's groups.
>      *
>      * @return A boolean. true if the current subject matches the name of the
>      * principal in the role, false otherwise.
>      */
>     private boolean subjectMatches(String principalWant, Subject subject)
>     {
>        // first, see if it's a group name match
>        if (SubjectUtils.isUserInGroup(subject, principalWant)) {
>           return true;
>        }
>        // second, see if it's a user name match
>        if (principalWant.equals(SubjectUtils.getUsername(subject))) {
>           return true;
>        }
>        // didn't match
>        return false;
>     }

## Generate an MBean Type Using the WebLogic MBeanMaker

Before you start generating an MBean type for your custom security provider, you should first:

- 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

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:

1. Create an MBean Definition File (MDF)
2. Use the WebLogic MBeanMaker to Generate the MBean Type
3. Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF)
4. Install the MBean Type Into the WebLogic Server Environment

Notes: Several sample security providers (available under Code Samples: WebLogic Server on the dev2dev Web site) illustrate how to perform these steps.

All instructions provided in this section assume that you are working in a Windows environment.

### Create an MBean Definition File (MDF)

To create an MBean Definition File (MDF), follow these steps:

1. Copy the MDF for the sample Authentication provider to a text file.

Note: The MDF for the sample Authentication provider is called `SampleAuthenticator.xml`. (There is currently no sample Credential Mapping provider.)

2. Modify the content of the `<MBeanType>` and `<MBeanAttribute>` elements in your MDF so that they are appropriate for your custom Credential Mapping provider.
3. Add any custom attributes and operations (that is, additional `<MBeanAttribute>` and `<MBeanOperation>` elements) to your MDF.
4. Save the file.

Note: A complete reference of MDF element syntax is available in MBean Definition File (MDF) Element Syntax.

### Use the WebLogic MBeanMaker to Generate the MBean Type

Once you create your MDF, you are ready to run it through the WebLogic MBeanMaker. The WebLogic MBeanMaker is currently a command-line utility that takes as its input an MDF, and outputs some intermediate Java files, including an MBean interface, an MBean implementation, and an associated MBean information file. Together, these intermediate files form the MBean type for your custom security provider.

The instructions for generating an MBean type differ based on the design of your custom Credential Mapping provider. Follow the instructions that are appropriate to your situation:

- No Optional SSPI MBeans and No Custom Operations
- Optional SSPI MBeans or Custom Operations

#### 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:

1. Create a new DOS shell. You must have the following in your classpath:

- `WL_HOME\server\lib\weblogic.jar`
- `WL_HOME\server\lib\mbeantypes\wlManagement.jar`
- `JAVA_HOME\..\lib\tools.jar`
- The filedir that you specify in the `-Dfiles` flag

1. Type the following command:

`java -DMDF=`xmlfile`-Dfiles=`filesdir`-DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker`

where the `-DMDF` flag indicates that the WebLogic MBeanMaker should translate the MDF into code, xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.

Copy `WL_HOME\server\lib\commo.dtd` to the same directory as the xml file specified by the `-DMDF` flag.

Whenever xmlfile is provided, a new set of output files is generated.

Each time you use the `-DcreateStubs=true` flag, it overwrites any existing MBean implementation file.

Note: The WebLogic MBeanMaker processes one MDF at a time. Therefore, you may have to repeat this process if you have multiple MDFs (in other words, multiple Credential Mapping providers).

2. Proceed to Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF).

#### Optional SSPI MBeans or Custom Operations

If the MDF for your custom Credential Mapping provider does implement some optional SSPI MBeans or does include custom operations, consider the following:

- Are you creating an MBean type for the first time? If so, follow these steps:

1. Create a new DOS shell. You must have the following in your classpath:

- `WL_HOME\server\lib\weblogic.jar`
- `WL_HOME\server\lib\mbeantypes\wlManagement.jar`
- `JAVA_HOME\..\lib\tools.jar`
- The filedir that you specify in the `-Dfiles` flag

1. Type the following command:

`java -DMDF=`xmlfile`-Dfiles=`filesdir`-DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker`

where the `-DMDF` flag indicates that the WebLogic MBeanMaker should translate the MDF into code, xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.

Copy `WL_HOME\server\lib\commo.dtd` to the same directory as the xml file specified by the `-DMDF` flag.

Whenever xmlfile is provided, a new set of output files is generated.

Each time you use the `-DcreateStubs=true` flag, it overwrites any existing MBean implementation file.

Note: The WebLogic MBeanMaker processes one MDF at a time. Therefore, you may have to repeat this process if you have multiple MDFs (in other words, multiple Credential Mapping providers).

2. If you implemented optional SSPI MBeans in your MDF, follow these steps:

1. Locate the MBean implementation file.

The MBean implementation file generated by the WebLogic MBeanMaker is named MBeanName `Impl.java`. For example, for the MDF named `MyCredentialMapper`, the MBean implementation file to be edited is named `MyCredentialMapperImpl.java`.

2. For each optional SSPI MBean that you implemented in your MDF, copy the method stubs from the Mapping MDF Operation Declarations to Java Method Signatures Document (available on the dev2dev Web site) into the MBean implementation file, and implement each method. Be sure to also provide implementations for any methods that the optional SSPI MBean inherits.

3. If you included any custom operations in your MDF, implement the methods using the method stubs.
4. Save the file.
5. Proceed to Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF).

- Are you updating an existing MBean type? If so, follow these steps:

1. Copy your existing MBean implementation file to a temporary directory so that your current method implementations are not overwritten by the WebLogic MBeanMaker.
2. Create a new DOS shell. You must have the following in your classpath:

- `WL_HOME\server\lib\weblogic.jar`
- `WL_HOME\server\lib\mbeantypes\wlManagement.jar`
- `JAVA_HOME\..\lib\tools.jar`
- The filedir that you specify in the `-Dfiles` flag

1. Type the following command:

`java -DMDF=`xmlfile`-Dfiles=`filesdir`-DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker`

where the `-DMDF` flag indicates that the WebLogic MBeanMaker should translate the MDF into code, xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.

Copy `WL_HOME\server\lib\commo.dtd` to the same directory as the xml file specified by the `-DMDF` flag.

Whenever xmlfile is provided, a new set of output files is generated.

Each time you use the `-DcreateStubs=true` flag, it overwrites any existing MBean implementation file.

Note: The WebLogic MBeanMaker processes one MDF at a time. Therefore, you may have to repeat this process if you have multiple MDFs (in other words, multiple Credential Mapping providers).

2. If you implemented optional SSPI MBeans in your MDF, follow these steps:

1. Locate the MBean implementation file.

The MBean implementation file generated by the WebLogic MBeanMaker is named MBeanName `Impl.java`. For example, for the MDF named `SampleCredentialMapper`, the MBean implementation file to be edited is named `SampleCredentialMapperImpl.java`.

2. Open your existing MBean implementation file (which you saved to a temporary directory in step 1).
3. Synchronize the existing MBean implementation file with the MBean implementation file generated by the WebLogic MBeanMaker.

Accomplishing this task may include, but is not limited to: copying the method implementations from your existing MBean implementation file into the newly-generated MBean implementation file (or, alternatively, adding the new methods from the newly-generated MBean implementation file to your existing MBean implementation file), and verifying that any changes to method signatures are reflected in the version of the MBean implementation file that you are going to use (for methods that exist in both MBean implementation files).

4. If you modified the MDF to implement optional SSPI MBeans that were not in the original MDF, copy the method stubs from the Mapping MDF Operation Declarations to Java Method Signatures Document (available on the dev2dev Web site) into the MBean implementation file, and implement each method. Be sure to also provide implementations for any methods that the optional SSPI MBean inherits.

3. If you modified the MDF to include any custom operations that were not in the original MDF, implement the methods using the method stubs.
4. Save the version of the MBean implementation file that is complete (that is, has all methods implemented).
5. Copy this MBean implementation file into the directory where the WebLogic MBeanMaker placed the intermediate files for the MBean type. You specified this as filesdir in step 3. (You will be overriding the MBean implementation file generated by the WebLogic MBeanMaker as a result of step 3.)
6. Proceed to Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF).

#### About the Generated MBean Interface File

The MBean interface file is the client-side API to the MBean that your runtime class or your MBean implementation will use to obtain configuration data. It is typically used in the initialize method as described in Understand the Purpose of the Provider SSPIs.

Because the WebLogic MBeanMaker generates MBean types from the MDF you created, the generated MBean interface file will have the name of the MDF, plus the text "MBean" appended to it. For example, the result of running the `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:

1. Create a new DOS shell. You must have the following in your classpath:

- `WL_HOME\server\lib\weblogic.jar`
- `WL_HOME\server\lib\mbeantypes\wlManagement.jar`
- `JAVA_HOME\..\lib\tools.jar`
- The filedir that you specify in the `-Dfiles` flag

1. Type the following command:

`java -DMJF=`jarfile`-Dfiles=`filesdir `weblogic.management.commo.WebLogicMBeanMaker`

where the `-DMJF` flag indicates that the WebLogic MBeanMaker should build a JAR file containing the new MBean types, jarfile is the name for the MJF and filesdir is the location where the WebLogic MBeanMaker looks for the files to JAR into the MJF.

Compilation occurs at this point, so errors are possible. If jarfile is provided, and no errors occur, an MJF is created with the specified name.

Notes: 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.

Note: WL_HOME`\server\lib\mbeantypes` is the default directory for installing MBean types. However, if you want WebLogic Server to look for MBean types in additional directories, use the `-Dweblogic.alternateTypesDirectory=`<dir> command-line flag when starting your server, where <dir> is a comma-separated list of directory names. When you use this flag, WebLogic Server will always load MBean types from WL_HOME`\server\lib\mbeantypes` first, then will look in the additional directories and load all valid archives present in those directories (regardless of their extension). For example, if `-Dweblogic.alternateTypesDirectory = dirX,dirY`, WebLogic Server will first load MBean types from WL_HOME`\server\lib\mbeantypes`, then any valid archives present in `dirX` and `dirY`. If you instruct WebLogic Server to look in additional directories for MBean types and are using the Java Security Manager, you must also update the `weblogic.policy` file to grant appropriate permissions for the MBean type (and thus, the custom security provider). For more information, see Using the Java Security Manager to Protect WebLogic Resources in Programming WebLogic Security.

You can create instances of the MBean type by configuring your custom 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 Configuration and Security Data under "Recovering Failed Servers" in Configuring and Managing WebLogic Server.

## 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:

- Managing Credential Mapping Providers, Resource Adapters, and Deployment Descriptors
- Enabling Deployable Credential Mappings

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 (Connectors), store relevant deployment information in Java 2 Enterprise Edition (J2EE) and WebLogic Server 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 maps. Typically, you will want to include this credential map information when first configuring your Credential Mapping providers in the WebLogic Server Administration Console.

The Administration Console provides an Ignore Deploy Credential Mapping checkbox for this purpose, which you or an administrator should be sure is unchecked the first time a custom Credential Mapping provider is configured.

Notes: The Ignore Deploy Credential Mapping checkbox is unchecked by default. To locate the On Ignore Deploy Credential Mapping checkbox, click Security —> Realms —> realm in the left pane of the Administration Console, where realm is the name of your security realm. Then select the General tab.

When the Ignore Deploy Credential Mapping checkbox is unchecked and a Resource Adapter (Connector) is deployed, WebLogic Server reads credential maps from the `weblogic-ra.xml` deployment descriptor file, an example of which is shown in Listing 10-2. This information is then copied into the security provider database for the Credential Mapping provider

Listing 10-2 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-2 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 maps in deployment descriptors and in the Administration Console, BEA recommends that you copy the credential maps defined in the Resource Adapter's deployment descriptor once, then use the Administration Console to define subsequent credential maps. This is because any changes made to the credential maps 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 Resource Adapter (Connector) again (which will happen if you redeploy it through the Administration Console, modify it on disk, or restart WebLogic Server), you should check the Ignore Deploy Credential Mapping checkbox. If you do not, the credential maps defined using the Administration Console will be overwritten by those defined in the deployment descriptor.

### Enabling Deployable Credential Mappings

If you implemented the `DeployableCredentialProvider` SSPI as part of developing your custom Credential Mapping provider and want to support deployable credential maps, the person configuring the custom Credential Mapping provider (that is, you or an administrator) must be sure that the Credential Mapping Deployment Enabled check box 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 check box can be used to control which Credential Mapping provider is used for credential map deployment.

Note: The Ignore Deploy Credential Mapping checkbox (specified at the security realm level and described in Managing Credential Mapping Providers, Resource Adapters, and Deployment Descriptors) determines whether you want credential maps to be copied into the security databases for the configured Credential Mapping providers. The Credential Mapping Deployment Enabled check box (specified for each configured Credential Mapping provider) determines whether or not the Credential Mapping provider is the one that stores the deployed credential maps.

## Provide a Mechanism for Credential Map Management

While configuring a custom Credential Mapping provider via the WebLogic Server Administration Console makes it accessible by applications requiring credential mapping services, you also need to supply administrators with a way to manage this security provider's associated credential maps. The WebLogic Credential Mapping provider, for example, supplies administrators with a Credential Mappings page (see Figure 10-2) that allows them to add, modify, or remove credential mappings for various Connector modules by right-clicking on the Connector Module and selecting the Define Credential Mappings... option.

Figure 10-2 WebLogic Credential Mapping Provider's Credential Mappings Page

Neither the Credential Mapping page nor access to it is available to administrators when you develop a custom Credential Mapping provider. Therefore, you must provide your own mechanism for credential map management. This mechanism must read and write credential maps to and from the custom Credential Mapping provider's database.

You can accomplish this task in one of three ways:

- Option 1: Create Your Own "Credential Mappings" Page Using Console Extensions
- Option 2: Develop a Stand-Alone Tool for Credential Map Management
- Option 3: Integrate an Existing Credential Map Management Tool into the Administration Console

### Option 1: Create Your Own "Credential Mappings" Page Using Console Extensions

The main benefit of creating console extensions for your custom Credential Mapping provider is that you automatically know the ID for the WebLogic resource and therefore, the WebLogic resource's location in the resource hierarchy. (This information is required to read and write expressions to and from the Credential Mapping provider's database.) An additional benefit is that your page can be integrated into the existing WebLogic Server Administration Console GUI, like the Credential Mapping page provided with the WebLogic Credential Mapping provider.

If you selected this option, you need to:

1. Implement the `getExtensionForUserPasswordCredential()` and `getExtentionForUserPasswordCredentialMapping()` methods of the `weblogic.management.console.extensibility.SecurityExtensionV2` interface.

The implementation of the `getExtensionForUserPasswordCredential()` method should return a page that defines the resource ID/ remote user to remote user password mapping. The implementation of the `getExtentionForUserPasswordCredentialMapping()` method should return the page that defines the WebLogic resource ID/WebLogic user to remote user mapping.

Note: For more information, see Writing Console Extensions for Custom Security Providers.

2. In addition, you must do one of the following:

1. Implement the `UserPasswordCredentialMapEditor` and `UserPasswordCredentialMapReader` optional Credential Mapping SSPI MBeans to develop a management MBean that will act as an intermediary between your Credential Mappings page and the Credential Mapping provider's database. For more information, see Determine Which SSPI MBeans to Extend and Implement and Table 2-5.

In this case, you also need to determine how to represent the local-to-remote user relationship as a string. You can do this by developing a syntax for the relationship (like the expressions that make up security roles and security policies), or store it in a relational database or LDAP directory.

Note: The way you store the local-to-remote user relationship can be different for different Credential Mapping providers.

2. Develop your own MBean APIs for managing credential maps, and implement those interfaces to develop a management MBean that will act as an intermediary between your Credential Mappings page and the Credential Mapping provider's database.
3. Read and write expressions from and to the custom Credential Mapping provider's database directly, without delegating to an MBean.

### Option 2: Develop a Stand-Alone Tool for Credential Map Management

You would typically select this option if you want to develop a tool that is entirely separate from the WebLogic Server Administration Console.

For this option, you do not need to write any console extensions for your custom Credential Mapping provider, nor do you need to develop any management MBeans as described in Option 1: Create Your Own "Credential Mappings" Page Using Console Extensions. However, your tool needs to:

1. Determine the WebLogic resource's ID, since it is not automatically provided to you by the console extension. For more information, see WebLogic Resource Identifiers.
2. Determine how to represent the represent the local-to-remote user relationship. (This representation is entirely up to you and need not be a string as in Option 1: Create Your Own "Credential Mappings" Page Using Console Extensions.)
3. Read and write the expressions from and to the custom Credential Mapping provider's database.

### Option 3: Integrate an Existing Credential Map Management Tool into the Administration Console

You would typically select this option if you have a tool that is separate from the WebLogic Server Administration Console, but you want to launch that tool from the Administration Console.

For this option, your tool needs to:

1. Determine the WebLogic resource's ID. For more information, see WebLogic Resource Identifiers.
2. Determine how to represent the represent the local-to-remote user relationship. (This representation is entirely up to you and need not be a string as in Option 1: Create Your Own "Credential Mappings" Page Using Console Extensions.)
3. Read and write the expressions from and to the custom Credential Mapping provider's database.
4. Link into the Administration Console using basic console extension techniques, as described in Extending the Administration Console.