Provides authentication and authorization (roles and initial schema) according to JAAS modules configured by the runtime JAAS implementation.

JAAS modules used must have both a NameCallback and a PasswordCallback. This is how we pass the JDBC-provided user name and password to the module.

JAAS setup is Java-implementation-specific. For Sun Java, you set up a JAAS configuration file which resides at $HOME/.java.login.config or at the location that you set with Java system property java.security.auth.login.config.

You can use this bean to manage just access, or also to manage roles or initial schemas. To use for roles or initial schemas, you must set the roleSchemaValuePattern property to distinguish which of the JAAS-module-provided values to use. By default, all JAAS-module-provided Principles will be candidates. If you set property roleSchemaViaCredential to true, then all JAAS-module-provided public Credentials will be candidates instead.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	JaasAuthBean.UPCallbackHandler

Modifier and Type	Field and Description
private String	applicationKey
private boolean	initialized
private static FrameworkLogger	logger
private Pattern	roleSchemaValuePattern
private boolean	roleSchemaViaCredential

Constructor Summary

Access	Constructor and Description
public	JaasAuthBean()

Method Summary

Modifier and Type	Method and Description
public String[]	authenticate(String userName, String password) Implements org.hsqldb.auth.AuthFunctionBean.authenticate. Return a list of authorized roles or null to indicate that the implementation does not intend to produce a specific role list but only to indicate whether to allow access or not.
public void	init()
public void	setApplicationKey(String key applicationKey) Set the key into the JAAS runtime configuration.
public void	setRoleSchemaValuePattern(Pattern pattern roleSchemaValuePattern) Assign a pattern to both detect honored values, and optionally to map from a single principal name or public credential string to a single HyperSQL role or schema string.
public void	setRoleSchemaValuePatternString(String pattern patternString) String wrapper for method setRoleSchemaValuePattern(Pattern) Use the (x?) Pattern constructs to set options.
public void	setRoleSchemaViaCredential(boolean boolean roleSchemaViaCredential) By default, If roleSchemaValuePattern is set, then role and schema values are obtained from principle values; otherwise existing account privileges are used (if any).

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

Field Detail

applicationKey	back to summary
private String applicationKey

initialized	back to summary
private boolean initialized

logger	back to summary
private static FrameworkLogger logger

roleSchemaValuePattern	back to summary
private Pattern roleSchemaValuePattern

roleSchemaViaCredential	back to summary
private boolean roleSchemaViaCredential

Constructor Detail

JaasAuthBean	back to summary
public JaasAuthBean()

Method Detail

authenticate	back to summary
public String[] authenticate(String userName, String password) throws DenyException Implements org.hsqldb.auth.AuthFunctionBean.authenticate. Doc from org.hsqldb.auth.AuthFunctionBean.authenticate. Return a list of authorized roles or null to indicate that the implementation does not intend to produce a specific role list but only to indicate whether to allow access or not. A return value of String[0] is different from returning null, and means that the user should not be granted any roles.

authenticate

back to summary

public String[] authenticate(String userName, String password) throws DenyException

Implements org.hsqldb.auth.AuthFunctionBean.authenticate.

Doc from org.hsqldb.auth.AuthFunctionBean.authenticate.

Return a list of authorized roles or null to indicate that the implementation does not intend to produce a specific role list but only to indicate whether to allow access or not. A return value of String[0] is different from returning null, and means that the user should not be granted any roles.

init	back to summary
public void init() Exceptions IllegalStateException: if any required setting has not been set.

setApplicationKey	back to summary
public void setApplicationKey(String applicationKey) Set the key into the JAAS runtime configuration. For Sun's JAAS implementation, this is the "application" identifier for a stanza in the JAAS configuration file. Parameters applicationKey:String key

setApplicationKey

back to summary

public void setApplicationKey(String applicationKey)

Set the key into the JAAS runtime configuration. For Sun's JAAS implementation, this is the "application" identifier for a stanza in the JAAS configuration file.

Parameters

applicationKey:String: key

setRoleSchemaValuePattern back to summary

