javax.resource API 1.7.1 · javax.resource.spi.work.SecurityContext

A standard WorkContext that allows a Work instance to propagate security related context information from an EIS to an application server.

This allows an EIS/resource adapter to flow-in security context information and execute a Work instance, and call methods on a MessageEndpoint interface, to effect message inflow, within that Work instance, in the context of an established identity.

A resource adapter indicates to the WorkManager, that a Work instance needs to be run in a specified security execution context by submitting a Work instance that implements WorkContextProvider interface and ensuring that the List of WorkContexts for that Work instance contains an instance of its subclass of Securitytext.

It should be noted however that when a resource adapter flows-in an identity to be used by the application server, the propagated identity may or may not belong to the application server's security domain.

There are therefore, two scenarios while a resource adapter propagates a security identity from an EIS to the application server:

Case 1: Resource adapter flows-in an identity in the application server's security domain: In this case, the application server could just set the initiating principal, flown-in from the resource adapter, as the security context the Work instance executes as.
Case 2: Resource adapter flows-in an identity belonging to the EIS' security domain: The resource adapter establishes a connection to the EIS and needs to perform a Work in the context of an EIS identity. In this case, the initiating or caller principal does not exist in the application server's security domain and a translation from one domain to the other needs to be performed.

Modifier and Type	Field and Description
private static final long	serialVersionUID Determines if a deserialized instance of this class is compatible with this class.

Constructor Summary

Access	Constructor and Description
public	SecurityContext()

Method Summary

Modifier and Type	Method and Description
public String	getDescription() Implements javax.resource.spi.work.WorkContext.getDescription. Get the brief description of the role played by the `WorkContext` and any other related debugging information.
public String	getName() Implements javax.resource.spi.work.WorkContext.getName. Get the associated name of the `WorkContext`.
public abstract void	setupSecurityContext(CallbackHandler A `CallbackHandler` provided by the `WorkManager` that supports the `Callback`s described above handler, Subject A Subject that represents the security identity that needs to be established as the context for the `Work` instance. It is used by the method implementation to store Principals and credentials that needs to be used as the security context of the `Work` instance. executionSubject, Subject A Subject that represents the application server It may be used by the method implementation as the source of Principals or credentials to be used to validate a connection to the EIS. If the Subject is not null, the method implementation may add additional Principals or credentials (pertaining to the recipient of the service request) to the Subject. * serviceSubject) The container calls this method to set up the security Context for the `Work` instance.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

serialVersionUID	back to summary
private static final long serialVersionUID Determines if a deserialized instance of this class is compatible with this class.

Constructor Detail

SecurityContext	back to summary
public SecurityContext()

Method Detail

getDescription back to summary

getDescription	back to summary
public String getDescription() Implements javax.resource.spi.work.WorkContext.getDescription. Doc from javax.resource.spi.work.WorkContext.getDescription. Get the brief description of the role played by the `WorkContext` and any other related debugging information. This could be used by the WorkManager and the resource adapter for debugging purposes. Returns:String the associated description of the `WorkContext`

public String getDescription()

Implements javax.resource.spi.work.WorkContext.getDescription.

Doc from javax.resource.spi.work.WorkContext.getDescription.

Get the brief description of the role played by the WorkContext and any other related debugging information. This could be used by the WorkManager and the resource adapter for debugging purposes.

Returns:String: the associated description of the WorkContext

getName back to summary

getName	back to summary
public String getName() Implements javax.resource.spi.work.WorkContext.getName. Doc from javax.resource.spi.work.WorkContext.getName. Get the associated name of the `WorkContext`. This could be used by the WorkManager and the resource adapter for debugging purposes. Returns:String the associated name of the `WorkContext`

public String getName()

Implements javax.resource.spi.work.WorkContext.getName.

Doc from javax.resource.spi.work.WorkContext.getName.

Get the associated name of the WorkContext. This could be used by the WorkManager and the resource adapter for debugging purposes.

Returns:String: the associated name of the WorkContext

setupSecurityContext back to summary

