11 Credential Mapping Providers

This chapter describes credential mapping provider concepts and functionality, and provides step-by-step instructions for developing a custom credential mapping provider in WebLogic Server 12.1.3.

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.

This chapter includes the following sections:

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 11-1 illustrates how credential mapping providers interact with the WebLogic Security Framework during the credential mapping process, and an explanation follows.

Figure 11-1 Credential Mapping Providers and the Credential Mapping Process

Description of Figure 11-1 follows
Description of "Figure 11-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. It is up to the credential mapper to decide whether it supports the token or not. If it supports the token, it performs its processing.

  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.

WebLogic Server includes a PKI Credential Mapping provider. The PKI (Public Key Infrastructure) Credential Mapping provider included in WebLogic Server maps a WebLogic Server subject (the initiator) and target resource (and an optional credential action) to a key pair or public certificate that should be used by the application when using the targeted resource. The PKI Credential Mapping provider uses the subject and resource name to retrieve the corresponding credential from the keystore. The PKI Credential Mapping provider supports the CredentialMapperV2.PKI_KEY_PAIR_TYPE and CredentialMapperV2.PKI_TRUSTED_CERTIFICATE_TYPE token types.

WebLogic Server also includes the SAML Credential Mapping provider. The SAML Credential Mapping provider generates SAML 1.1 and 2.0 assertions for authenticated subjects based on a target site or resource. If the requested target has not been configured and no defaults are set, an assertion will not be generated. User information and group membership (if configured as such) are put in the AttributeStatement.

As described in "Configuring SAML SSO Attribute Support" in Developing Applications with the WebLogic Security Service, WebLogic Server enhanced the SAML 1.1 and 2.0 Credential Mapping provider and Identity Assertion provider mechanisms to support the use of a custom attribute mapper that can obtain additional attributes (other than group information) to be written into SAML assertions, and to then map attributes from incoming SAML assertions.

The SAML Credential Mapping provider supports the CredentialMapperV2.SAML_ASSERTION_B64_TYPE, CredentialMapperV2.SAML_ASSERTION_DOM_TYPE, and CredentialMapperV2.SAML_ASSERTION_TYPE token types.

The SAML 2.0 Credential Mapping provider supports the CredentialMapperV2.SAML2_ASSERTION_DOM_TYPE, and CredentialMapperV2.SAML2_ASSERTION_TYPE token types.

If the out-of-the-box credential mapping providers do not meet your needs, then you need to develop a custom credential mapping provider. Note, however, that only the following token types are ever requested by the WebLogic Server resource containers:

  • CredentialMapperV2.PASSWORD_TYPE

  • CredentialMapperV2.PKI_KEY_PAIR_TYPE

  • CredentialMapperV2.PKI_TRUSTED_CERTIFICATE_TYPE

  • CredentialMapperV2.SAML_ASSERTION_B64_TYPE

  • CredentialMapperV2.SAML_ASSERTION_DOM_TYPE

  • CredentialMapperV2.SAML_ASSERTION_TYPE

  • CredentialMapperV2.SAML2_ASSERTION_DOM_TYPE

  • CredentialMapperV2.SAML2_ASSERTION_TYPE

  • CredentialMapperV2.USER_PASSWORD_TYPE

Does Your Custom Credential Mapping Provider Need to Support
Application Versioning?

All authorization, role mapping, and credential mapping providers for the security realm must support application versioning in order for an application to be deployed using versions. If you develop a custom security provider for authorization, role mapping, or credential mapping and need to support versioned applications, you must implement the Versionable Application SSPI, as described in Chapter 14, "Versionable Application Providers."

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 for your custom credential mapping provider by completing the steps described in Appendix B, "Generate an MBean Type Using the WebLogic MBeanMaker."

  3. Provide a Mechanism for Credential Map Management

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:

Implement the CredentialProviderV2 SSPI

To implement the CredentialProviderV2 SSPI, provide implementations for the methods described in Understand the Purpose of the "Provider" SSPIs and the following method:

  • getCredentialProvider

    public CredentialMapperV2 getCredentialProvider();

    The getCredentialProviderV2 method obtains the implementation of the CredentialMapperV2 SSPI. For a single runtime class called MyCredentialMapperProviderImpl.java (as in Figure 3-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 CredentialProviderV2 SSPI is used as a factory to obtain classes that implement the CredentialMapperV2 SSPI.

For more information about the CredentialProviderV2 SSPI and the getCredentialProvider method, see the Java API Reference for Oracle WebLogic Server.

Implement the DeployableCredentialProvider SSPI

Note:

The DeployableCredentialProvider SSPI is deprecated in this release of WebLogic Server.

To implement the DeployableCredentialProvider SSPI, provide implementations for the methods described in Understand the Purpose of the "Provider" SSPIs, Implement the CredentialProviderV2 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. 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 Java API Reference for Oracle WebLogic Server.

Implement the CredentialMapperV2 SSPI

The CredentialMapperV2 interface defines the security service provider interface (SSPI) for objects capable of obtaining the appropriate set of credentials for a particular resource that is scoped within an application.

Only the following credential types are supported and passed to the CredentialMapperV2 interface:

  • PASSWORD_TYPE

  • PKI_KEY_PAIR_TYPE

  • PKI_TRUSTED_CERTIFICATE_TYPE

  • SAML_ASSERTION_B64_TYPE

  • SAML_ASSERTION_DOM_TYPE

  • SAML_ASSERTION_TYPE

  • SAML2_ASSERTION_DOM_TYPE

  • SAML2_ASSERTION_TYPE

  • USER_PASSWORD_TYPE

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

  • getCredential

    public Object getCredential(Subject requestor, String initiator, Resource
resource, ContextHandler handler, String credType);

    The getCredential method returns the credential of the specified type from the target resource associated with the specified initiator.

  • getCredentials

    public Object[] getCredentials(Subject requestor, Subject initiator, Resource
resource, ContextHandler handler, String credType);

    The getCredentials method returns the credentials of the specified type from the target resource associated with the specified initiator.

For more information about the CredentialMapperV2 SSPI and the getCredential and getCredentials methods, see the Java API Reference for Oracle WebLogic Server.

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.

Example 11-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. The code makes use of the methods available in the weblogic.security.SubjectUtils class.

Example 11-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; 
}

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 that allows them to add, modify, or remove credential mappings for various Connector modules.

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 two ways:

Option 1: 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. 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.)

  3. Read and write the expressions from and to the custom credential mapping provider's database.

Option 2: 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 WebLogic Server 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.)

  3. Read and write the expressions from and to the custom credential mapping provider's database.

  4. Link into the WebLogic Server Administration Console using basic console extension techniques.