| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>JAAS Support</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="jetty, servlet, servlet-api, cometd, http, websocket, eclipse, maven, java, server, software"><link rel="home" href="index.html" title="Jetty"><link rel="up" href="configuring-security.html" title="Chapter 7. Configuring Security"><link rel="prev" href="configuring-security-secure-passwords.html" title="Secure Password Obfuscation"><link rel="next" href="spnego-support.html" title="Spnego Support"><link xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" rel="shortcut icon" href="images/favicon.ico"><link rel="stylesheet" href="css/highlighter/foundation.css"><script src="js/highlight.pack.js"></script><script> |
| hljs.initHighlightingOnLoad(); |
| </script><link type="text/css" rel="stylesheet" href="css/font-awesome/font-awesome.min.css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><tr><td style="width: 25%"><a href="http://www.eclipse.org/jetty"><img src="images/jetty-header-logo.png" alt="Jetty Logo"></a><br><span style="font-size: small"> |
| Version: 9.3.28.v20191105</span></td><td style="width: 50%"></td></tr></table><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">JAAS Support</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="configuring-security-secure-passwords.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a> </td><th width="60%" align="center">Chapter 7. Configuring Security<br><a accesskey="p" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></th><td width="20%" align="right"> <a accesskey="n" href="spnego-support.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr></table><hr></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="jetty-callout"><h5 class="callout"><a href="http://www.webtide.com/">Contact the core Jetty developers at |
| <span class="website">www.webtide.com</span></a></h5><p> |
| private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... |
| scalability guidance for your apps and Ajax/Comet projects ... development services for sponsored feature development |
| </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jaas-support"></a>JAAS Support</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="jaas-support.html#jetty-jaas">Jetty and JAAS</a></span></dt><dt><span class="section"><a href="jaas-support.html#jaas-configuration">Configuration</a></span></dt><dt><span class="section"><a href="jaas-support.html#_a_closer_look_at_jaasloginservice">A Closer Look at JAASLoginService</a></span></dt><dt><span class="section"><a href="jaas-support.html#_writing_your_own_loginmodule">Writing your Own LoginModule</a></span></dt><dt><span class="section"><a href="jaas-support.html#_other_goodies">Other Goodies</a></span></dt></dl></div><p>JAAS implements a Java version of the standard Pluggable Authentication Module (PAM) framework.</p><p>JAAS can be used for two purposes:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">for authentication of users, to reliably and securely determine who is currently executing Java code, regardless of whether the code is running as an application, an applet, a bean, or a servlet</li><li class="listitem">for authorization of users to ensure they have the access control rights (permissions) required to do the actions performed</li></ul></div><p>JAAS authentication is performed in a pluggable fashion. |
| This permits applications to remain independent from underlying authentication technologies. |
| New or updated authentication technologies can be plugged under an application without requiring modifications to the application itself. |
| Applications enable the authentication process by instantiating a <code class="literal">LoginContext</code> object, which in turn references a configuration to determine the authentication technology(ies), or <code class="literal">LoginModule</code>(s), to be used in performing the authentication. |
| Typical <code class="literal">LoginModules</code> may prompt for and verify a username and password. |
| Others may read and verify a voice or fingerprint sample.</p><p>See Java Authentication and Authorization Service (JAAS) <a class="link" href="http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html" target="_top">Reference Guide</a> for more information about JAAS.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="jetty-jaas"></a>Jetty and JAAS</h3></div></div></div><p>Many application servers support JAAS as a means of bringing greater flexibility to the declarative security models of the J2EE (now known as the JavaEE) <a class="link" href="http://java.sun.com/javaee/index.jsp" target="_top">specification</a>. |
| Jetty support for JAAS provides greater alternatives for servlet security, and increases the portability of web applications.</p><p>The JAAS support aims to dictate as little as possible whilst providing a sufficiently flexible infrastructure to allow users to drop in their |
| own custom <a class="link" href="http://java.sun.com/j2se/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.html" target="_top">LoginModules</a>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="jaas-configuration"></a>Configuration</h3></div></div></div><p>Using JAAS with Jetty is very simply a matter of declaring a <code class="literal">org.eclipse.jetty.jaas.JAASLoginService</code>, creating a JAAS login module configuration file and specifying it on the Jetty run line. |
| Let’s look at an example.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_step_1"></a>Step 1</h4></div></div></div><p>Configure a Jetty <code class="literal">org.eclipse.jetty.jaas.JAASLoginService</code> to match the <code class="literal"><realm-name></code> in your <code class="literal">web.xml</code> file. For example, if the <code class="literal">web.xml</code> contains a realm called "xyz" like so:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code><login-config> |
| <auth-method>FORM</auth-method> |
| <realm-name>xyz</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></code></pre><p>Then you need to create a <code class="literal">JAASLoginService</code> with the matching name of "xyz":</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code><New class="org.eclipse.jetty.jaas.JAASLoginService"> |
| <Set name="Name">Test JAAS Realm</Set> |
| <Set name="LoginModuleName">xyz</Set> |
| </New></code></pre><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-exclamation" aria-hidden="true"></i> Caution</h3><p>The name of the realm-name that you declare in <code class="literal">web.xml</code> must match exactly the name of your <code class="literal">JAASLoginService</code>.</p></div></blockquote></div><p>You can declare your <code class="literal">JAASLoginService</code> in a couple of different ways:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p class="simpara">If you have more than one webapp that you would like to use the same security infrastructure, then you can declare your <code class="literal">JAASLoginService</code> in a top-level Jetty xml file as a bean that is added to the <code class="literal">org.eclipse.jetty.server.Server</code>. |
| An example:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code><Configure id="Server" class="org.eclipse.jetty.server.Server"> |
| |
| <Call name="addBean"> |
| <Arg> |
| <New class="org.eclipse.jetty.jaas.JAASLoginService"> |
| <Set name="name">Test JAAS Realm</Set> |
| <Set name="LoginModuleName">xyz</Set> |
| </New> |
| </Arg> |
| </Call> |
| |
| </Configure></code></pre></li><li class="listitem"><p class="simpara">Alternatively, you can use a <code class="literal">JAASLoginService</code> with just a specific webapp by creating a <a class="link" href="configuring-specific-webapp-deployment.html#deployable-descriptor-file" title="Jetty Deployable Descriptor XML File">context xml</a> file for the webapp, and specifying the <code class="literal">JAASLoginService</code> in it:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code><Configure class="org.eclipse.jetty.webapp.WebAppContext"> |
| |
| <Set name="securityHandler"> |
| <New class="org.eclipse.jetty.security.ConstraintSecurityHandler"> |
| <Set name="loginService"> |
| <New class="org.eclipse.jetty.jaas.JAASLoginService"> |
| <Set name="name">Test JAAS Realm</Set> |
| <Set name="loginModuleName">xyz</Set> |
| </New> |
| </Set> |
| </New> |
| </Set> |
| |
| </Configure></code></pre></li></ol></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="jaas-step-2"></a>Step 2</h4></div></div></div><p>Set up your <code class="literal">LoginModule</code> in a configuration file, following the <a class="link" href="http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/login/Configuration.html" target="_top">syntax rules</a> :</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>xyz { |
| com.acme.SomeLoginModule required debug=true; |
| };</code></pre><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-exclamation" aria-hidden="true"></i> Caution</h3><p>It is imperative that the application name on the first line is exactly the same as the <code class="literal">LoginModuleName</code> of your <code class="literal">JAASLoginService</code>.</p></div></blockquote></div><p>You may find it convenient to name this configuration file as <code class="literal">etc/login.conf</code> because, as we will see below, some of the wiring up for JAAS has been done for you.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_step_3"></a>Step 3</h4></div></div></div><p>You now need to invoke Jetty with support for JAAS. |
| There are 2 aspects to this:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">adding JAAS-related jars to the Jetty container classpath</li><li class="listitem">setting the System property <code class="literal">java.security.auth.login.config</code></li></ul></div><p>To accomplish the above, use the Jetty <a class="link" href="startup.html#startup-overview" title="Startup Overview">startup</a> <a class="link" href="startup-modules.html" title="Managing Startup Modules">modules mechanism</a> to add the JAAS <a class="link" href="startup-modules.html" title="Managing Startup Modules">module</a>:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>java -jar start.jar --add-to-startd=jaas</code></pre><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-asterisk" aria-hidden="true"></i> Note</h3><p>The top level of the distribution does not have the JAAS module enabled by default. |
| However, there are several <a class="link" href="quickstart-running-jetty.html#demo-webapps-base" title="Demo Base">demo webapps</a> - including a JAAS webapp - available in the <code class="literal">demo-base</code> directory of the distribution which has pre-enabled the JAAS module.</p></div></blockquote></div><p>Now you will have a file named <code class="literal">start.d/jaas.ini</code>, which contains:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>--module=jaas |
| jaas.login.conf=etc/login.conf</code></pre><p>The <code class="literal">jaas.login.conf</code> property refers to the location of your <code class="literal">LoginModule</code> configuration file that you established in <a class="link" href="jaas-support.html#jaas-step-2" title="Step 2">Step 2</a>. |
| If you called it <code class="literal">etc/login.conf</code>, then your work is done. Otherwise, change the value of the <code class="literal">jaas.login.conf</code> property to be the location of your LoginModule configuration file. |
| Jetty will automatically use this property to set the value of the System property <code class="literal">java.security.auth.login.config.</code></p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_a_closer_look_at_jaasloginservice"></a>A Closer Look at JAASLoginService</h3></div></div></div><p>To allow the greatest degree of flexibility in using JAAS with web applications, the <code class="literal">JAASLoginService</code> 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:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">a policy for role-based authorization (Default: <code class="literal">org.eclipse.jetty.jaas.StrictRoleCheckPolicy</code>)</li><li class="listitem">a CallbackHandler (Default: <code class="literal">org.eclipse.jetty.jaas.callback.DefaultCallbackHandler</code>)</li><li class="listitem">a list of classnames for the Principal implementation that equate to a user role (Default: <code class="literal">org.eclipse.jetty.jaas.JAASRole</code>)</li></ul></div><p>Here’s an example of setting each of these (to their default values):</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code><New class="org.eclipse.jetty.jaas.JAASLoginService"> |
| <Set name="Name">Test JAAS Realm</Set> |
| <Set name="LoginModuleName">xyz</Set> |
| <Set name="RoleCheckPolicy"> |
| <New class="org.eclipse.jetty.jaas.StrictRoleCheckPolicy"/> |
| </Set> |
| <Set name="CallbackHandlerClass"> |
| org.eclipse.jetty.jaas.callback.DefaultCallbackHandler |
| </Set> |
| <Set name="roleClassNames"> |
| <Array type="java.lang.String"> |
| <Item>org.eclipse.jetty.jaas.JAASRole</Item> |
| </Array> |
| </Set> |
| </New></code></pre><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_rolecheckpolicy"></a>RoleCheckPolicy</h4></div></div></div><p>The <code class="literal">RoleCheckPolicy</code> must be an implementation of the <code class="literal">org.eclipse.jetty.jaas.RoleCheckPolicy</code> 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 <code class="literal">org.eclipse.jetty.jaas.StrictRoleCheckPolicy</code>, which will assess 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. |
| If the user has no temporarily assigned roles, the role is amongst those configured for the user.</p><p>Roles can be temporarily assigned to a user programmatically by using the <code class="literal">pushRole(String rolename)</code> method of the <code class="literal">org.eclipse.jetty.jaas.JAASUserPrincipal</code> class.</p><p>For the majority of webapps, the default <code class="literal">StrictRoleCheckPolicy</code> will be quite adequate, however you may provide your own implementation and set it on your <code class="literal">JAASLoginService</code> instance.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_callbackhandler"></a>CallbackHandler</h4></div></div></div><p>A CallbackHandler is responsible for interfacing with the user to obtain usernames and credentials to be authenticated.</p><p>Jetty ships with the <code class="literal">org.eclipse.jetty.jaas.DefaultCallbackHandler</code> which interfaces the information contained in the request to the Callbacks that are requested by <code class="literal">LoginModules</code>. |
| You can replace this default with your own implementation if you have specific requirements not covered by the default.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_role_principal_implementation_class"></a>Role Principal Implementation Class</h4></div></div></div><p>When <code class="literal">LoginModules</code> authenticate a user, they usually also gather all of the roles that a user has and place them inside the JAAS Subject. |
| As <code class="literal">LoginModules</code> 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 <code class="literal"><security-constraint></code>. The example <code class="literal">LoginModules</code> that ship with Jetty all use the <code class="literal">org.eclipse.jetty.jaas.JAASRole</code> class. However, if you have plugged in other <code class="literal">LoginModules</code>, you must configure the classnames of their role Principal implementations.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_sample_loginmodules"></a>Sample LoginModules</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="link" href="http://www.eclipse.org/jetty/javadoc/9.3.28.v20191105/org/eclipse/jetty/jaas/spi/JDBCLoginModule.html" target="_top"><code class="literal">org.eclipse.jetty.jaas.spi.JDBCLoginModule</code></a></li><li class="listitem"><a class="link" href="http://www.eclipse.org/jetty/javadoc/9.3.28.v20191105/org/eclipse/jetty/jaas/spi/PropertyFileLoginModule.html" target="_top"><code class="literal">org.eclipse.jetty.jaas.spi.PropertyFileLoginModule</code></a></li><li class="listitem"><a class="link" href="http://www.eclipse.org/jetty/javadoc/9.3.28.v20191105/org/eclipse/jetty/jaas/spi/DataSourceLoginModule.html" target="_top"><code class="literal">org.eclipse.jetty.jaas.spi.DataSourceLoginModule</code></a></li><li class="listitem"><a class="link" href="http://www.eclipse.org/jetty/javadoc/9.3.28.v20191105/org/eclipse/jetty/jaas/spi/LdapLoginModule.html" target="_top"><code class="literal">org.eclipse.jetty.jaas.ldap.LdapLoginModule</code></a></li></ul></div><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-asterisk" aria-hidden="true"></i> Note</h3><p>Passwords can be stored in clear text, obfuscated or checksummed. |
| The class <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.3.28.v20191105/org/eclipse/jetty/util/security/Password.html" target="_top"><code class="literal">org.eclipse.jetty.util.security.Password</code></a> should be used to generate all varieties of passwords,the output from which can be put in to property files or entered into database tables. |
| See more on this under the Configuration section on <a class="link" href="configuring-security-secure-passwords.html" title="Secure Password Obfuscation">securing passwords</a>.</p></div></blockquote></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_jdbcloginmodule"></a>JDBCLoginModule</h4></div></div></div><p>The <code class="literal">JDBCLoginModule</code> 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 names of the table and columns storing the roles.</p><p>Here is an example login module configuration file entry for it using an HSQLDB driver:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>jdbc { |
| org.eclipse.jetty.jaas.spi.JDBCLoginModule required |
| debug="true" |
| dbUrl="jdbc:hsqldb:." |
| dbUserName="sa" |
| dbDriver="org.hsqldb.jdbcDriver" |
| userTable="myusers" |
| userField="myuser" |
| credentialField="mypassword" |
| userRoleTable="myuserroles" |
| userRoleUserField="myuser" |
| userRoleRoleField="myrole"; |
| };</code></pre><p>There is no particular schema required for the database tables storing the authentication and role information. |
| The properties <code class="literal">userTable</code>, <code class="literal">userField</code>, <code class="literal">credentialField</code>, <code class="literal">userRoleTable</code>, <code class="literal">userRoleUserField</code>, <code class="literal">userRoleRoleField</code> configure the names of the tables and the columns within them that are used to format the following queries:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code> select <credentialField> from <userTable> |
| where <userField> =? |
| select <userRoleRoleField> from <userRoleTable> |
| where <userRoleUserField> =?</code></pre><p>Credential and role information is lazily read from the database when a previously unauthenticated user requests authentication. |
| Note that this information is <span class="emphasis"><em>only</em></span> cached for the length of the authenticated session. |
| When the user logs out or the session expires, the information is flushed from memory.</p><p>Note that passwords can be stored in the database in plain text or encoded formats - see the note on "Passwords/Credentials" above.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_datasourceloginmodule"></a>DataSourceLoginModule</h4></div></div></div><p>Similar to the <code class="literal">JDBCLoginModule</code>, but this <code class="literal">LoginModule</code> uses a <code class="literal">DataSource</code> to connect to the database instead of a JDBC driver. The <code class="literal">DataSource</code> is obtained by performing a JNDI lookup on <code class="literal">java:comp/env/${dnJNDIName}</code>.</p><p>A sample login module configuration using this method:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>ds { |
| org.eclipse.jetty.jaas.spi.DataSourceLoginModule required |
| debug="true" |
| dbJNDIName="ds" |
| userTable="myusers" |
| userField="myuser" |
| credentialField="mypassword" |
| userRoleTable="myuserroles" |
| userRoleUserField="myuser" |
| userRoleRoleField="myrole"; |
| };</code></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_propertyfileloginmodule"></a>PropertyFileLoginModule</h4></div></div></div><p>With this login module implementation, the authentication and role information is read from a property file.</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>props { |
| org.eclipse.jetty.jaas.spi.PropertyFileLoginModule required |
| debug="true" |
| file="/somewhere/somefile.props"; |
| };</code></pre><p>The file parameter is the location of a properties file of the same format as the <code class="literal">etc/realm.properties</code> example file. |
| The format is:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code><username>: <password>[,<rolename> ...]</code></pre><p>Here’s an example:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>fred: OBF:1xmk1w261u9r1w1c1xmq,user,admin |
| harry: changeme,user,developer |
| tom: MD5:164c88b302622e17050af52c89945d44,user |
| dick: CRYPT:adpexzg3FUZAk,admin</code></pre><p>The contents of the file are fully read in and cached in memory the first time a user requests authentication.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_ldaploginmodule"></a>LdapLoginModule</h4></div></div></div><p>Here’s an example:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>ldaploginmodule { |
| org.eclipse.jetty.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"; |
| };</code></pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_writing_your_own_loginmodule"></a>Writing your Own LoginModule</h3></div></div></div><p>If you want to implement your own custom <code class="literal">LoginModule</code>, there are two classes to be familiar with: <code class="literal">org.eclipse.jetty.jaas.spi.AbstractLoginModule</code> and <code class="literal">org.eclipse.jetty.jaas.spi.UserInfo</code>.</p><p>The <code class="literal">org.eclipse.jetty.jaas.spi.AbstractLoginModule</code> implements all of the <code class="literal">javax.security.auth.spi.LoginModule</code> methods. |
| All you need to do is to implement the <code class="literal">getUserInfo</code> method to return a <code class="literal">org.eclipse.jetty.jaas.UserInfo</code> instance which encapsulates the username, password and role names (note: as <code class="literal">java.lang.Strings</code>) for a user.</p><p>The <code class="literal">AbstractLoginModule</code> does not support any caching, so if you want to cache UserInfo (eg as does the <code class="literal">org.eclipse.jetty.jaas.spi.PropertyFileLoginModule</code>) then you must provide this yourself.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_other_goodies"></a>Other Goodies</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_requestparametercallback"></a>RequestParameterCallback</h4></div></div></div><p>As all servlet containers intercept and process a form submission with action <code class="literal">j_security_check</code>, it is usually not possible to insert any extra input fields onto a login form with which to perform authentication: you may only pass <code class="literal">j_username</code> and <code class="literal">j_password</code>. |
| 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 <code class="literal">org.eclipse.jetty.jaas.callback.RequestParameterCallback</code>. |
| This callback handler gives you access to all parameters that were passed in the form submission. |
| To use it, in the <code class="literal">login()</code> method of your custom login module, add the <code class="literal">RequestParameterCallback</code> 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 is an example:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>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 |
| |
| } |
| }</code></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_example_jaas_webapp"></a>Example JAAS WebApp</h4></div></div></div><p>An example webapp using JAAS can be found in the Jetty GitHub repository:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="link" href="https://github.com/eclipse/jetty.project/tree/jetty-9.3.x/tests/test-webapps/test-jaas-webapp" target="_top">https://github.com/eclipse/jetty.project/tree/master/tests/test-webapps/test-jaas-webapp</a></li></ul></div></div></div></div><script type="text/javascript"> |
| SyntaxHighlighter.all() |
| </script><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuring-security-secure-passwords.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a> </td><td width="20%" align="center"><a accesskey="u" href="configuring-security.html"><i class="fa fa-chevron-up" aria-hidden="true"></i> Top</a></td><td width="40%" align="right"> <a accesskey="n" href="spnego-support.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Secure Password Obfuscation </td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></td><td width="40%" align="right" valign="top"> Spnego Support</td></tr></table></div><p xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><div class="jetty-callout"> |
| See an error or something missing? |
| <span class="callout"><a href="http://github.com/eclipse/jetty.project">Contribute to this documentation at |
| <span class="website"><i class="fa fa-github" aria-hidden="true"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2019-11-05)</i></span></div></p></body></html> |
