oracle.wcc.ridc.adfca

Class RidcConnection

java.lang.Object

oracle.wcc.ridc.adfca.RidcConnection

Direct Known Subclasses:

RidcConnectionImpl

public abstract class RidcConnection
extends Object

Public API for consuming WebCenter Content RIDC-based Connection

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RidcConnection.Protocol RIDC protocol types

Constructor Summary

Constructors

Constructor and Description
RidcConnection()

Method Summary

Modifier and Type	Method and Description
DataBinder	createBinder() Create a new DataBinder.
abstract DataBinder	createImpersonationBinder(String impersonatee, boolean sticky) Create a new DataBinder that is initialized with properties to support impersonation.
abstract IdcContext	getAnonymousCredential() Get a credential for the anonymous user.
static RidcConnection	getConnection(String connectionName) Obtain from registry of RidcConnection singletons, the RidcConnection with the specified name.
abstract String	getConnectionName() Gets the connection's name.
abstract IdcContext	getCredential() Evaluates the credentials stored for this connection instance along with the protocol being leveraged and infers / returns the user context deemed most appropriate.
abstract IdcContext	getCredential(String username) Attempt to obtain for the specified username an appropriate user context object.
abstract IdcContext	getCredentialForADFSecurityContextUser() Attempt to obtain for the user as seen by the ADF Security Context an appropriate user context object.
abstract IdcContext	getCredentialForADFSecurityContextUser(boolean anonymousSupported) Attempt to obtain for the user as seen by the ADF Security Context an appropriate user context object.
abstract IdcContext	getCredentialForImpersonatee(String impersonatee, IdcContext impersonatorContext) Leverages the specified impersonator user context to invoke a PING_SERVER call to the Content Server with impersonation properties set in the request DataBinder requesting sticky impersonation for the specified impersonatee.
abstract IdcClient	getIdcClient() Gets the IdcClient instance for this connection.
IdcClientManager	getIdcClientManager() Gets the IdcClientManager that was used to create the IdcClient instance for this connection.
abstract Boolean	getPropSessionPoolAnonymousFallback() Gets the session pool anonymous fallback property.
abstract RidcConnection.Protocol	getProtocol() Gets the connection's protocol type.
abstract Class	getSessionPoolCredentialProviderClass() Gets the RidcCredentialProvider Class to utilize to generate the initial IdcContext for new RidcSession instances created within the ADF session-scoped Session Pool.
abstract boolean	isHttpConnection() Returns true if the connection's protocol is HTTP
abstract boolean	isIntradocConnection() Returns true if the connection's protocol is Intradoc
abstract boolean	isJaxwsConnection() Returns true if the connection's protocol is JAX/WS
abstract void	logout(IdcContext userContext) Attempt to logout the session wrapped by the specified IdcContext instance.
abstract DataBinder	ping() Invoke an anonymous PING_SERVER call to the Content Server associated with this connection.
ServiceResponse	sendRequest(IdcContext userContext, DataBinder binder) Execute the request; Sends the request to the Content Server and obtains the response.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RidcConnection

public RidcConnection()

Method Detail

getConnection

public static RidcConnection getConnection(String connectionName)
                                    throws NamingException,
                                           IdcClientException

Obtain from registry of RidcConnection singletons, the RidcConnection with the specified name. The registry of connections (ConcurrentHashMap) is stored in the ADF Application Scope. Consult RidcConnectionProvider for more details.

The first time a connection for a specified name is obtained, some minor validations are performed in the initialization process which ultimately culminates in an anonymous PING_SERVER test being invoked. The PING_SERVER test confirms that the protocol and connection URL are appropriate, but does NOT validate the connection's associated credentials.

Notes:

Each RidcConnection returned wraps a unique IdcClient and IdcClientManager instance. IdcClientManger is NOT shared between RidcConnection instances; Take this in to account should registering of RIDC filters be required.

