Package 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

  • Constructor Details

    • RidcConnection

      public RidcConnection()

  • Method Details

    • 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.