Module org.hsqldb
Package org.hsqldb.auth

## Class JaasAuthBean

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

- All Implemented Interfaces:
    `AuthFunctionBean`

      public class JaasAuthBean
      extends java.lang.Object
      implements AuthFunctionBean

  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.

  Since:
    2.5.0
  Author:
    Blaine Simpson (blaine dot simpson at admc dot com)
  See Also:
    `AuthFunctionBean`, `NameCallback`, `PasswordCallback`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `JaasAuthBean.UPCallbackHandler` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `JaasAuthBean()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.String[]` | `authenticate​(java.lang.String userName, java.lang.String password)` | 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.
    `void` | `init()` |
    `void` | `setApplicationKey​(java.lang.String applicationKey)` | Set the key into the JAAS runtime configuration.
    `void` | `setRoleSchemaValuePattern​(java.util.regex.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.
    `void` | `setRoleSchemaValuePatternString​(java.lang.String patternString)` | String wrapper for method setRoleSchemaValuePattern(Pattern) Use the (x?) Pattern constructs to set options.
    `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).

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### JaasAuthBean

          public JaasAuthBean()

  - ### Method Detail

    - #### setRoleSchemaViaCredential

          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

    - #### init

          public void init()

      Throws:
        `java.lang.IllegalStateException` - if any required setting has not been set.

    - #### setApplicationKey

          public void setApplicationKey​(java.lang.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` - key

    - #### setRoleSchemaValuePattern

          public void setRoleSchemaValuePattern​(java.util.regex.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.

      1. 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).
      2. 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
      See Also:
        `Matcher.matches()`

    - #### setRoleSchemaValuePatternString

          public void setRoleSchemaValuePatternString​(java.lang.String patternString)

      String wrapper for method setRoleSchemaValuePattern(Pattern) Use the (x?) Pattern constructs to set options.
      Parameters:
        `patternString` - pattern
      Throws:
        `java.util.regex.PatternSyntaxException` - exception
      See Also:
        `setRoleSchemaValuePattern(Pattern)`

    - #### authenticate

          public java.lang.String[] authenticate​(java.lang.String userName,
                                                 java.lang.String password)
                                          throws DenyException

      Description copied from interface: `AuthFunctionBean`
      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.
      Specified by:
        `authenticate` in interface `AuthFunctionBean`
      Parameters:
        `userName` - String
        `password` - String
      Returns:
        null or String[] according to the contract of HyperSQL authentication function contract, except that the role/schema list is returned as a String[] instead of a java.sql.Array.
      Throws:
        `DenyException`