Once a named connection is obtained for the first time and initialized, any subsequent changes to that connection by way of MBean operations will not take effect until either

1. The application/server is restarted
2. The connections map is disposed through the RidcConnectionProvider.dispose() method and any existing connection objects held by application code are nullified. Subsequent call to getConnection(..) would result in a fresh connection with latest available properties.

This method is simply a convenience/shortcut method for accessing the like-named method found in the RidcConnectionProvider class.

This method is thread-safe.

Parameters:

connectionName - The name of the RIDC ADF Connection

Returns:

A singleton RidcConnection instance obtained from the registry for the specified connection name.

Throws:

NamingException

IdcClientException

getConnectionName

public abstract String getConnectionName()

Gets the connection's name.

Returns:

name of the connection

getIdcClient

public abstract IdcClient getIdcClient()

Gets the IdcClient instance for this connection.

Returns:

IdcClient the IdcClient instance

getIdcClientManager

public IdcClientManager getIdcClientManager()

Gets the IdcClientManager that was used to create the IdcClient instance for this connection. This is just a simple convenience method.

Returns:

IdcClientManager leveraged to created the IdcClient

getProtocol

public abstract RidcConnection.Protocol getProtocol()

Gets the connection's protocol type.

Returns:

protocol type (intradoc / http / jaxws)

isJaxwsConnection

public abstract boolean isJaxwsConnection()

Returns true if the connection's protocol is JAX/WS

Returns:

true if leveraging the JAX/WS protocol

isHttpConnection

public abstract boolean isHttpConnection()

Returns true if the connection's protocol is HTTP

Returns:

true if leveraging the HTTP protocol

isIntradocConnection

public abstract boolean isIntradocConnection()

Returns true if the connection's protocol is Intradoc

Returns:

true if leveraging the Intradoc protocol

ping

public abstract DataBinder ping()
                         throws IdcClientException

Invoke an anonymous PING_SERVER call to the Content Server associated with this connection.

Returns:

The response DataBinder

Throws:

IdcClientException

logout

public abstract void logout(IdcContext userContext)

Attempt to logout the session wrapped by the specified IdcContext instance.

Note - Earlier versions of RIDC did not provide a logout method; To allow this connection architecture to potentially work with older RIDC api, we use a static initializer and reflection to determine if logout method is present. Only if the method is present do we invoke it.

A logout may also be a NO-OP for certain RIDC connection protocols.

Parameters:

userContext - The user context object

createBinder

public DataBinder createBinder()

Create a new DataBinder.

This method is simply a convenience/shortcut method for accessing the like-named method found in the IdcClient class.

Returns:

a new data binder

createImpersonationBinder

public abstract DataBinder createImpersonationBinder(String impersonatee,
                                                     boolean sticky)

Create a new DataBinder that is initialized with properties to support impersonation.

Note - Impersonation is only available with specific versions of the Content Server

Impersonation can be either per request, or sticky (survive the request).

Per-request impersonation is likely the safest approach; The app should configure a pool of impersonator (person whom has privileges to impersonate another user) user contexts, and then when impersonation is required call this method to add the "RunAs" property in the request DataBinder with value set to the impersonatee (person being impersonated).

Warning 1 - Be very careful with impersonation - particularly sticky impersonation;
Should the session associated with an IdcContext expire, it is possible with certain RIDC protocols that the connection may be silently re-established using the actual impersonator user rather than the impersonatee intended. Subsequently, the request to UCM will go across using the impersonator user rather than the impersonatee (person being impersonated) which could have bad security consequences.

Warning 2 - If the end-user is able to inject properties in to the DataBinder without sanitization, and sticky impersonation is active, a malicious end-user could supply the property "StickyImpersonation" with value "false" in a request, which would restore the connection back as the impersonator user.

Parameters:

impersonatee - The user whom will be impersonated

sticky - set to true if impersonation should survive the request

Returns:

A DataBinder initialized with properties required for impersonation.