setupSecurityContext	back to summary
public abstract void setupSecurityContext(CallbackHandler handler, Subject executionSubject, Subject serviceSubject) The container calls this method to set up the security Context for the `Work` instance. The handler argument must not be null, and the argument handler and the `CallbackHandler` passed to this method must support the following `Callback`s defined in JSR 196: Java Authentication SPI for Containers specification: CallerPrincipalCallback GroupPrincipalCallback PasswordValidationCallback The following `Callback`s may be supported by the container. CertStoreCallback PrivateKeyCallback SecretKeyCallback TrustStoreCallback A resource adapter might use the `CallerPrincipalCallback` "to set the container's representation of the caller principal. The CallbackHandler must establish the argument Principal as the caller principal associated with the invocation being processed by the container. When the argument Principal is null, the handler will establish the container's representation of the unauthenticated caller principal." A resource adapter might use the `GroupPrincipalCallback` "to establish the container's representation of the corresponding group principals within the Subject. When a null value is passed to the groups argument, the handler will establish the container's representation of no group principals within the Subject. Otherwise, the handler's processing of this callback is additive, yielding the union (without duplicates) of the principals existing within the Subject, and those created with the names occurring within the argument array. The CallbackHandler will define the type of the created principals." A resource adapter might use the `PasswordValidationCallback` "to employ the password validation facilities of its containing runtime." The executionSubject argument must be non-null and it must not be read-only. It is expected that this method will populate this executionSubject with principals and credentials that would be flown into the application server. The serviceSubject argument may be null, and when it is not null it must not be read-only. It represents the application server and it may be used by the Work implementation to retrieve Principals and credentials necessary to establish a connection to the EIS (in the cause of mutual-auth like scenarios). If the Subject is not null, the Work implementation may collect the server credentials, as necessary, by using the callback handler passed to them . When this method is called, the method implementation identifies the security context that needs to be flown-in to the application server to serve as the execution context of the Work instance. populates the executionSubject with the EIS Principals and Credentials that it wants to serve as the security context for the Work instance to be executed in. adds instances of the necessary Callbacks , usually a subset of the ones listed above, to an array and invokes the handle() method in the container's CallbackHandler implementation passing in the array of Callback instances. on successful return from the CallbackHandler.handle() method the setSecurityContext returns after ensuring that the executionSubject is populated with the valid Principals and Credentials that represent the execution context of the Work instance Parameters handler:CallbackHandler A `CallbackHandler` provided by the `WorkManager` that supports the `Callback`s described above executionSubject:Subject A Subject that represents the security identity that needs to be established as the context for the `Work` instance. It is used by the method implementation to store Principals and credentials that needs to be used as the security context of the `Work` instance. serviceSubject:Subject A Subject that represents the application server It may be used by the method implementation as the source of Principals or credentials to be used to validate a connection to the EIS. If the Subject is not null, the method implementation may add additional Principals or credentials (pertaining to the recipient of the service request) to the Subject. * See Also `196: Java Authentication SPI for Containers specification and related JavaDoc`

public abstract void setupSecurityContext(CallbackHandler handler, Subject executionSubject, Subject serviceSubject)

The container calls this method to set up the security Context for the Work instance.

The handler argument must not be null, and the argument handler and the CallbackHandler passed to this method must support the following Callbacks defined in JSR 196: Java Authentication SPI for Containers specification:

CallerPrincipalCallback
GroupPrincipalCallback
PasswordValidationCallback

The following Callbacks may be supported by the container.

CertStoreCallback
PrivateKeyCallback
SecretKeyCallback
TrustStoreCallback

A resource adapter might use the CallerPrincipalCallback "to set the container's representation of the caller principal. The CallbackHandler must establish the argument Principal as the caller principal associated with the invocation being processed by the container. When the argument Principal is null, the handler will establish the container's representation of the unauthenticated caller principal."

A resource adapter might use the GroupPrincipalCallback "to establish the container's representation of the corresponding group principals within the Subject. When a null value is passed to the groups argument, the handler will establish the container's representation of no group principals within the Subject. Otherwise, the handler's processing of this callback is additive, yielding the union (without duplicates) of the principals existing within the Subject, and those created with the names occurring within the argument array. The CallbackHandler will define the type of the created principals."

A resource adapter might use the PasswordValidationCallback "to employ the password validation facilities of its containing runtime."

The executionSubject argument must be non-null and it must not be read-only. It is expected that this method will populate this executionSubject with principals and credentials that would be flown into the application server.

The serviceSubject argument may be null, and when it is not null it must not be read-only. It represents the application server and it may be used by the Work implementation to retrieve Principals and credentials necessary to establish a connection to the EIS (in the cause of mutual-auth like scenarios). If the Subject is not null, the Work implementation may collect the server credentials, as necessary, by using the callback handler passed to them .

When this method is called, the method implementation

identifies the security context that needs to be flown-in to the application server to serve as the execution context of the Work instance.
populates the executionSubject with the EIS Principals and Credentials that it wants to serve as the security context for the Work instance to be executed in.
adds instances of the necessary Callbacks , usually a subset of the ones listed above, to an array and invokes the handle() method in the container's CallbackHandler implementation passing in the array of Callback instances.
on successful return from the CallbackHandler.handle() method the setSecurityContext returns after ensuring that the executionSubject is populated with the valid Principals and Credentials that represent the execution context of the Work instance

Parameters

handler:CallbackHandler: A CallbackHandler provided by the WorkManager that supports the Callbacks described above
executionSubject:Subject: A Subject that represents the security identity that needs to be established as the context for the Work instance. It is used by the method implementation to store Principals and credentials that needs to be used as the security context of the Work instance.
serviceSubject:Subject: A Subject that represents the application server It may be used by the method implementation as the source of Principals or credentials to be used to validate a connection to the EIS. If the Subject is not null, the method implementation may add additional Principals or credentials (pertaining to the recipient of the service request) to the Subject. *

public abstract Class SecurityContext

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail