Using the JDBC Realm for User Authentication

An authentication realm, sometimes called a security policy domain or security domain, is a scope over which an application server defines and enforces a common security policy. A realm contains a collection of users, who may or may not be assigned to a group. GlassFish Server comes preconfigured with the file, certificate, and administration realms. An administrator can also set up LDAP, JDBC, digest, or custom realms.

An application can specify in its deployment descriptor which realm to use. If the application does not specify a realm, GlassFish Server uses its default realm, the file realm. If an application specifies that a JDBC realm is to be used for user authentication,GlassFish Server will retrieve user credentials from a database. The application server uses the database information and the enabled JDBC realm option in the configuration file.

A database provides an easy way to add, edit, or delete users at runtime and enables users to create their own accounts without any administrative assistance. Using a database also has an additional benefit, providing a place to securely store any extra user information. A realm can be thought of as a database of user names and passwords that identify valid users of a web application or set of web applications with an enumeration of the list of roles associated with each valid user. Access to specific web application resources is granted to all users in a particular role, instead of enumerating a list of associated users. A user name can have any number of roles associated with it.

Two of the tutorial case studies, Chapter 52, Duke's Tutoring Case Study Example and Chapter 53, Duke's Forest Case Study Example, use the JDBC realm for user authentication. Where appropriate, reference will be made to one or both of these examples.

To Configure a JDBC Authentication Realm

GlassFish Server enables administrators to specify a user’s credentials (user name and password) in the JDBC realm instead of in the connection pool. This prevents other applications from browsing the database tables for user credentials. By default, storing passwords as clear text is not supported in the JDBC realm. Under normal circumstances, passwords should not be stored as clear text.

1. Create the database tables in which user credentials for the realm will be stored.

   How you create the database tables depends on the database you are using. Duke’s Forest uses an Ant task, create-tables, in the build.xml file for the Entities project. The task executes an SQL script, create.sql, that creates the FOREST.PERSON, FOREST.GROUPS, and FOREST.PERSON_GROUPS database tables, as shown below:

   CREATE TABLE "FOREST"."PERSON"
   (
     ID int NOT NULL PRIMARY KEY GENERATED ALWAYS AS IDENTITY 
         (START WITH 1, INCREMENT BY 1),
     FIRSTNAME varchar(50) NOT NULL,
     LASTNAME varchar(100) NOT NULL,
     EMAIL varchar(45) NOT NULL UNIQUE,
     ADDRESS varchar(45) NOT NULL,
     CITY varchar(45) NOT NULL,
     PASSWORD varchar(100),
     DTYPE varchar(31)
   )
   ;
   CREATE UNIQUE INDEX SQL_PERSON_EMAIL_INDEX ON "FOREST"."PERSON"(EMAIL)
   ;
   CREATE UNIQUE INDEX SQL_PERSON_ID_INDEX ON "FOREST"."PERSON"(ID)
   ;
   CREATE TABLE "FOREST"."GROUPS"
   (
      ID int NOT NULL PRIMARY KEY GENERATED ALWAYS AS IDENTITY 
          (START WITH 1, INCREMENT BY 1),
      NAME varchar(50) NOT NULL,
      DESCRIPTION varchar(300)
   )
   ;
   CREATE TABLE "FOREST"."PERSON_GROUPS"
   (
     GROUPS_ID int NOT NULL,
     EMAIL varchar(45) NOT NULL
   )
   ;
   ALTER TABLE "FOREST"."PERSON_GROUPS"
   ADD CONSTRAINT FK_PERSON_GROUPS_PERSON
   FOREIGN KEY (EMAIL)
   REFERENCES "FOREST"."PERSON"(EMAIL)
   ;
   ALTER TABLE "FOREST"."PERSON_GROUPS"
   ADD CONSTRAINT FK_PERSON_GROUPS_GROUPS
   FOREIGN KEY (GROUPS_ID)
   REFERENCES "FOREST"."GROUPS"(ID)
   ;
   CREATE INDEX SQL_PERSONGROUPS_EMAIL_INDEX ON "FOREST"."PERSON_GROUPS"(EMAIL)
   ;
   CREATE INDEX SQL_PERSONGROUPS_ID_INDEX ON "FOREST"."PERSON_GROUPS"(GROUPS_ID)
   ;

   The Duke’s Tutoring case study uses a singleton bean, ConfigBean, to create its database tables, instead of using SQL commands.

