This tutorial describes how to configure security realms to provide authentication and access control for web applications running in Jetty. A realm has a unique name, and is composed of a set of users. Each user has authentication information (for example, a password) and a set of roles associated with him/herself. You can configure one or many different realms depending on your needs.
- Configure a single realm to share common security information across all of your web applications.
- Configure distinct realms to partition your security information webapp by webapp.
A realm–known as a LoginService–is available to all web applications on a Server instance if you define it in a Jetty configuration file, for example $JETTY_HOME/etc/jetty.xml. Here’s an example of defining an in-memory type of LoginService called the HashLoginService (note in Jetty 6 this was called theHashUserRealm):
Test Realm <SystemProperty name="jetty.home" default="."/>/etc/realm.properties 0
Alternatively, you can define a LoginService for just a single web application in a context file. Here’s how to define the same HashLoginService, but inside a context xml file instead of a configuration file:
/test <SystemProperty name="jetty.home" default="."/>/webapps/test Test Realm /etc/realm.properties
Jetty provides a number of different LoginService types from which you can choose.
This LoginService is a simple realm whose authentication and authorization information is stored in a properties file. Each line in the file contains a username, a password, and zero or more role assignments. The format is:
username: password[,rolename ...]
- username is the user’s unique identity;
- password is the user’s (possibly obfuscated or MD5 encrypted) password;
- rolename is the user’s role.
admin: CRYPT:ad1ks..kc.1Ug,server-administrator,content-administrator,admin other: OBF:1xmk1w261u9r1w1c1xmq guest: guest,read-only
You configure the HashLoginService with a name and a reference to the location of the properties file:
Test Realm <SystemProperty name="jetty.home" default="."/>/etc/realm.properties
You can also configure it to check the properties file regularly for changes and reload when changes are detected. The reloadInterval is in seconds:
Test Realm <SystemProperty name="jetty.home" default="."/>/etc/realm.properties 5
In this implementation, authentication and role information is stored in a database accessed via JDBC. A properties file defines the JDBC connection and database table information. Here is an example of a properties file for this realm implementation:
jdbcdriver = org.gjt.mm.mysql.Driver url = jdbc:mysql://localhost/jetty username = jetty password = jetty usertable = users usertablekey = id usertableuserfield = username usertablepasswordfield = pwd roletable = roles roletablekey = id roletablerolefield = role userroletable = user_roles userroletableuserkey = user_id userroletablerolekey = role_id cachetime = 300
The format of the database tables is (pseudo-sql):
users ( id integer PRIMARY KEY, username varchar(100) NOT NULL UNIQUE KEY, pwd varchar(50) NOT NULL );
user_roles ( user_id integer NOT NULL, role_id integer NOT NULL, UNIQUE KEY (user_id, role_id), INDEX(user_id) );
roles ( id integer PRIMARY KEY, role varchar(100) NOT NULL UNIQUE KEY );
- users is a table containing one entry for every user consisting of:
- id–the unique identity of a user
- user–the name of the user
- pwd–the user’s password (possibily obfuscated or MD5 encrypted)
- user-roles is a table containing one row for every role granted to a user:
- user_id–the unique identity of the user
- role_id–the role for a user
- roles is a a table containing one role for every role in the system:
- id–the unique identifier of a role
- role–a human-readable name for a role
If you want to use obfuscated, MD5 hashed or encrypted passwords the ‘pwd’ column of the ‘users’ table must be large enough to hold the obfuscated, hashed or encrypted password text plus the appropriate prefix.
You define a JDBCLoginService with the name of the realm and the location of the properties file describing the database:
Test JDBC Realm etc/jdbcRealm.properties
See Java Authentication and Authorization Service (JAAS) tutorial for additional information about configuring security realms.