com.pingidentity.pa.sdk.identitymapping

Interface IdentityMappingPlugin<T extends PluginConfiguration>

Type Parameters:

T - the PluginConfiguration class for this implementation of IdentityMappingPlugin

All Superinterfaces:

ConfigurablePlugin<T>, DescribesUIConfigurable

All Known Implementing Classes:

HeaderIdentityMappingPlugin, IdentityMappingPluginBase

public interface IdentityMappingPlugin<T extends PluginConfiguration>
extends DescribesUIConfigurable, ConfigurablePlugin<T>

A IdentityMappingPlugin is the runtime instantiation of an Identity Mapping defined in the Administrative API. It can be used to map the data of an Identity into a form that is expected by the protected application. The protected application then uses this mapped identity to identify the end-user or user-agent.

Implementing a IdentityMappingPlugin

Plugin Annotation

A class that implements IdentityMappingPlugin must be annotated with the IdentityMapping annotation.

Provider-configuration file

The fully qualified class name for an implementation of IdentityMappingPlugin should be placed in a META-INF/services/com.pingidentity.pa.sdk.identitymapping.IdentityMappingPlugin resource file that is packaged in the jar containing the compiled class for the implementation. This signals to PingAccess that the class is a valid IdentityMappingPlugin implementation.

Responsibilities of a IdentityMappingPlugin

In addition to the responsibilities of a configurable plugin defined in the com.pingidentity.pa.sdk.plugins documentation, a IdentityMappingPlugin has the following additional responsibilities:

Handling Requests

The IdentityMappingPlugin will inspect Identity attributes for the current request and modify the request that will be sent to the protected application. The modified request should contain identity information that can be used by the target Application for identification and authorization. For example, an IdentityMappingPlugin might translate identity attributes into headers to be used by the protected application.

Two methods should be implemented in a IdentityMappingPlugin.

The mapIdentity(com.pingidentity.pa.sdk.identity.Identity, com.pingidentity.pa.sdk.http.Request, com.pingidentity.pa.sdk.http.Exchange) method is called on request where the user has been authenticated. This method should modify the request to provide any identity information for the target Application.

The mapAnonymousIdentity(com.pingidentity.pa.sdk.http.Request, com.pingidentity.pa.sdk.http.Exchange) method is called on an anonymous request.

A note about header clobbering: If headers are to be used to pass identity information to the target Application, the configured headers should always overwrite any headers of the same name that may have come in the original request. This should happen even in the case of anonymous requests and the configured headers should return empty values. To simplify header based identity mapping, HeaderIdentityMappingPlugin may be extended and will handle this behavior.

In order to comply with the PingAccess Agent Protocol, the user subject should be returned to the target Agent in a header and the vnd-pi-sub header should be set indicating the header name. The IdentityMappingPlugin will handle this automatically if Identity.setMappedSubject(java.lang.String) is called within mapIdentity(com.pingidentity.pa.sdk.identity.Identity, com.pingidentity.pa.sdk.http.Request, com.pingidentity.pa.sdk.http.Exchange), setting the value to the subject.

See Also:

com.pingidentity.pa.sdk.plugins

Method Summary

Modifier and Type	Method and Description
void	mapAnonymousIdentity(Request request, Exchange exchange) Maps the anonymous identity.
void	mapIdentity(Identity identity, Request request, Exchange exchange) Maps the identity by inspecting the identity associated with the request and making modifications to the request and/or exchange.

Methods inherited from interface com.pingidentity.pa.sdk.plugins.DescribesUIConfigurable

getConfigurationFields

Methods inherited from interface com.pingidentity.pa.sdk.plugins.ConfigurablePlugin

configure, getConfiguration

Method Detail

mapIdentity

void mapIdentity(Identity identity,
                 Request request,
                 Exchange exchange)

Maps the identity by inspecting the identity associated with the request and making modifications to the request and/or exchange.

If the subject is configured in the IdentityMapping, Identity.setMappedSubject(java.lang.String) should be called, setting the subject value.

NOTE: Modifications to the exchange via Exchange.setRequest(Request), and Exchange.setResponse(Response) will be ignored

Parameters:

identity - the identity of the request (always set)

request - the request

exchange - the exchange

mapAnonymousIdentity

void mapAnonymousIdentity(Request request,
                          Exchange exchange)

Maps the anonymous identity. An anonymous identity occurs when the corresponding Resource is configured as anonymous and the incoming request does not contain any identity information (such as the PingAccess cookie or OAuth token).

If the identity is mapped to request headers, this method should clobbers headers that would be set when an identity was present in the request.

NOTE: Modifications to the exchange via Exchange.setRequest(Request), and Exchange.setResponse(Response) will be ignored

Parameters:

request - the request

exchange - the exchange