security.xtp

解压在c盘

<s1 title="Security Configuration">

<summarylist/>

<s2 title='Overview'>

<p>Security in Resin consists of four separate functions:</p>

<ul>
<li><a href="#authentication">Authentication</a>: Who is trying to use the resource?
<ul>
<li><a href="#login-config">login-config</a>: How the client sends the user and password.
<li><a href="#authenticator">authenticator</a>: How the server checks the user and password to authenticate a user.
</ul>
<li><a href="#authorization">Authorization</a>: Is the client allowed to use the resource?
<li><a href="#encryption">Encryption</a> (SSL): Protecting data from prying eyes.
<li><a href="#security-manager">Security Manager</a> (for ISPs only) :
Protecting users from each other.
</ul>

<p>By using Resin's login support, applications can add security
without writing an entire authentication library.  If the predefined
authentication methods, XML and database user lookup, are inadequate,
Resin provides an API to write custom authentication code.</p>

<p>The easiest authenticator to understand is the XmlAuthenticator.
It lets you put users and passwords directly in the configuration
file.  The following example uses "Basic" authentication for login.
Basic authentication asks the browser to pop open a window prompting
for a username and password.  (Basic authentication is discouraged
because it is not secure unless you use it with SSL, but it's the
easiest example.)  The only user defined here is "Harry Potter" and
he has the password "quidditch".  He also plays the
"user" role.</p>

<example title="Using the XmlAuthenticator">
&lt;web-app>
&lt;login-config auth-method='basic'>
  &lt;authenticator>
    &lt;class-name>com.caucho.http.security.XmlAuthenticator&lt;/class-name>
    &lt;init-param user='Harry Potter:quidditch:user'/>
  &lt;/authenticator>
&lt;/login-config>
&lt;security-constraint url-pattern='/users-only/*' role-name='user'/>
&lt;/web-app>
</example>

<p>In the above example, the &lt;security-constraint> checks
for authorization.  Only users playing the "user" role can access
the /users-only directory.</p>

</s2>

<s2 name='authentication' title='Authentication'>

<defun title='login-config'>

</defun>

<defun title='auth-method'>
<p>Selects the authentication method.</p>

<deftable title="auth-method values">
<tr><th>auth-method<th>Meaning
<tr><td>basic<td>HTTP Basic authentication
<tr><td>digest<td>HTTP Digest authentication
<tr><td>form<td>Form-based authentication
</deftable>

</defun>

<defun title='form-login-config'>
<p>Configures authentication for forms.  The login form has
specific parameters that the servlet engine's login form processing
understands.  If the login succeeds, the user will see the original
page.  If it fails, she will see the error page.</p>

<deftable>
<tr><td>form-login-page<td>The page to be used to prompt the user login<td>none
<tr><td>form-error-page<td>The error page for unsuccessful login<td>none
<tr><td>internal-forward<td>Use an internal redirect on success or a sendRedirect<td>false
<tr><td>form-uri-priority<td>If true, the form's j_uri will override a stored URI<td>false
</deftable>

<p>The form itself must have the action <var/j_security_check/>.  It
must also have the parameters <var/j_username/> and <var/j_password/>.
Optionally, it can also have <var/j_uri/> and
<var/j_use_cookie_auth/>.  <var/j_uri/> gives the next page to display
when login succeeds.  <var/j_use_cookie_auth/> allows Resin to send a
persistent cookie to the user to make following login easier.
</p>

<p><var/j_use_cookie_auth/> gives control to the user whether to generate
a persistent cookie.  It lets you implement the "remember me" button.  By
default, the authentication only lasts for a single session.
</p>

<deftable title="j_security_check Parameters">
<tr><th>Parameter<th>Meaning)
<tr><td>j_username<td>The user name
<tr><td>j_password<td>The password
<tr><td>j_uri<td>Resin extension for the successful display
page (Optional).
<tr><td>j_use_cookie_auth<td>Resin extension to allow cookie
login (Optional).
</deftable>

<p>The following is an example of a servlet-standard login page:</p>

<example>
&lt;form action='j_security_check' method='POST'>
&lt;table>
&lt;tr>&lt;td>User:&lt;td>&lt;input name='j_username'>
&lt;tr>&lt;td>Password:&lt;td>&lt;input name='j_password'>
&lt;tr>&lt;td colspan=2>hint: the password is 'quidditch'
&lt;tr>&lt;td>&lt;input type=submit>
&lt;/table>
&lt;/form>
</example>

</defun>

<defun title='authenticator' version='Resin 1.1'>
<p>Specifies a class to authenticate users.  This Resin-specific
option lets you control your authentication.  You can either create your 
own custom authenticator, or use Resin's JdbcAuthenticator.</p>

<p>The authenticator is responsible for taking the username and
password and returning a UserPrincipal if the username and password match.
</p>

<p>Users wanting to implement an authenticator should look at the JavaDoc
for com.caucho.http.security.ServletAuthenticator
and com.caucho.http.security.AbstractAuthenticator.
To protect your application from API changes, you should extend
AbstractAuthenticator rather than implementing Authenticator directly.
</p>
</defun>