sendRequest

public ServiceResponse sendRequest(IdcContext userContext,
                                   DataBinder binder)
                            throws IdcClientException

Execute the request; Sends the request to the Content Server and obtains the response.

This method is simply a convenience/shortcut method for accessing the like-named method found in the IdcClient class.

Parameters:

userContext - the user context

binder - the request data binder object

Returns:

the response

Throws:

IdcClientException

getAnonymousCredential

public abstract IdcContext getAnonymousCredential()

Get a credential for the anonymous user.

Returns:

A user context object for the anonymous user

getCredential

public abstract IdcContext getCredential()

Evaluates the credentials stored for this connection instance along with the protocol being leveraged and infers / returns the user context deemed most appropriate.

Care should be taken when creating/updating a connection that only the appropriate credential properties are set, and the others set to null/None.

*** If the connection has no credential properties set, an IllegalStateException will be thrown.

Important Rules / Notes:

Intradoc protocol
Returns an IdcContext leveraging just the username connection prop

HTTP Protocol
Returns an IdcContext leveraging the username and password connection properties.

JAX/WS Protocol
Returns an IdcContext with AppIdClientCredentials should the credential.appidkey prop be non empty.
** Otherwise
Returns an IdcContext leveraging the username and password connection properties if the password property is non-null with length > 0.
** Otherwise
Returns an IdcContext leveraging the username connection prop.

Returns:

A user context object based on the protocol and credential properties set for this connection

getCredentialForADFSecurityContextUser

public abstract IdcContext getCredentialForADFSecurityContextUser()

Attempt to obtain for the user as seen by the ADF Security Context an appropriate user context object.

If the ADF security context believes no user is authenticated, a null (IdcContext) object will be returned.

See Important Rules / Notes outlined for the getCredential(String username) method;

In particular understand that null will be returned if it is deemed the only way to support the request is to leverage identity impersonation and that identity impersonation has not been enabled or failed for the connection.

Returns:

A user context object for the authenticated user seen by the ADF Security Context (if possible based on the connection definition). Null otherwise.

getCredentialForADFSecurityContextUser

public abstract IdcContext getCredentialForADFSecurityContextUser(boolean anonymousSupported)

Attempt to obtain for the user as seen by the ADF Security Context an appropriate user context object.

If the ADF security context believes no user is authenticated, an IdcContext object wrapping the anonymous credential will be returned should the anonymousSupported method property be set to true.

See Important Rules / Notes outlined for the getCredential(String username) method;

In particular understand that null will be returned if it is deemed the only way to support the request is to leverage identity impersonation and that identity impersonation has not been enabled or failed for the connection.

Parameters:

anonymousSupported - whether to support returning of anonymous credentials for non-Authenticated users.

Returns:

when anonymousSupported is true, an anonymous credential will be returned if the ADF Security Context believes no user is authenticated. When an authenticated user is seen by the ADF Security Context, a best-effort attempt will be made to obtain a user context object for the user. null will be returned in all other cases.

getCredential

public abstract IdcContext getCredential(String username)

Attempt to obtain for the specified username an appropriate user context object.

Whether this can be achieved may depend on the connection properties such as protocol being leveraged, what credentials are set on the connection, whether identity impersonation is enabled etc.

Method Rules:

Throws IllegalArgumentException if the specified username is null or trimmed empty.

Intradoc protocol
Returns an IdcContext wrapping the specified username.
Intradoc is a trusted protocol and requires no passwords, hence so long as the specified username is valid, and the server trusts the client's ip address, everything should work as expected.

HTTP protocol
Returns null if no credentials are set for the connection.
** Otherwise
Returns an IdcContext associated with the connection should the specified username match the connection's stored username.
** Otherwise
Returns null if identity impersonation has not been enabled.
** Otherwise
If impersonation feature is enabled, the connection's username and password properties will be leveraged to obtain a user context credential that will deemed the impersonatorContext. This impersonatorContext credential along with the specified username (aka impersonatee) will be passed on to the getCredentialForImpersonatee() method and the user context obtained as a result returned. getCredentialForImpersonatee() will return a null user context if impersonation fails.

