Package oracle.jdbc.spi

Interface EndUserSecurityContextProvider

All Superinterfaces:
OracleResourceProvider
public interface EndUserSecurityContextProvider extends OracleResourceProvider

A provider of the security context in which the end user of an application executes a database operation.

The oracle.jdbc.provider.endUserSecurityContext connection property identifies the name of an EndUserSecurityContextProvider implementation. Connection properties under the namespace of oracle.jdbc.provider.endUserSecurityContext configure any parameters that an implementation defines. To illustrate, the connection properties below would identify a provider named "example-provider", and configure a parameter named "clientId": 

  oracle.jdbc.provider.endUserSecurityContext = example-provider
  oracle.jdbc.provider.endUserSecurityContext.clientId = 11111111-2222-3333-4444-555555555555

ServiceLoader locates implementations of EndUserSecurityContextProvider declared by a META-INF/services/oracle.jdbc.spi.EndUserSecurityContextProvider file in the class path, or by a module-info.java file with a "provides oracle.jdbc.spi.EndUserSecurityContextProvider" directive in the module path. Typically, these files are distributed within a jar file that contains an EndUserSecurityContextProvider implementation.

Since:
26

  • Method Details

    • getEndUserSecurityContext

      EndUserSecurityContext getEndUserSecurityContext(Map<OracleResourceProvider.Parameter,CharSequence> parameterValues)

      Returns the security context in which a database operation is executed by the end user of an application. Oracle JDBC invokes this method before every database operation. For example, every time PreparedStatement.execute() is called, Oracle JDBC invokes this method to get the security context in which the SQL operation is being executed.

      Each time this method is invoked, the result of that invocation determines the security context in which the next database operation is executed.

      If a non-null EndUserSecurityContext is returned:
      The next database operation is executed within the provided security context.
      If null EndUserSecurityContext is returned:
      The next database operation is executed as normal, under the security policy of the database user that was authenticated when Driver.connect(String, java.util.Properties) was called.
      If an IllegalArgumentException or IllegalStateException is thrown:
      No database operation is executed, and a SQLException is thrown from the method that was attempting to do so. For instance, PreparedStatement.execute() would throw a SQLException before the SQL operation could be executed.

      When JDBC connections are pooled, the same connection may be reused to service the requests of different end users. This method should be implemented to return an EndUserSecurityContext that identifies which end user is currently using the JDBC connection. In cases where multiple database operations are executed for the same end user, consecutive invocations of this method should return an EndUserSecurityContext with identical information, perhaps even the same instance. When database operations are not being executed on behalf of any end user, this method may return null.

      The parameterValues passed to this method is a Map comprised as follows:

      • The key set is the same as, or a subset of, the Parameter objects returned by an invocation of OracleResourceProvider.getParameters() on this provider.
      • If no value is configured for a parameter, then the Map contains the default value of that Parameter, if any. If the parameter has no default value, then the map does not contain an entry for that Parameter.
      • The Map does not contain entries having null values.

      The parameterValues Map may contain a CharSequence having a security sensitive value. After this method returns, the caller may wipe the contents of these CharSequence values from memory. Implementations of this method should not retain a reference to these CharSequence objects.

      Parameters:
      parameterValues - Parameters configured by connection properties . Not null. May be empty.
      Returns:
      The end user security context, or null if there is none.
      Throws:
      IllegalArgumentException - If the value of a parameter can not be parsed or interpreted.
      IllegalStateException - If an implementation-specific failure prevents a resource from being provided.