Table of contents

• Table of contents
• Introduction
• Configure the datasource
• Installation of the Flexible Jdbc Realm
• General Glassfish Security Configuration
• Configure glassfish with the realm definition
• Configure the application with a realm definition

Introduction

FlexibleJdbcRealm is a glassfish security realm and is deployed as an additional jar of the glassfish/payara runtime. This version supports glassfish version 4 and payara application server version 5. There is no difference between this version and earlier versions considering features. So, for older versions of glassfish please use an older version.

Configure the datasource

To start off, a datasource must be configured for accessing the database with user and group information.

Installation of the Flexible Jdbc Realm

• Copy the FlexibleJdbcRealm jar to the glassfish lib directory.

General Glassfish Security Configuration

Examine the settings in Glassfish admin console under Configuration/Security, Typically, you will want to enable default principal to role mapping. This setting means that the role names as used in your application will be identical to those configured in your security realm without a custom mapping of principals to roles.

Configure glassfish with the realm definition

• Add mapping of the security realm to the flexible JDBC realm login module to the login.conf of the glassfish domain you are using. For example:

   PhotoXChangeRealm
              { org.wamblee.glassfish.auth.FlexibleJdbcLoginModule required; }; 

• Configure the security realm in glassfish.
  • In admin console, go to Configuration/Security/Realms.
  • Add a new realm and use the class name org.wamblee.glassfish.auth.FlexibleJdbcRealm as the realm class.
  • Configure the realm as follows

    • Basic Properties: Properties you must set or should always set.

      Property	Description
      jaas.context	The name of the realm as in login.conf and web.xml.
      sql.password	The sql prepared statement that returns the encoded password for a given user. The username is the single parameter of the realm.
      sql.groups	The sql prepared statement which returns the groups based on the username.
      datasource.jndi	The jndi name of the datasource.
      assign-groups	Optional property containing a comma-separated list of groups that any authenticated user is assigned to. You should set this property if your are using default principal to role mapping as mentioned in General Glassfish Security Configuration

    • Password Encoding: How to store the password (including seed, see next item) into the database.

      Property	Description
      charset	Optional property for the character set to be used to convert passwords to byte arrays. This provides the encoding of a string into a byte array as input to the digest method. By default the platform default character set as returned by Charset.defaultCharset().name() is used.
      password.digest	The digest method of the password. The value of this property is an encoding as supported by MessageDigest.getInstance(String). The special value PLAIN must be used to indicate that no encoding will be used. Use for instance MD5 for MD5 digests. Note: In version 0.1, the value MD5HEX was used for MD5, this must now be simply MD5 Note: In version 0.2, the name of this property was password.encoding. In later versions, the digest method and encoding are separately configurable.
      password.encoding	Optional property for the encoding of the digest result (a byte array) into a string. Two encoding methods are supported: HEX: For hexadecimal encoding with padding to 32 characters. HEX:nn: For hexidecimal encoding with padding to the given number of characters. For instance, HEX:40 encodes to hex with padding to 40 characters. TEXT: For encoding as a string. This uses the configured character set for converting the byte array to a string (see charset property) BASE64: For base64 encoding. If this property is not set then the value HEX is used.

    • Seeding: Seeding means modifying the password string before it is encoded. This is an additional security measure to prevent dictionary attacks.

      Property	Description
      sql.seed	Optional property to define the query to retrieve the seed for a given user name. This is a query in prepared statement syntax with one parameter for the user name. If this property is not defined then the empty string will be used for the seed (which is identical to no seeding).
      password.seed.format	Optional property that defined how the seed will be used together with the password. This is a string in java.text.MessageFormat format with the first parameter the password and the second parameter the seed. If this property is not set than the default format is "{0}{1}" meaning that the seed will be appended to the password.

    • Caching: Caching to minimize database access.

      Property	Description
      cache.classname	Optional property for the fully qualified classname of the cache to use. By default the value org.wamblee.glassfish.auth.cache.impl.NoAuthenticationCache is used which means that no caching is done at all. See Caching for more information about available caches.

Configure the application with a realm definition

• Add realm definition to web.xml login-config element (realm-name), For example:

      <login-config>
          <auth-method>FORM</auth-method>
          <realm-name>PhotoXChangeRealm</realm-name>
          <form-login-config>
              <form-login-page>/login.jsp</form-login-page>
              <form-error-page>/loginError.jsp</form-error-page>
          </form-login-config>
      </login-config>