setRoleSchemaValuePattern	back to summary
public void setRoleSchemaValuePattern(Pattern roleSchemaValuePattern) Assign a pattern to both detect honored values, and optionally to map from a single principal name or public credential string to a single HyperSQL role or schema string. Do not use this method if you are using this JaasAuthBean only to permit or reject access (with roles and schema being determined by pre-existing local HyperSQL accounts). On that case, simple success of the login() method method will allow access as the specified user. If every principal name or public credentials holds only the String values precisely as HyperSQL needs them, then set the pattern to ".+". For example, if the JAAS module returns principals (or credentials) with values "one", "two", "three", then if you set this pattern to ".+", HyperSQL will attempt to assign initial schema and roles for the values "one", "two", and "three". These are two distinct and important purposes for the specified Pattern. Values that do not successfully match the pattern will be ignored. If the pattern does match, then the entire principal or credential value will be used to assign initial schema or role (as long as it is a valid schema name or role name in the local database). Optionally uses parentheses to specify a single capture group (if you use parentheses to specify more than one matching group, we will only capture for the first). What is captured by this group is exactly the role or schema that HyperSQL will attempt to assign. If no capture parens are given then the Pattern is only used for the acceptance decision, and the JAAS-provided value will be returned verbatim. N.b. this Pattern will be used for the matches() operation, therefore it must match the entire candidate value strings (this is different than the find operation which does not need to satisfy the entire candidate value). Example1 : `cn=([^,]+),ou=dbRole,dc=admc,dc=com` will extract the CN value from matching attribute values. Example1 : `cn=[^,]+,ou=dbRole,dc=admc,dc=com` will return the entire `cn...com` string for matching attribute values. Parameters roleSchemaValuePattern:Pattern pattern See Also `Matcher#matches()`

public void setRoleSchemaValuePattern(Pattern roleSchemaValuePattern)

Assign a pattern to both detect honored values, and optionally to map from a single principal name or public credential string to a single HyperSQL role or schema string. Do not use this method if you are using this JaasAuthBean only to permit or reject access (with roles and schema being determined by pre-existing local HyperSQL accounts). On that case, simple success of the login() method method will allow access as the specified user.

If every principal name or public credentials holds only the String values precisely as HyperSQL needs them, then set the pattern to ".+". For example, if the JAAS module returns principals (or credentials) with values "one", "two", "three", then if you set this pattern to ".+", HyperSQL will attempt to assign initial schema and roles for the values "one", "two", and "three".

These are two distinct and important purposes for the specified Pattern.

Values that do not successfully match the pattern will be ignored. If the pattern does match, then the entire principal or credential value will be used to assign initial schema or role (as long as it is a valid schema name or role name in the local database).
Optionally uses parentheses to specify a single capture group (if you use parentheses to specify more than one matching group, we will only capture for the first). What is captured by this group is exactly the role or schema that HyperSQL will attempt to assign. If no capture parens are given then the Pattern is only used for the acceptance decision, and the JAAS-provided value will be returned verbatim.

N.b. this Pattern will be used for the matches() operation, therefore it must match the entire candidate value strings (this is different than the find operation which does not need to satisfy the entire candidate value).

Example1 :

cn=([^,]+),ou=dbRole,dc=admc,dc=com

will extract the CN value from matching attribute values.

Example1 :

cn=[^,]+,ou=dbRole,dc=admc,dc=com

will return the entire cn...com string for matching attribute values.

Parameters

roleSchemaValuePattern:Pattern: pattern

See Also

Matcher#matches()

setRoleSchemaValuePatternString back to summary

setRoleSchemaValuePatternString	back to summary
public void setRoleSchemaValuePatternString(String patternString) String wrapper for method setRoleSchemaValuePattern(Pattern) Use the (x?) Pattern constructs to set options. Parameters patternString:String pattern Exceptions PatternSyntaxException: exception See Also `setRoleSchemaValuePattern(Pattern)`

public void setRoleSchemaValuePatternString(String patternString)

String wrapper for method setRoleSchemaValuePattern(Pattern) Use the (x?) Pattern constructs to set options.

Parameters

patternString:String: pattern

Exceptions

PatternSyntaxException:: exception

See Also

setRoleSchemaValuePattern(Pattern)

setRoleSchemaViaCredential	back to summary
public void setRoleSchemaViaCredential(boolean roleSchemaViaCredential) By default, If roleSchemaValuePattern is set, then role and schema values are obtained from principle values; otherwise existing account privileges are used (if any). If roleSchemaViaCredential is set to true and roleSchemaValuePattern is set, then credential values will be used instead. Do not set roleSchemaViaCredential to true unless roleSchemaValuePattern is set. Parameters roleSchemaViaCredential:boolean boolean

setRoleSchemaViaCredential

back to summary

public void setRoleSchemaViaCredential(boolean roleSchemaViaCredential)

By default, If roleSchemaValuePattern is set, then role and schema values are obtained from principle values; otherwise existing account privileges are used (if any). If roleSchemaViaCredential is set to true and roleSchemaValuePattern is set, then credential values will be used instead.

Do not set roleSchemaViaCredential to true unless roleSchemaValuePattern is set.

Parameters

roleSchemaViaCredential:boolean: boolean

org.hsqldb.auth back to summary

public Class JaasAuthBean.UPCallbackHandler

Class Inheritance

extends Object
implements CallbackHandler

java.lang.Object
org.hsqldb.auth.JaasAuthBean.UPCallbackHandler

All Implemented Interfaces

javax.security.auth.callback.CallbackHandler

Field Summary

Modifier and Type	Field and Description
private char[]	p
private String	u

Constructor Summary

Access	Constructor and Description
public	UPCallbackHandler(String u, String pString)