JAX/WS protocol
Returns an IdcContext wrapping the specified username should either no credentials be set for the connection, or only the username property be set. (This assumes client policy is SAML based and Identity Switch will be leveraged).
** Otherwise
Returns an IdcContext associated with the connection should the specified username match the connection's stored username.
** Otherwise
Returns null if identity impersonation has not been enabled.
** Otherwise
If impersonation feature is enabled, the connection's appid key / or username and password properties will be leveraged to obtain a user context credential that will deemed the impersonatorContext. This impersonatorContext credential along with the specified username (aka impersonatee) will be passed on to the getCredentialForImpersonatee() method and the user context obtained as a result returned. getCredentialForImpersonatee() will return a null user context if impersonation fails.

Important Notes:

If impersonation will be leveraged to obtain the user context for the specified username, please take note of the Important Security Warnings found in the javadoc for the createImpersonationBinder(String impersonatee, boolean sticky) method;

Impersonation in general requires:

1. Destination UCM Server to be a suitable version that supports impersonation concept.
2. UCM Server to have impersonation feature activated
3. The Connection's stored credential to be that of a valid user / appidkey whom possesses the role configured/required for impersonation
4. The connection to be configured with the impersonation property enabled

JAX/WS Identity Switch info:
In order to make a SAML connection to the UCM server leveraging a user not matching the authenticated subject, an identity switch SAML policy would ordinarily be required. Additionally, a special codesource permission grant of type oracle.wsm.security.WSIdentityPermission is required for the application on the on wsm-agent-core.jar. If the policy configured for the JAX/WS RIDC connection be it explicitly or by way of GPA does not set subject.precedence=false, identity switch will not function. By setting the protocol.jaxws.registeridentityswitchfilter property to true on the connection, a special filter that gets invoked before each JAX/WS request will override this property to ensure subject.precedence=false.

Parameters:

username - the user for which an appropriate user context object is required.

Returns:

A user context object based on the protocol and credential properties set for this connection; or null if this was not possible.

getCredentialForImpersonatee

public abstract IdcContext getCredentialForImpersonatee(String impersonatee,
                                                        IdcContext impersonatorContext)

Leverages the specified impersonator user context to invoke a PING_SERVER call to the Content Server with impersonation properties set in the request DataBinder requesting sticky impersonation for the specified impersonatee.

If the response binder obtained from the PING_SERVER has a dUser value matching that of the impersonatee supplied, then the impersonation is deemed successful and the impersonatorContext will be returned to the callee. This user context is now impersonating the impersonatee.

Otherwise, if impersonation failed, the impersonatorContext is logged out and null is returned.

See Important Security Warnings found in the javadoc for the createImpersonationBinder(String impersonatee, boolean sticky) method;

Also note, this method will attempt impersonation regardless of whether the underlying connection has the impersonation property enabled!

Parameters:

impersonatee - person being impersonated

impersonatorContext - user context of person whom has privileges to impersonate another user.

Returns:

impersonatorContext now acting as the impersonatee if impersonation succeeded, otherwise null.

getSessionPoolCredentialProviderClass

public abstract Class getSessionPoolCredentialProviderClass()

Gets the RidcCredentialProvider Class to utilize to generate the initial IdcContext for new RidcSession instances created within the ADF session-scoped Session Pool. A return value of null indicates that the connection has not been configured with session pool support property set to true.

Returns:

RidcCredentialProvider Class

getPropSessionPoolAnonymousFallback

public abstract Boolean getPropSessionPoolAnonymousFallback()

Gets the session pool anonymous fallback property.

Returns:

whether the credentail provider class should fallback to returning an anonymous IdcContext instance in the event the connected user or appropriate cannot be determined.