Skip navigation.
Downloads | Product Documentation | Support

Managing WebLogic Security

# Single Sign-On with Enterprise Information Systems

This section explains how to create credential maps that allow Enterprise Information System (EIS) users to access protected WebLogic Resources.

- Overview
- Using Deployment Descriptors to Create Credential Maps (Deprecated)
- Using the WebLogic Administration Console to Create Credential Maps

Note: This chapter applies to WebLogic Server deployments using the security features in this release of WebLogic Server as well as deployments using Compatibility Security.

# Overview

Single sign-on allows user information to be propagated from an EIS to WebLogic Server so that users are not required to authenticate themselves multiple times as they access WebLogic Server resources. Resource adapters defined by the J2EE Connector Architecture can acquire the credentials necessary to authenticate users defined in an EIS when they request access to a protected WebLogic resource. The container in WebLogic Server that hosts resource adapters can retrieve the appropriate set of credentials for the WebLogic resource using a credential map. A credential map creates an association between a user in WebLogic Server security realm and an identity (a username and password combination) used to authenticate that user in an EIS such as an Oracle database, a SQL server, or a SAP application.

Creating a credential map is a two-step process:

1. Create a WebLogic Server user or group for the EIS user. The user or group needs to be defined in the configured Authentication provider. Multiple WebLogic Server users or groups can be mapped to the same remote user or group. For more efficient management, BEA recommends using groups to create credential maps.
2. Create a credential map for the EIS users. Use the username and password under which the user is authenticated to the EIS or the group in which the EIS user is a member to define the user. These credential maps are stored in the embedded LDAP server.

For more information using security in resource adapters, see the Security topic in Programming WebLogic J2EE Connectors.

WebLogic Server provides two techniques for creating credential maps: deployment descriptors (deprecated) and the WebLogic Server Administration Console. The following sections describe both techniques.

# Using Deployment Descriptors to Create Credential Maps (Deprecated)

Credentials maps can be specified in the <`security-principal-map>` element of the `weblogic-ra.xml` deployment descriptor file. The <`security-principal-map>` element provides the association between the credentials used to log in to the EIS and credentials used to authenticate to WebLogic resources. The deployment descriptor technique for creating credential maps is deprecated in this release of WebLogic Server. Instead, use the WebLogic Server Administration Console to create credential maps. For more information, see Using the WebLogic Administration Console to Create Credential Maps.

If you deployed a resource adapter that has a `weblogic-ra.xml` deployment descriptor file containing a defined `<security-principal-map>` element, BEA recommends importing the data into the embedded LDAP server and where it can be used by the WebLogic Credential Mapping provider.

## Importing Information from weblogic-ra.xml into the Embedded LDAP Server

To import the information from the `weblogic-ra.xml` deployment descriptor file into the embedded LDAP server, enable the Credential Mapping Deployment Enabled attribute on the Credential Mapping provider in the default (active) security realm. When the resource adapter is deployed, the credential map information is loaded into the Credential Mapping provider.

In order to support the Credential Mapping Deployment Enabled attribute, a Credential Mapping provider must implement the DeployableCredentialProvider SSPI. By default, the WebLogic Credential Mapping provider has this attribute enabled. Therefore, information from a `weblogic-ra.xml` deployment descriptor file is automatically loaded into the WebLogic Credential Mapping provider when the resource adapter is deployed.

It is important to understand that once information from a `weblogic-ra.xml` deployment descriptor file is loaded into the embedded LDAP server, the original resource adapter remains unchanged. Therefore, if you redeploy the original resource adapter (which will happen if you redeploy it through the WebLogic Server Administration Console, modify it on disk, or restart WebLogic Server), the data will once again be imported from the `weblogic-ra.xml` deployment descriptor file and credential mapping information may be lost.

## Avoiding Overwriting of Credential Mapping Information

To avoid overwriting new credential mapping information with old information in a `weblogic-ra.xml` deployment descriptor file, enable the Ignore Security Data in Deployment Descriptors attribute:

1. Expand the Security-->Realms nodes.

All security realms available for the WebLogic domain are listed in the Realms table.

2. Select the name of the realm you are using.
3. Select the General tab.
4. Check the Ignore Deploy Credential Mapping attribute. This attribute specifies that the Credential Mapping providers in the security realm will use only credential maps created using the WebLogic Server Administration Console. By default, this attribute is not checked meaning the Credential Mapping provider will load credential maps specified in a `weblogic-ra.xml` deployment descriptor file.
5. Click Apply.
6. Reboot WebLogic Server.

After performing the preceeding procedure, BEA Systems recommends modifying the `weblogic-ra.xml` deployment descriptor file to remove the `<security-principal-map>` element.

# Using the WebLogic Administration Console to Create Credential Maps

You can now use the WebLogic Server Administration Console to create credential maps. If you are using the WebLogic Credential Mapping provider, the credential maps are stored in the embedded LDAP server.

To create a credential map:

1. Verify the Ignore Deploy Credential Mapping attribute is enabled on the default (active) security realm. Otherwise, you risk overwriting credential maps with old information in `weblogic-ra.xml` deployment descriptor files. For more information, see Setting a New Security Realm as the Default (Active) Security Realm.
2. Define a user or group for the EIS user. For more information, see Users and Groups in Securing WebLogic Resources.
3. Deploy a resource adapter. For more information, see Programming WebLogic J2EE Connectors.
4. In the left pane of the WebLogic Server Administration Console, expand Deployments-->Connector Modules nodes.
5. Right-click the name of the Connector for which you want to create a credential map, and select Define Credential Mappings... to display the Credential Mappings page.

If available, a table of currently defined credential maps appears in the right pane.

6. Click the Configure a New Credential Mapping... link.

If multiple WebLogic Credential Mapping providers are configured in the security realm, select which WebLogic Credential Mapping provider's database should store information for the new credential map.

7. Enter the WebLogic Server user or group name you defined for the EIS user in step 2 in the WLS User field.
8. Enter the name of the EIS user in the Remote User field.
9. Click Apply to save your changes.

The EIS user appears in the Credential Maps table.

10. Click the name of the EIS user in the Remote User column of the Credential Maps table.
11. Enter the password for the EIS user in the Remote Password field.
12. Confirm the password.
13. Click Apply.