Method Summary

Modifier and Type	Method and Description
public void	handle(Callback[] callbacks) Implements javax.security.auth.callback.CallbackHandler.handle. Retrieve or display the information requested in the provided Callbacks.

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

Field Detail

p	back to summary
private char[] p

u	back to summary
private String u

Constructor Detail

UPCallbackHandler	back to summary
public UPCallbackHandler(String u, String pString)

Method Detail

handle back to summary

handle	back to summary
public void handle(Callback[] callbacks) throws UnsupportedCallbackException Implements javax.security.auth.callback.CallbackHandler.handle. Doc from javax.security.auth.callback.CallbackHandler.handle. Retrieve or display the information requested in the provided Callbacks. The `handle` method implementation checks the instance(s) of the `Callback` object(s) passed in to retrieve or display the requested information. The following example is provided to help demonstrate what an `handle` method implementation might look like. This example code is for guidance only. Many details, including proper error handling, are left out for simplicity. public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException { for (int i = 0; i < callbacks.length; i++) { if (callbacks[i] instanceof TextOutputCallback) { // display the message according to the specified type TextOutputCallback toc = (TextOutputCallback)callbacks[i]; switch (toc.getMessageType()) { case TextOutputCallback.INFORMATION: System.out.println(toc.getMessage()); break; case TextOutputCallback.ERROR: System.out.println("ERROR: " + toc.getMessage()); break; case TextOutputCallback.WARNING: System.out.println("WARNING: " + toc.getMessage()); break; default: throw new IOException("Unsupported message type: " + toc.getMessageType()); } } else if (callbacks[i] instanceof NameCallback) { // prompt the user for a username NameCallback nc = (NameCallback)callbacks[i]; // ignore the provided defaultName System.err.print(nc.getPrompt()); System.err.flush(); nc.setName((new BufferedReader (new InputStreamReader( System.in, System.getProperty("stdin.encoding")))).readLine()); } else if (callbacks[i] instanceof PasswordCallback) { // prompt the user for sensitive information PasswordCallback pc = (PasswordCallback)callbacks[i]; System.err.print(pc.getPrompt()); System.err.flush(); pc.setPassword(readPassword(System.in)); } else { throw new UnsupportedCallbackException (callbacks[i], "Unrecognized Callback"); } } } // Reads user password from given input stream. private char[] readPassword(InputStream in) throws IOException { // insert code to read a user password from the input stream } Exceptions UnsupportedCallbackException: if the implementation of this method does not support one or more of the Callbacks specified in the `callbacks` parameter.

public void handle(Callback[] callbacks) throws UnsupportedCallbackException

Implements javax.security.auth.callback.CallbackHandler.handle.

Doc from javax.security.auth.callback.CallbackHandler.handle.

Retrieve or display the information requested in the provided Callbacks.

The handle method implementation checks the instance(s) of the Callback object(s) passed in to retrieve or display the requested information. The following example is provided to help demonstrate what an handle method implementation might look like. This example code is for guidance only. Many details, including proper error handling, are left out for simplicity.

public void handle(Callback[] callbacks)
throws IOException, UnsupportedCallbackException {

  for (int i = 0; i < callbacks.length; i++) {
     if (callbacks[i] instanceof TextOutputCallback) {

         // display the message according to the specified type
         TextOutputCallback toc = (TextOutputCallback)callbacks[i];
         switch (toc.getMessageType()) {
         case TextOutputCallback.INFORMATION:
             System.out.println(toc.getMessage());
             break;
         case TextOutputCallback.ERROR:
             System.out.println("ERROR: " + toc.getMessage());
             break;
         case TextOutputCallback.WARNING:
             System.out.println("WARNING: " + toc.getMessage());
             break;
         default:
             throw new IOException("Unsupported message type: " +
                                 toc.getMessageType());
         }

     } else if (callbacks[i] instanceof NameCallback) {

         // prompt the user for a username
         NameCallback nc = (NameCallback)callbacks[i];

         // ignore the provided defaultName
         System.err.print(nc.getPrompt());
         System.err.flush();
         nc.setName((new BufferedReader
                 (new InputStreamReader(
                         System.in,
                         System.getProperty("stdin.encoding")))).readLine());

     } else if (callbacks[i] instanceof PasswordCallback) {

         // prompt the user for sensitive information
         PasswordCallback pc = (PasswordCallback)callbacks[i];
         System.err.print(pc.getPrompt());
         System.err.flush();
         pc.setPassword(readPassword(System.in));

     } else {
         throw new UnsupportedCallbackException
                 (callbacks[i], "Unrecognized Callback");
     }
  }
}

// Reads user password from given input stream.
private char[] readPassword(InputStream in) throws IOException {
   // insert code to read a user password from the input stream
}

Exceptions

UnsupportedCallbackException:: if the implementation of this method does not support one or more of the Callbacks specified in the callbacks parameter.