2. Add user credentials to the database tables you created.

   How you add user credentials to the database tables depends on the database that you are using. Duke’s Forest uses an Ant task. The create-tables Ant task for Duke’s Forest adds the user credentials to the tables created in the previous step:

   INSERT INTO "FOREST"."PERSON" (FIRSTNAME,LASTNAME,EMAIL,ADDRESS,CITY,
   PASSWORD,DTYPE) VALUES ('Robert','Exampler','robert@example.com',
   'Example street','San Francisco','81dc9bdb52d04dc20036dbd8313ed055',
   'Customer');
   INSERT INTO "FOREST"."PERSON" (FIRSTNAME,LASTNAME,EMAIL,ADDRESS,CITY,
   PASSWORD,DTYPE) VALUES ('Admin','Admin','admin@example.com','Example street',
   'Belmont','81dc9bdb52d04dc20036dbd8313ed055','Administrator');
   INSERT INTO "FOREST"."PERSON" (FIRSTNAME,LASTNAME,EMAIL,ADDRESS,CITY,
   PASSWORD,DTYPE) VALUES ('Jack','Frost','jack@example.com','Example Blvd',
   'San Francisco','81dc9bdb52d04dc20036dbd8313ed055','Customer');
   INSERT INTO "FOREST"."PERSON" (FIRSTNAME,LASTNAME,EMAIL,ADDRESS,CITY,
   PASSWORD,DTYPE) VALUES ('Payment','User','paymentUser@dukesforest.com',
   '-','-','58175e1df62779046a3a4e2483575937','Customer');
   
   INSERT INTO "FOREST"."GROUPS" (NAME, DESCRIPTION) 
   VALUES ('USERS', 'Users of the store');
   INSERT INTO "FOREST"."GROUPS" (NAME, DESCRIPTION) 
   VALUES ('ADMINS', 'Administrators of the store');
   
   INSERT INTO "FOREST"."PERSON_GROUPS" (GROUPS_ID,EMAIL) 
   VALUES (1,'robert@example.com');
   INSERT INTO "FOREST"."PERSON_GROUPS" (GROUPS_ID,EMAIL) 
   VALUES (2,'admin@example.com');
   INSERT INTO "FOREST"."PERSON_GROUPS" (GROUPS_ID,EMAIL) 
   VALUES (1,'jack@example.com');
   INSERT INTO "FOREST"."PERSON_GROUPS" (GROUPS_ID,EMAIL) 
   VALUES (1,'paymentUser@dukesforest.com');

   The Duke’s Tutoring case study uses a singleton bean, ConfigBean, to populate its database tables, instead of using SQL commands.

3. Create a JDBC connection pool for the database.

   Duke’s Forest uses an Ant task, create-forest-pool, to create the derby_net_forest_forestPool JDBC connection pool for the database:

   <target name="create-forest-pool"
       description="create JDBC connection pool">
       <antcall target="create-jdbc-connection-pool">
           <param name="pool.name" value="derby_net_forest_forestPool" />
       </antcall>
   </target>

   You can also use the Administration Console or the command line to create a connection pool.

4. Create a JDBC resource for the database.

   Duke’s Forest uses an Ant task, create-forest-resource, to create the jdbc/forest JDBC resource for the database:

   <target name="create-forest-resource" depends="create-forest-pool"
       description="create JDBC resource">
       <antcall target="create-jdbc-resource">
           <param name="pool.name" value="derby_net_forest_forestPool" />
           <param name="jdbc.resource.name" value="jdbc/forest" />
       </antcall>
   </target>

   You can also use the Administration Console or the command line to create a JDBC resource.

5. Create a realm.

   Duke’s Forest uses an Ant task, create-forest-realm, to create jdbcRealm, the JDBC realm used for user authentication:

   <target name="create-forest-realm" depends="create-forest-resource"
       description="create JDBC realm">
       <antcall target="create-jdbc-realm">
           <param name="jdbc.resource.name" value="jdbc/forest" />
           <param name="jdbc.realm.name" value="jdbcRealm" />
           <param name="user.table.name" value="forest.PERSON" />
           <param name="user.name.column" value="email" />
           <param name="password.column" value="password" />
           <param name="group.table" value="forest.GROUPS" />
           <param name="group.name.column" value="name" />
           <param name="assign.groups" value="USERS,ADMINS" />
           <param name="digest.algorithm" value="MD5" />
       </antcall>
   </target>

   This task associates the resource with the realm, defines the tables and columns for users and groups used for authentication, and defines the digest algorithm that will be used for storing passwords in the database.

   You can also use the Administration Console or the command line to create a realm.

6. Modify the deployment descriptor for your application to specify the JDBC realm:

   • For an enterprise application in an EAR file, modify the glassfish-application.xml file.

   • For a web application in a WAR file, modify the web.xml file.

   • For an enterprise bean in an EJB JAR file, modify the glassfish-ejb-jar.xml file.

   For example, for the Duke’s Forest application, the web.xml file specifies the jdbcRealm realm:

   <login-config>
       <auth-method>FORM</auth-method>
       <realm-name>jdbcRealm</realm-name>
       <form-login-config>
           <form-login-page>/login.xhtml</form-login-page>
           <form-error-page>/login.xhtml</form-error-page>
       </form-login-config>
   </login-config>
   <security-constraint>
       <web-resource-collection>
           <web-resource-name>Secure Pages</web-resource-name>
           <description/>
           <url-pattern>/admin/*</url-pattern>
       </web-resource-collection>
       <auth-constraint>
           <role-name>ADMINS</role-name>
       </auth-constraint>
   </security-constraint> 

   Form-based login is specified for all web pages under /admin. Access to those pages will be allowed only to users in the ADMINS role.

7. Assign security roles to users or groups of users in the realm.

   To assign a security role to a group or to a user, add a security-role-mapping element to the application server-specific deployment descriptor, in this case glassfish-web.xml:

   <security-role-mapping>
       <role-name>USERS</role-name>
       <group-name>USERS</group-name>
   </security-role-mapping>
   <security-role-mapping>
       <role-name>ADMINS</role-name>
       <group-name>ADMINS</group-name>
   </security-role-mapping>

   Since GlassFish Server users are assigned to groups during the user creation process, this is more efficient than mapping security roles to individual users.