Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Jetty/Tutorial/JAAS"

 
(27 intermediate revisions by 6 users not shown)
Line 2: Line 2:
 
| introduction =  
 
| introduction =  
  
Using JAAS with jetty is very simply a matter of declaring a org.mortbay.jetty.plus.jaas.JAASUserRealm, creating a jaas login module configuration file and specifying it on the jetty run line.  
+
{{Jetty Redirect|http://www.eclipse.org/jetty/documentation/current/jaas-support.html}}
 +
 
 +
Using JAAS with Jetty is a matter of completing the following tasks:
 +
 
 +
[[#Configuring a JAASLoginService]]
 +
 
 +
[[#Declaring an org.eclipse.jetty.plus.jaas.JAASLoginService]]
 +
 
 +
[[#Creating a JAAS login module configuration file]]
 +
 
 +
[[#Specifying the JAAS login module configuration file on the Jetty run line]]
 +
 
 +
You should also refer to the JAAS [http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials Tutorials] and [http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html Reference Guide].
  
 
| details =
 
| details =
Let's look at an example.
+
The following sections explain how to configure Jetty with JAAS:
  
=== Step 1 ===
+
=== Configuring a JAASLoginService ===
 +
 
 +
Configure a Jetty <tt>org.eclipse.jetty.plus.jaas.JAASLoginService</tt> to match the ''realm-name'' in your <tt>web.xml</tt> file. For example, if the <tt>web.xml</tt> contains a realm called "Test JAAS Realm":
  
Configure a Jetty org.mortbay.jetty.plus.jaas.JAASUserRealm to match the &lt;realm-name&gt; in your web.xml file. For example, if the web.xml contains a realm called "xyzrealm":
 
 
<source lang="xml">
 
<source lang="xml">
 
<login-config>
 
<login-config>
 
   <auth-method>FORM</auth-method>
 
   <auth-method>FORM</auth-method>
   <realm-name>xyzrealm</realm-name>
+
   <realm-name>Test JAAS Realm</realm-name>
 
   <form-login-config>
 
   <form-login-config>
 
     <form-login-page>/login/login</form-login-page>
 
     <form-login-page>/login/login</form-login-page>
Line 21: Line 34:
 
</source>
 
</source>
  
Then the following JAASUserRealm would be declared in a Jetty configuration file:
+
=== Declaring an org.eclipse.jetty.plus.jaas.JAASLoginService  ===
 +
 
 +
Next declare the following JAASLoginService in a Jetty configuration file:
 +
 
 
<source lang="xml">
 
<source lang="xml">
<Call name="addUserRealm">
+
    <Call name="addBean">
  <Arg>
+
      <Arg>
    <New class="org.mortbay.jetty.plus.jaas.JAASUserRealm">
+
          <New class="org.eclipse.jetty.plus.jaas.JAASLoginService">
      <Set name="name">xyzrealm</Set>
+
          <Set name="Name">Test JAAS Realm</Set>
       <Set name="LoginModuleName">xyz</Set>
+
          <Set name="LoginModuleName">xyz</Set>
 +
          </New>
 +
       </Arg>
 +
    </Call>
 +
</source>
 +
 
 +
Alternatively, of course, you can set this up in a context XML file that configures a web app:
 +
<source lang="xml">
 +
  <Set name="securityHandler">
 +
    <New class="org.eclipse.jetty.security.ConstraintSecurityHandler">
 +
    <Set name="loginService">
 +
      <New class="org.eclipse.jetty.plus.jaas.JAASLoginService">
 +
        <Set name="name">Test JAAS Realm</Set>
 +
        <Set name="loginModuleName">xyz</Set>
 +
      </New>
 +
    </Set>
 
     </New>
 
     </New>
   </Arg>
+
   </Set>
</Call>
+
 
</source>
 
</source>
{{warning| IMPORTANT: It is imperative that the contents of the &lt;realm-name&gt; and the &lt;Set name="name"&gt; of the JAASUserRealm instance are _exactly_ the same}}
 
  
=== Step 2 ===
+
{{warning|It is imperative that the ''realm-name'' element in web.xml file is ''exactly'' the same as the value of the ''name'' property of the JAASLoginService instance.}}
 +
 
 +
=== Creating a JAAS login module configuration file ===
  
 
Set up your LoginModule in a configuration file, following the [http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/login/Configuration.html syntax rules]:
 
Set up your LoginModule in a configuration file, following the [http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/login/Configuration.html syntax rules]:
Line 42: Line 73:
 
     };
 
     };
 
</source>
 
</source>
{{warning|IMPORTANT: It is imperative that the application name to the left of the \{ is _exactly_ the same as the &lt;Set name="LoginModuleName"&lt;}}
+
{{warning|It is imperative that the application name to the left of the opening brace is ''exactly'' the same as the value of the ''LoginModuleName'' property specified above.}}
  
 +
Read the [http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/LoginConfigFile.html JAAS tutorial] for more information on configuration options for LoginModules.
  
=== Step 3 ===
+
=== Specifying the JAAS login module configuration file on the Jetty run line ===
  
Invoke jetty with the jaas configuration file you created in step 2:
+
Invoke Jetty with the JAAS configuration file you created above:
 
<source lang="bash">
 
<source lang="bash">
 
> java -Djava.security.auth.login.config=mylogin.conf -jar start.jar etc/myjetty.xml
 
> java -Djava.security.auth.login.config=mylogin.conf -jar start.jar etc/myjetty.xml
 
</source>
 
</source>
  
== A Closer Look at the JAASUserRealm ==
+
== Fine Tuning the JAASLoginService ==
  
To allow the greatest degree of flexibility in using JAAS with web applications, the JAASUserRealm supports a couple of configuration options. Note that you don't ordinarily need to set these explicitly, as Jetty has defaults which will work in 99% of cases. However, should you need to, you can configure:
+
To allow the greatest degree of flexibility in using JAAS with web applications, the JAASLoginService supports additional configuration options. You don't ordinarily need to set these explicitly, as Jetty has defaults which work in 99% of cases. However, should you need to, you can configure:
  
* a policy for role-based authorization (Default: org.mortbay.jetty.plus.jaas.StrictRoleCheckPolicy)
+
* A policy for role-based authorization (Default: <tt>org.eclipse.jetty.plus.jaas.StrictRoleCheckPolicy</tt>).
* a [http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/callback/CallbackHandler.html CallbackHandler] (Default: org.mortbay.jetty.plus.jaas.callback.DefaultCallbackHandler)
+
* A [http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/callback/CallbackHandler.html CallbackHandler].
* a list of classnames for the [http://java.sun.com/j2se/1.4.2/docs/api/java/security/Principal.html Principal] implementation that equate to a user role (Default: org.mortbay.jetty.plus.jaas.JAASRole)
+
* A list of classnames for the [http://java.sun.com/j2se/1.4.2/docs/api/java/security/Principal.html Principal] implementation that equate to a user role (Default: <tt>org.eclipse.jetty.plus.jaas.JAASRole</tt>).
  
Here's an example of setting each of these (to their default values):
+
Here's an example that sets each of these:
 
<source lang="xml">
 
<source lang="xml">
<New class="org.mortbay.jetty.plus.jaas.JAASUserRealm">
+
<New class="org.eclipse.jetty.plus.jaas.JAASLoginService">
 
   <Set name="Name">xyzrealm</Set>
 
   <Set name="Name">xyzrealm</Set>
 
   <Set name="LoginModuleName">xyz</Set>
 
   <Set name="LoginModuleName">xyz</Set>
 
   <Set name="RoleCheckPolicy">
 
   <Set name="RoleCheckPolicy">
     <New class="org.mortbay.jetty.plus.jaas.StrictRoleCheckPolicy"/>
+
     <New class="org.eclipse.jetty.plus.jaas.StrictRoleCheckPolicy"/>  <!-- default -->
 
   </Set>
 
   </Set>
 
   <Set name="CallbackHandlerClass">
 
   <Set name="CallbackHandlerClass">
     org.mortbay.jetty.plus.jaas.callback.DefaultCallbackHandler
+
     com.acme.MyCallbackHandler
 
   </Set>
 
   </Set>
 
   <Set name="roleClassNames">
 
   <Set name="roleClassNames">
 
     <Array type="java.lang.String">
 
     <Array type="java.lang.String">
       <Item>org.mortbay.jetty.plus.jaas.JAASRole</Item>
+
       <Item>org.eclipse.jetty.plus.jaas.JAASRole</Item> <!-- default -->
 
     </Array>
 
     </Array>
 
   </Set>
 
   </Set>
Line 79: Line 111:
 
</source>
 
</source>
  
=== RoleCheckPolicy ===
+
=== Understanding the RoleCheckPolicy ===
  
The RoleCheckPolicy must be an implementation of the org.mortbay.jetty.plus.jaas.RoleCheckPolicy interface and its purpose is to help answer the question "is User X in Role Y" for role-based authorization requests. The default implementation distributed with jetty is the org.mortbay.jetty.plus.jaas.StrictRoleCheckPolicy, which will assess a user as having a particular role iff that role is at the top of the stack of roles that have been temporarily pushed onto the user or if the user has no temporarily assigned roles, the role is amongst those configured for the user.
+
The RoleCheckPolicy must be an implementation of the <tt>org.eclipse.jetty.plus.jaas.RoleCheckPolicy</tt> interface, and its purpose is to help answer the question "is User X in Role Y?" for role-based authorization requests. The default implementation distributed with Jetty is the <tt>org.eclipse.jetty.plus.jaas.StrictRoleCheckPolicy</tt>, which assesses a user as having a particular role if that role is at the top of the stack of roles that have been temporarily pushed onto the user, or if the user has no temporarily assigned roles, the role is among those configured for the user.
  
Roles can be temporarily assigned to a user programmatically by using the pushRole(String rolename) method of the org.mortbay.jetty.plus.jaas.JAASUserPrincipal class.
+
You can temporarily assign roles to a user programmatically by using the <tt>pushRole(String rolename)</tt> method of the <tt>org.eclipse.jetty.plus.jaas.JAASUserPrincipal</tt> class.
  
For the majority of webapps, the default StrictRoleCheckPolicy will be quite adequate, however you may provide your own implementation and set it on your JAASUserRealm instance.
+
For the majority of webapps, the default StrictRoleCheckPolicy is adequate, but you can provide your own implementation and set it on your tt>JAASLoginService</tt> instance.
  
=== CallbackHandler ===
+
=== Using the CallbackHandler ===
  
 
A [http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/callback/CallbackHandler.html CallbackHandler] is responsible for interfacing with the user to obtain usernames and credentials to be authenticated.
 
A [http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/callback/CallbackHandler.html CallbackHandler] is responsible for interfacing with the user to obtain usernames and credentials to be authenticated.
  
Jetty ships with the org.mortbay.jetty.plus.jaas.DefaultCallbackHandler which interfaces the information contained in the [http://jetty.mortbay.org/apidocs/javax/servlet/http/HttpServletRequest.html request] to the [http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/callback/Callback.html Callbacks] that are requested by [http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/spi/LoginModule.html LoginModules]. You can replace this default with your own implementation if you have specific requirements not covered by the default.
+
Jetty ships with a CallbackHandler which interfaces the information contained in the [http://download.oracle.com/javaee/5/api/javax/servlet/http/HttpServletRequest.html request] to the [http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/callback/Callback.html Callbacks] that [http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/spi/LoginModule.html LoginModules] requests. You can replace this default with your own implementation if you have specific requirements not covered by the default.
  
=== Role Principal Implementation Class ===
+
=== Configuring a Role Principal Implementation Class ===
  
When LoginModules authenticate a user, they usually also gather all of the roles that a user has and place them inside the JAAS [http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/Subject.html Subject]. As LoginModules are free to use their own implementation of the JAAS [http://java.sun.com/j2se/1.4.2/docs/api/java/security/Principal.html Principal] to put into the Subject, jetty needs to know which Principals represent the user and which represent his/her roles when performing authorization checks on &lt;security-constraint&gt;s. The example LoginModules that ship with jetty all use the org.mortbay.jetty.plus.jaas.JAASRole class. However, if you have plugged in some other LoginModules, you must configure the classnames of their role Principal implementations.
+
When LoginModules authenticate a user, they usually also gather all of the roles that a user has and place them inside the JAAS [http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/Subject.html Subject]. As LoginModules are free to use their own implementation of the JAAS [http://java.sun.com/j2se/1.4.2/docs/api/java/security/Principal.html Principal] to put into the Subject, Jetty needs to know which Principals represent the user and which represent his/her roles when performing authorization checks on ''security-constraints''. The example LoginModules that ship with jetty all use the <tt>org.mortbay.jetty.plus.jaas.JAASRole</tt> class. However, if you have plugged in some other LoginModules, you must configure the classnames of their role Principal implementations.
  
=== Sample Login Modules ===
+
== Examining Sample Login Modules ==
  
 
At the time of writing, Jetty provides four sample LoginModule implementations:
 
At the time of writing, Jetty provides four sample LoginModule implementations:
* org.mortbay.jetty.plus.jaas.spi.JDBCLoginModule
+
* org.eclipse.jetty.plus.jaas.spi.JDBCLoginModule
* org.mortbay.jetty.plus.jaas.spi.PropertyFileLoginModule
+
* org.eclipse.jetty.plus.jaas.spi.PropertyFileLoginModule
* org.mortbay.jetty.plus.jaas.spi.DataSourceLoginModule
+
* org.eclipse.jetty.plus.jaas.spi.DataSourceLoginModule
* org.mortbay.jetty.plus.jaas.ldap.LdapLoginModule
+
* org.eclipse.jetty.plus.jaas.ldap.LdapLoginModule
  
 
We'll take a look at all of these, but first, a word about password handling in Jetty, as it applies to all LoginModules.
 
We'll take a look at all of these, but first, a word about password handling in Jetty, as it applies to all LoginModules.
  
=== Passwords/Credentials ===
+
=== Understanding Passwords/Credentials ===
  
Passwords can be stored in clear text, obfuscated or checksummed.  The class org.eclipse.jetty.http.security.Password should be used to generate all varieties of passwords,the output from which can be cut and pasted into property files or entered into database tables.
+
Passwords can be stored in clear text, obfuscated or checksummed.  Use the class <tt>org.eclipse.jetty.http.security.Password</tt> to generate all varieties of passwords, the output from which you can cut and paste into property files or enter into database tables.
 
<source lang="bash">
 
<source lang="bash">
 
> java -cp lib/jetty.jar org.eclipse.jetty.http.security.Password
 
> java -cp lib/jetty.jar org.eclipse.jetty.http.security.Password
Line 119: Line 151:
 
CRYPT:me/ks90E221EY
 
CRYPT:me/ks90E221EY
 
</source>
 
</source>
Read more on [Securing Passwords].
+
Read more on [[Jetty/Howto/Secure_Passwords|securing passwords]].
  
 
=== JDBCLoginModule ===
 
=== JDBCLoginModule ===
  
The JDBCLoginModule stores user passwords and roles in a database that are accessed via JDBC calls. You can configure the JDBC connection information, as well as the names of the table and columns storing the username and credential, and the name of the table and columns storing the roles.
+
The JDBCLoginModule stores user passwords and roles in a database that is accessed via JDBC calls. You can configure the JDBC connection information, as well as the names of the table and columns storing the username and credential, and the name of the table and columns storing the roles.
  
 
Here is an example login module configuration file entry for it using an HSQLDB driver:
 
Here is an example login module configuration file entry for it using an HSQLDB driver:
 
<source lang="text">
 
<source lang="text">
 
jdbc {
 
jdbc {
      org.mortbay.jetty.plus.jaas.spi.JDBCLoginModule required
+
        org.eclipse.jetty.plus.jaas.spi.JDBCLoginModule required
      debug="true"
+
        debug="true"
      dbUrl="jdbc:hsqldb:."
+
        dbUrl="jdbc:hsqldb:."
      dbUserName="sa"
+
        dbUserName="sa"
      dbDriver="org.hsqldb.jdbcDriver"
+
        dbPassword="secret"
      userTable="myusers"
+
        dbDriver="org.hsqldb.jdbcDriver"
      userField="myuser"
+
        userTable="myusers"
      credentialField="mypassword"
+
        userField="myuser"
      userRoleTable="myuserroles"
+
        credentialField="mypassword"
      userRoleUserField="myuser"
+
        userRoleTable="myuserroles"
      userRoleRoleField="myrole";
+
        userRoleUserField="myuser"
      };
+
        userRoleRoleField="myrole";
 +
    };
 
</source>
 
</source>
  
There is no particular schema required for the database tables storing the authentication and role information. The properties userTable, userField, credentialField, userRoleTable, userRoleUserField, userRoleRoleField configure the names of the tables and the columns within them that are used to format the following queries:
+
There is no particular schema required for the database tables storing the authentication and role information. The properties ''userTable'', ''userField'', c''redentialField'', ''userRoleTable'', ''userRoleUserField'', ''userRoleRoleField'' configure the names of the tables and the columns within them that are used to format the following queries:
 
<source lang="sql">
 
<source lang="sql">
 
select <credentialField> from <userTable> where <userField> =?
 
select <credentialField> from <userTable> where <userField> =?
Line 148: Line 181:
 
</source>
 
</source>
  
Credential and role information is lazily read from the database when a previously unauthenticated user requests authentication. Note that this information is only cached for the length of the authenticated session. When the user logs out or the session expires, the information is flushed from memory.
+
Credential and role information is lazily read from the database when a previously unauthenticated user requests authentication. This information is only cached for the length of the authenticated session. When the user logs out or the session expires, the information is flushed from memory.
  
Note that passwords can be stored in the database in plain text or encoded formats, using the [org.mortbay.jetty.security.Password|#pwd] class.
+
{{note|You can store passwords in the database in plain text or encoded formats, using the Jetty [[Jetty/Howto/Secure_Passwords|password utility]].}}
  
 
=== DataSourceLoginModule ===
 
=== DataSourceLoginModule ===
  
Similar to the JDBCLoginModule, but this LoginModule uses a DataSource to connect to the database instead of a jdbc driver. The DataSource is obtained by doing a jndi lookup on java:comp/env/$\{dnJNDIName\}
+
Similar to the JDBCLoginModule, but this LoginModule uses a DataSource to connect to the database instead of a JDBC driver. The DataSource is obtained by doing a JNDI lookup on <tt>java:comp/env/$\{dnJNDIName\}</tt>.
  
Here is a sample login module configuration for it:
+
Here is a sample login module configuration for the DataSourceLoginModule:
<source lang="text">ds {
+
<source lang="text">
    org.mortbay.jetty.plus.jaas.spi.DataSourceLoginModule required
+
ds {
    debug="true"
+
      org.eclipse.jetty.plus.jaas.spi.DataSourceLoginModule required
    dbJNDIName="ds"
+
      debug="true"
    userTable="myusers"
+
      dbJNDIName="ds"
    userField="myuser"
+
      userTable="myusers"
    credentialField="mypassword"
+
      userField="myuser"
    userRoleTable="myuserroles"
+
      credentialField="mypassword"
    userRoleUserField="myuser"
+
      userRoleTable="myuserroles"
    userRoleRoleField="myrole";
+
      userRoleUserField="myuser"
    };
+
      userRoleRoleField="myrole";
 +
  };
 
</source>
 
</source>
  
Line 175: Line 209:
 
<source lang="text">
 
<source lang="text">
 
props {
 
props {
        org.mortbay.jetty.plus.jaas.spi.PropertyFileLoginModule required
+
          org.eclipse.jetty.plus.jaas.spi.PropertyFileLoginModule required
        debug="true"
+
          debug="true"
        file="/somewhere/somefile.props";
+
          file="/somewhere/somefile.props";
 
       };
 
       };
 
</source>
 
</source>
  
The file parameter is the location of a properties file of the same format as the etc/realm.properties example file. The format is:
+
The file parameter is the location of a properties file of the same format as the <tt>etc/realm.properties</tt> example file. The format is:
 
<source lang="text"><username>: <password>[,<rolename> ...]
 
<source lang="text"><username>: <password>[,<rolename> ...]
 
</source>
 
</source>
Line 195: Line 229:
 
=== LdapLoginModule ===
 
=== LdapLoginModule ===
  
Note that the LdapLoginModule ships in a separate jar, in $JETTY-HOME/lib/ext/jetty-ldap-jaas.jar. It requires JDK1.5 or above.
+
The LdapLoginModule ships in a separate jar, in <tt>$JETTY-HOME/lib/ext/jetty-ldap-jaas.jar</tt>. It requires JDK1.5 or above.
  
 
<source lang="text">
 
<source lang="text">
  
 
ldaploginmodule {
 
ldaploginmodule {
   org.mortbay.jetty.plus.jaas.spi.LdapLoginModule required
+
   org.eclipse.jetty.plus.jaas.spi.LdapLoginModule required
 
   debug="true"
 
   debug="true"
 
   contextFactory="com.sun.jndi.ldap.LdapCtxFactory"
 
   contextFactory="com.sun.jndi.ldap.LdapCtxFactory"
Line 221: Line 255:
 
</source>
 
</source>
  
=== Writing Your Own ===
+
==== Configuring the Role Principal Implementation Class for the LdapLoginModule<ref>Jay Jaeger, IT Management Consultant at the State of Wisconsin, provided this example. In turn, Jaeger writes, "I would never have figured this out had it not been for the article at
 +
http://mail-archives.apache.org/mod_mbox/karaf-issues/201012.mbox/%3C30176778.74721292097241071.JavaMail.jira@thor%3E ." </ref>====
  
If you want to implement your own custom LoginModule, there are two classes to be familiar with:
+
The LdapLoginModule does not deal with the situation of user -> some group -> role group, as it assigns users directly to the role group. If you want to specify role occupants by groups within an organization, you need the ability to sort them in this way. The following example shows how to do so by configuring ''RoleClassNames'' information. This example implements [http://waffle.codeplex.com/ WAFFLE], which lets you run Jetty under Windows with Active Directory.
 +
 
 +
<source lang="xml">
 +
<New class="org.mortbay.jetty.plus.jaas.JAASUserRealm">
 +
  <Set name="name">MyTestRealm</Set>
 +
  <Set name="LoginModuleName">Jaas</Set>
 +
  <Set name="RoleClassNames">
 +
    <Array type="java.lang.String">
 +
      <Item>waffle.jaas.UserPrincipal</Item>
 +
      <Item>waffle.jaas.RolePrincipal</Item>
 +
    </Array>
 +
  </Set>
 +
</New>
 +
</source>
 +
 
 +
Along with:
 +
 
 +
<source lang="text">
 +
Jaas {
 +
waffle.jaas.WindowsLoginModule sufficient debug=true;
 +
};
 +
</source>
 +
 
 +
Add the necessary WAFFLE classes to the Jetty lib directory. Then start Jetty:
 +
 
 +
<source lang="bash">
 +
> java -Djava.security.auth.login.config=$jetty.home/etc/waffle-login.conf -jar start.jar etc/myjetty.xml
 +
</source>
 +
 
 +
=== Writing Your Own LoginModule ===
 +
 
 +
If you want to implement your own custom LoginModule, there are two classes you should be familiar with:
  
 
<source lang="java">
 
<source lang="java">
 
AbstractLoginModule.java
 
AbstractLoginModule.java
  
package org.mortbay.jetty.plus.jaas.spi;
+
package org.eclipse.jetty.plus.jaas.spi;
  
 
public abstract class AbstractLoginModule implements LoginModule
 
public abstract class AbstractLoginModule implements LoginModule
Line 240: Line 306:
 
UserInfo.java
 
UserInfo.java
  
package org.mortbay.jetty.plus.jaas.spi;
+
package org.eclipse.jetty.plus.jaas.spi;
  
 
public class UserInfo
 
public class UserInfo
Line 267: Line 333:
 
</source>
 
</source>
  
The org.mortbay.jetty.plus.jaas.spi.AbstractLoginModule implements all of the javax.security.auth.spi.LoginModule methods. All you need to do is to implement the getUserInfo method to return a org.mortbay.jetty.plus.jaas.UserInfo instance which encapsulates the username, password and role names (note: as java.lang.Strings) for a user.
+
The <tt>org.eclipse.jetty.plus.jaas.spi.AbstractLoginModule</tt> implements all of the <tt>javax.security.auth.spi.LoginModule</tt> methods. All you need to do is to implement the <tt>getUserInfo</tt> method to return an <tt>org.eclipse.jetty.plus.jaas.UserInfo</tt> instance which encapsulates the username, password and role names as <tt>java.lang.Strings</tt> for a user.
  
The AbstractLoginModule does not support any caching, so if you want to cache UserInfo (e.g. as does the org.mortbay.jetty.plus.jaas.spi.PropertyFileLoginModule) then you must provide this yourself.
+
The AbstractLoginModule does not support any caching, so if you want to cache UserInfo (as, for example, does the <tt>org.mortbay.jetty.plus.jaas.spi.PropertyFileLoginModule</tt>, then you must provide this yourself.
  
=== Example JAAS WebApp ===
+
== Examining an Example JAAS WebApp ==
  
There is an example of authentication and web authorization in the jetty distribution in examples/test-jaas-webapp. It uses the PropertyFileLoginModule to perform authentication based on a simple properties file.  To use it with the [|http://jetty.mortbay.org/maven-plugin/index.html jetty maven plugin]:
+
There is an example of authentication and web authorization in the Jetty distribution in <tt>examples/test-jaas-webapp</tt>. It uses the PropertyFileLoginModule to perform authentication based on a simple properties file.  To use it with the [http://jetty.mortbay.org/maven-plugin/index.html jetty maven plugin]:
<source lang="bash">
+
<source lang="text">
 
> cd examples/test-jaas-webapp
 
> cd examples/test-jaas-webapp
 
> mvn jetty:run
 
> mvn jetty:run
 
</source>
 
</source>
  
Alternatively, to use it instead with jetty standalone:
+
Alternatively, to use it instead with Jetty standalone:
<source lang="bash">
+
<source lang="text">
 
> cd examples/test-jaas-webapp
 
> cd examples/test-jaas-webapp
 
> mvn clean install
 
> mvn clean install
Line 287: Line 353:
 
</source>
 
</source>
  
Then surf to [http://localhost:8080/test-jaas/index.html]
+
Then surf to <nowiki>http://localhost:8080/test-jaas/index.html</nowiki>.
  
 
== Other Goodies ==
 
== Other Goodies ==
Line 293: Line 359:
 
=== RequestParameterCallback ===
 
=== RequestParameterCallback ===
  
As all servlet containers intercept and process a form submission with action j_security_check, it is usually not possible to insert any extra input fields onto a login form with which to perform authentication: you may only pass j_username and j_password. For those rare occasions when this is not good enough, and you require more information from the user in order to authenticate them, you can use the JAAS callback handler org.mortbay.jetty.plus.jaas.callback.RequestParameterCallback. This callback handler gives you access to all parameters that were passed in the form submission. To use it, in the login() method of your custom login module, add the RequestParameterCallback to the list of callback handlers the login module uses, tell it which params you are interested in, and then get the value of the parameter back. Here's an example:
+
As all servlet containers intercept and process a form submission with action <tt>j_security_check</tt>, it is usually not possible to insert any extra input fields onto a login form with which to perform authentication: you may only pass <tt>j_username</tt> and <tt>j_password</tt>. For those rare occasions when this is not good enough, and you require more information from the user in order to authenticate them, you can use the JAAS callback handler <tt>org.mortbay.jetty.plus.jaas.callback.RequestParameterCallback</tt>. This callback handler gives you access to all parameters passed in the form submission. To use it, in the <tt>login()</tt> method of your custom login module, add the RequestParameterCallback to the list of callback handlers the login module uses, tell it which parameters you are want, and then get the value of the parameter back. Here's an example:
  
 
<source lang="java">
 
<source lang="java">
Line 333: Line 399:
 
     }
 
     }
 
</source>
 
</source>
| more = (optional) - links, additional references
+
 
 +
 
 +
 
 +
 
 +
== References ==
 +
 
 +
<references />
 
| category = [[Category:Jetty Tutorial]]
 
| category = [[Category:Jetty Tutorial]]
 
}}
 
}}

Latest revision as of 13:45, 30 April 2013



Introduction

Warning2.png
Jetty 7 and Jetty 8 are now EOL (End of Life)




THIS IS NOT THE DOCUMENTATION YOU ARE LOOKING FOR!!!!!






All development and stable releases are being performed with Jetty 9 and Jetty 10.






This wiki is now officially out of date and all content has been moved to the Jetty Documentation Hub






Direct Link to updated documentation: http://www.eclipse.org/jetty/documentation/current/jaas-support.html


Using JAAS with Jetty is a matter of completing the following tasks:

#Configuring a JAASLoginService

#Declaring an org.eclipse.jetty.plus.jaas.JAASLoginService

#Creating a JAAS login module configuration file

#Specifying the JAAS login module configuration file on the Jetty run line

You should also refer to the JAAS Tutorials and Reference Guide.

Details

The following sections explain how to configure Jetty with JAAS:

Configuring a JAASLoginService

Configure a Jetty org.eclipse.jetty.plus.jaas.JAASLoginService to match the realm-name in your web.xml file. For example, if the web.xml contains a realm called "Test JAAS Realm":

<login-config>
  <auth-method>FORM</auth-method>
  <realm-name>Test JAAS Realm</realm-name>
  <form-login-config>
    <form-login-page>/login/login</form-login-page>
    <form-error-page>/login/error</form-error-page>
  </form-login-config>
</login-config>

Declaring an org.eclipse.jetty.plus.jaas.JAASLoginService

Next declare the following JAASLoginService in a Jetty configuration file:

    <Call name="addBean">
      <Arg>
          <New class="org.eclipse.jetty.plus.jaas.JAASLoginService">
           <Set name="Name">Test JAAS Realm</Set>
           <Set name="LoginModuleName">xyz</Set>
          </New>
      </Arg>
    </Call>

Alternatively, of course, you can set this up in a context XML file that configures a web app:

  <Set name="securityHandler">
    <New class="org.eclipse.jetty.security.ConstraintSecurityHandler">
     <Set name="loginService">
       <New class="org.eclipse.jetty.plus.jaas.JAASLoginService">
         <Set name="name">Test JAAS Realm</Set>
         <Set name="loginModuleName">xyz</Set>
       </New>
     </Set>
    </New>
  </Set>
Warning2.png
It is imperative that the realm-name element in web.xml file is exactly the same as the value of the name property of the JAASLoginService instance.


Creating a JAAS login module configuration file

Set up your LoginModule in a configuration file, following the syntax rules:

xyz {
       com.acme.SomeLoginModule required debug=true;
    };
Warning2.png
It is imperative that the application name to the left of the opening brace is exactly the same as the value of the LoginModuleName property specified above.


Read the JAAS tutorial for more information on configuration options for LoginModules.

Specifying the JAAS login module configuration file on the Jetty run line

Invoke Jetty with the JAAS configuration file you created above:

> java -Djava.security.auth.login.config=mylogin.conf -jar start.jar etc/myjetty.xml

Fine Tuning the JAASLoginService

To allow the greatest degree of flexibility in using JAAS with web applications, the JAASLoginService supports additional configuration options. You don't ordinarily need to set these explicitly, as Jetty has defaults which work in 99% of cases. However, should you need to, you can configure:

  • A policy for role-based authorization (Default: org.eclipse.jetty.plus.jaas.StrictRoleCheckPolicy).
  • A CallbackHandler.
  • A list of classnames for the Principal implementation that equate to a user role (Default: org.eclipse.jetty.plus.jaas.JAASRole).

Here's an example that sets each of these:

<New class="org.eclipse.jetty.plus.jaas.JAASLoginService">
  <Set name="Name">xyzrealm</Set>
  <Set name="LoginModuleName">xyz</Set>
  <Set name="RoleCheckPolicy">
    <New class="org.eclipse.jetty.plus.jaas.StrictRoleCheckPolicy"/>  <!-- default -->
  </Set>
  <Set name="CallbackHandlerClass">
    com.acme.MyCallbackHandler
  </Set>
  <Set name="roleClassNames">
    <Array type="java.lang.String">
      <Item>org.eclipse.jetty.plus.jaas.JAASRole</Item> <!-- default -->
    </Array>
  </Set>
</New>

Understanding the RoleCheckPolicy

The RoleCheckPolicy must be an implementation of the org.eclipse.jetty.plus.jaas.RoleCheckPolicy interface, and its purpose is to help answer the question "is User X in Role Y?" for role-based authorization requests. The default implementation distributed with Jetty is the org.eclipse.jetty.plus.jaas.StrictRoleCheckPolicy, which assesses a user as having a particular role if that role is at the top of the stack of roles that have been temporarily pushed onto the user, or if the user has no temporarily assigned roles, the role is among those configured for the user.

You can temporarily assign roles to a user programmatically by using the pushRole(String rolename) method of the org.eclipse.jetty.plus.jaas.JAASUserPrincipal class.

For the majority of webapps, the default StrictRoleCheckPolicy is adequate, but you can provide your own implementation and set it on your tt>JAASLoginService</tt> instance.

Using the CallbackHandler

A CallbackHandler is responsible for interfacing with the user to obtain usernames and credentials to be authenticated.

Jetty ships with a CallbackHandler which interfaces the information contained in the request to the Callbacks that LoginModules requests. You can replace this default with your own implementation if you have specific requirements not covered by the default.

Configuring a Role Principal Implementation Class

When LoginModules authenticate a user, they usually also gather all of the roles that a user has and place them inside the JAAS Subject. As LoginModules are free to use their own implementation of the JAAS Principal to put into the Subject, Jetty needs to know which Principals represent the user and which represent his/her roles when performing authorization checks on security-constraints. The example LoginModules that ship with jetty all use the org.mortbay.jetty.plus.jaas.JAASRole class. However, if you have plugged in some other LoginModules, you must configure the classnames of their role Principal implementations.

Examining Sample Login Modules

At the time of writing, Jetty provides four sample LoginModule implementations:

  • org.eclipse.jetty.plus.jaas.spi.JDBCLoginModule
  • org.eclipse.jetty.plus.jaas.spi.PropertyFileLoginModule
  • org.eclipse.jetty.plus.jaas.spi.DataSourceLoginModule
  • org.eclipse.jetty.plus.jaas.ldap.LdapLoginModule

We'll take a look at all of these, but first, a word about password handling in Jetty, as it applies to all LoginModules.

Understanding Passwords/Credentials

Passwords can be stored in clear text, obfuscated or checksummed. Use the class org.eclipse.jetty.http.security.Password to generate all varieties of passwords, the output from which you can cut and paste into property files or enter into database tables.

> java -cp lib/jetty.jar org.eclipse.jetty.http.security.Password
Usage - java org.eclipse.jetty.http.security.Password [<user>] <password>
> java -cp lib/jetty.jar org.eclipse.jetty.http.security.Password me you
you
OBF:20771x1b206z
MD5:639bae9ac6b3e1a84cebb7b403297b79
CRYPT:me/ks90E221EY

Read more on securing passwords.

JDBCLoginModule

The JDBCLoginModule stores user passwords and roles in a database that is accessed via JDBC calls. You can configure the JDBC connection information, as well as the names of the table and columns storing the username and credential, and the name of the table and columns storing the roles.

Here is an example login module configuration file entry for it using an HSQLDB driver:

jdbc {
         org.eclipse.jetty.plus.jaas.spi.JDBCLoginModule required
         debug="true"
         dbUrl="jdbc:hsqldb:."
         dbUserName="sa"
         dbPassword="secret"
         dbDriver="org.hsqldb.jdbcDriver"
         userTable="myusers"
         userField="myuser"
         credentialField="mypassword"
         userRoleTable="myuserroles"
         userRoleUserField="myuser"
         userRoleRoleField="myrole";
     };

There is no particular schema required for the database tables storing the authentication and role information. The properties userTable, userField, credentialField, userRoleTable, userRoleUserField, userRoleRoleField configure the names of the tables and the columns within them that are used to format the following queries:

SELECT <credentialField> FROM <userTable> WHERE <userField> =?
SELECT <userRoleRoleField> FROM <userRoleTable> WHERE <userRoleUserField> =?

Credential and role information is lazily read from the database when a previously unauthenticated user requests authentication. This information is only cached for the length of the authenticated session. When the user logs out or the session expires, the information is flushed from memory.

Note.png
You can store passwords in the database in plain text or encoded formats, using the Jetty password utility.


DataSourceLoginModule

Similar to the JDBCLoginModule, but this LoginModule uses a DataSource to connect to the database instead of a JDBC driver. The DataSource is obtained by doing a JNDI lookup on java:comp/env/$\{dnJNDIName\}.

Here is a sample login module configuration for the DataSourceLoginModule:

ds {
       org.eclipse.jetty.plus.jaas.spi.DataSourceLoginModule required
       debug="true"
       dbJNDIName="ds"
       userTable="myusers"
       userField="myuser"
       credentialField="mypassword"
       userRoleTable="myuserroles"
       userRoleUserField="myuser"
       userRoleRoleField="myrole";
   };

PropertyFileLoginModule

With this login module implementation, the authentication and role information is read from a property file.

props {
          org.eclipse.jetty.plus.jaas.spi.PropertyFileLoginModule required
          debug="true"
          file="/somewhere/somefile.props";
      };

The file parameter is the location of a properties file of the same format as the etc/realm.properties example file. The format is:

<username>: <password>[,<rolename> ...]

Here's an example:

fred: OBF:1xmk1w261u9r1w1c1xmq,user,admin
harry: changeme,user,developer
tom: MD5:164c88b302622e17050af52c89945d44,user
dick: CRYPT:adpexzg3FUZAk,admin

The contents of the file are fully read in and cached in memory the first time a user requests authentication.

LdapLoginModule

The LdapLoginModule ships in a separate jar, in $JETTY-HOME/lib/ext/jetty-ldap-jaas.jar. It requires JDK1.5 or above.

ldaploginmodule {
   org.eclipse.jetty.plus.jaas.spi.LdapLoginModule required
   debug="true"
   contextFactory="com.sun.jndi.ldap.LdapCtxFactory"
   hostname="ldap.example.com"
   port="389"
   bindDn="cn=Directory Manager"
   bindPassword="directory"
   authenticationMethod="simple"
   forceBindingLogin="false"
   userBaseDn="ou=people,dc=alcatel"
   userRdnAttribute="uid"
   userIdAttribute="uid"
   userPasswordAttribute="userPassword"
   userObjectClass="inetOrgPerson"
   roleBaseDn="ou=groups,dc=example,dc=com"
   roleNameAttribute="cn"
   roleMemberAttribute="uniqueMember"
   roleObjectClass="groupOfUniqueNames";
   };

Configuring the Role Principal Implementation Class for the LdapLoginModule[1]

The LdapLoginModule does not deal with the situation of user -> some group -> role group, as it assigns users directly to the role group. If you want to specify role occupants by groups within an organization, you need the ability to sort them in this way. The following example shows how to do so by configuring RoleClassNames information. This example implements WAFFLE, which lets you run Jetty under Windows with Active Directory.

<New class="org.mortbay.jetty.plus.jaas.JAASUserRealm">
  <Set name="name">MyTestRealm</Set>
  <Set name="LoginModuleName">Jaas</Set>
  <Set name="RoleClassNames">
    <Array type="java.lang.String">
      <Item>waffle.jaas.UserPrincipal</Item>
      <Item>waffle.jaas.RolePrincipal</Item>
    </Array>
  </Set>
</New>

Along with:

Jaas {
waffle.jaas.WindowsLoginModule sufficient debug=true;
};

Add the necessary WAFFLE classes to the Jetty lib directory. Then start Jetty:

> java -Djava.security.auth.login.config=$jetty.home/etc/waffle-login.conf -jar start.jar etc/myjetty.xml

Writing Your Own LoginModule

If you want to implement your own custom LoginModule, there are two classes you should be familiar with:

AbstractLoginModule.java
 
package org.eclipse.jetty.plus.jaas.spi;
 
public abstract class AbstractLoginModule implements LoginModule
{
  ...
  public abstract UserInfo getUserInfo (String username) throws Exception;
}
UserInfo.java
 
package org.eclipse.jetty.plus.jaas.spi;
 
public class UserInfo
{
 
  public UserInfo (String userName, Credential credential, List roleNames)
  {
    ...
  }
 
  public String getUserName()
  {
    ...
  }
 
  public List getRoleNames ()
  {
    ...
  }
 
  public boolean checkCredential (Object suppliedCredential)
  {
     ...
  }
}

The org.eclipse.jetty.plus.jaas.spi.AbstractLoginModule implements all of the javax.security.auth.spi.LoginModule methods. All you need to do is to implement the getUserInfo method to return an org.eclipse.jetty.plus.jaas.UserInfo instance which encapsulates the username, password and role names as java.lang.Strings for a user.

The AbstractLoginModule does not support any caching, so if you want to cache UserInfo (as, for example, does the org.mortbay.jetty.plus.jaas.spi.PropertyFileLoginModule, then you must provide this yourself.

Examining an Example JAAS WebApp

There is an example of authentication and web authorization in the Jetty distribution in examples/test-jaas-webapp. It uses the PropertyFileLoginModule to perform authentication based on a simple properties file. To use it with the jetty maven plugin:

> cd examples/test-jaas-webapp
> mvn jetty:run

Alternatively, to use it instead with Jetty standalone:

> cd examples/test-jaas-webapp
> mvn clean install
> cd ../../
> java -jar start.jar etc/jetty.xml etc/jetty-jaas.xml

Then surf to http://localhost:8080/test-jaas/index.html.

Other Goodies

RequestParameterCallback

As all servlet containers intercept and process a form submission with action j_security_check, it is usually not possible to insert any extra input fields onto a login form with which to perform authentication: you may only pass j_username and j_password. For those rare occasions when this is not good enough, and you require more information from the user in order to authenticate them, you can use the JAAS callback handler org.mortbay.jetty.plus.jaas.callback.RequestParameterCallback. This callback handler gives you access to all parameters passed in the form submission. To use it, in the login() method of your custom login module, add the RequestParameterCallback to the list of callback handlers the login module uses, tell it which parameters you are want, and then get the value of the parameter back. Here's an example:

FooLoginModule.java
 
public class FooLoginModule extends AbstractLoginModule
{
        .
        .
        .
 
     public boolean login()
        throws LoginException
     {
        .
        .
        .
        Callback[] callbacks = new Callback[3];
        callbacks[0] = new NameCallback();
        callbacks[1] = new ObjectCallback();
 
        //as an example, look for a param named "extrainfo" in the request
        //use one RequestParameterCallback() instance for each param you want to access
        callbacks[2] = new RequestParameterCallback ();
        ((RequestParameterCallback)callbacks[2]).setParameterName ("extrainfo");
        .
        .
        .
        callbackHandler.handle(callbacks);
        String userName = ((NameCallback)callbacks[0]).getName();
        Object pwd = ((ObjectCallback)callbacks[1]).getObject();
        List paramValues = ((RequestParameterCallback)callbacks[2]).getParameterValues();
 
        //use the userName, pwd and the value(s) of the parameter named "extrainfo" to
        //authenticate the user
        .
        .
        .
     }



References

  1. Jay Jaeger, IT Management Consultant at the State of Wisconsin, provided this example. In turn, Jaeger writes, "I would never have figured this out had it not been for the article at http://mail-archives.apache.org/mod_mbox/karaf-issues/201012.mbox/%3C30176778.74721292097241071.JavaMail.jira@thor%3E ."

Back to the top