<s3 title='XmlAuthenticator' version='Resin 2.0.4'>
<p>The XmlAuthenticator (com.caucho.http.security.XmlAuthenticator),
stores the authentication in either an xml file or in the configuration
itself.</p>

<p>When configuring the XmlAuthenticator in the resin.conf
(or web.xml), each <var/init-param user/> adds a new configured
user.  The value contains the username, password, and the
roles the user plays.</p>

<example title='XmlAuthenticator in resin.conf'>
&lt;authenticator>
  &lt;class-name>com.caucho.http.security.XmlAuthenticator&lt;/class-name>
  &lt;init-param user='Harry Potter:quidditch:user,gryffindor'/>
  &lt;init-param user='Draco Malfoy:pureblood:user,slytherin'/>
&lt;/authenticator>
</example>

<p>Because the plain text passwords in the example
above are a serious security issue, most sites will use
the password-digest attribute described below to protect the
passwords.</p>

<deftable>
<tr><th>attribute<th>meaning
<tr><td>user<td>specifies an allowed user.  May be repeated.
<tr><td>password-digest<td>selects the signature method to protect
the password
<tr><td>path<td>specifies a path to an XML file containing the users and passwords.
<tr><td>logout-on-session-timeout<td>If true, the user will be logged out when the session times out<td>true
</deftable>

<p>The passwords can be specified in a separate *.xml file.  The password
file looks like:</p>

<example title='password.xml'>
&lt;authenticator>
  &lt;user name='Harry Potter' password='quidditch' role='gryffindor'/>
  &lt;user name='Draco Malfoy' password='pureblood' role='slytherin'/>
&lt;/authenticator>
</example>

<p>Sites should use password-digest to protect the passwords.</p>

</s3>

<s3 title='JdbcAuthenticator' version='Resin 2.0'>
<p>The JdbcAuthenticator (com.caucho.http.security.JdbcAuthenticator),
asks a backend database for the password matching the user's name.
It uses the DataSource specified by the <var/pool-name/> option, or
the JNDI <var/java:comp/env/jdbc/db-pool/> by default.
<var/pool-name/> refers to a DataSource configured with
<a href="app-config.xtp#resource-ref">resource-ref</a>.</p>

<p>The following are the attributes for the JdbcAuthenticator:</p>

<deftable>
<tr><th>attribute<th>meaning
<tr><td>pool-name<td>The database pool.  Looks in the application
attributes first, then in the global database pools.
<tr><td>password-query<td>A SQL query to get the user's password.  The
default query is given below.
<tr><td>cookie-auth-query<td>A SQL query to authenticate the user by a
persistent cookie.
<tr><td>cookie-auth-update<td>A SQL update to match
a persistent cookie to a user.
<tr><td>role-query<td>A SQL query to determine the user's role.  By
default, all users are in role "user", but no others.
<tr><td>password-digest<td>Specifies the digest algorithm and format (Resin 2.0.4)
<tr><td>logout-on-session-timeout<td>If true, the user will be logged out when the session times out (Resin 2.0.6)<td>true
</deftable>

<example>
&lt;!-- Resin-specific JdbcAuthenticator -->
&lt;authenticator id='com.caucho.http.security.JdbcAuthenticator'>
  &lt;pool-name>test&lt;/pool-name>
  &lt;password-query>
    SELECT password FROM LOGIN WHERE username=?
  &lt;/password-query>
  &lt;cookie-auth-query>
    SELECT username FROM LOGIN WHERE cookie=?
  &lt;/cookie-auth-query>
  &lt;cookie-auth-update>
    UPDATE LOGIN SET cookie=? WHERE username=?
  &lt;/cookie-auth-update>
  &lt;role-query>
    SELECT role FROM LOGIN WHERE username=?
  &lt;/role-query>
&lt;/authenticator>
</example>

</s3>

<s3 title='PasswordDigest' version='Resin 2.0.4'>

<p>Resin 2.0.4 adds the capability to store the digest of
a password instead of the password itself.  By using the password digest,
the application can avoid storing the password in a form that someone
can read.</p>

<p>Setting password-digest of any authenticator
extending AbstractAuthenticator will create a digest of the password.
The password-digest has two parts: the digest algorithm
and the encoding format.  "MD5-base64" is a typical digest format.</p>

<p>The authenticator will create a digest of the username and password.
Since that digest is a byte array, it is then converted to a string.</p>
<def>
MD5(<var/username/>:<var/password/>)
</def>

<example title='Using password-digest with XmlAuthenticator'>
&lt;authenticator>
  &lt;class-name>com.caucho.http.security.XmlAuthenticator&lt;/class-name>
  &lt;init-param password-digest='MD5-base64'/>
  &lt;init-param user='harry:Syvian7bcPDKI261QvH9Cw:user'/>
&lt;/authenticator>
</example>

<p>Of course, storing the digest password take a bit more work.  When
the user registers, the application needs to compute the
digest to store it.  You can use the PasswordDigest class to do that.</p>

<example>
import com.caucho.http.security.PasswordDigest;

...
PasswordDigest digest = new PasswordDigest();
digest.setAlgorithm("MD5");
digest.setFormat("base64");

String password = digest.getPasswordDigest("harry", "quidditch");
</example>

</s3>

</s2>