commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jsde...@apache.org
Subject cvs commit: jakarta-commons/httpclient/xdocs authentication.xml navigation.xml releases.xml
Date Thu, 20 Feb 2003 00:43:53 GMT
jsdever     2003/02/19 16:43:53

  Modified:    httpclient/xdocs navigation.xml releases.xml
  Added:       httpclient/xdocs authentication.xml
  Log:
  Add the authentication.xml
  
  Revision  Changes    Path
  1.4       +3 -1      jakarta-commons/httpclient/xdocs/navigation.xml
  
  Index: navigation.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/navigation.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- navigation.xml	30 Jan 2003 23:29:39 -0000	1.3
  +++ navigation.xml	20 Feb 2003 00:43:52 -0000	1.4
  @@ -17,6 +17,8 @@
         <item name="Applications" href="/applications.html"/>
         <item name="Logging Guide" href="/logging.html"/>
         <item name="Webapp Test Guide" href="/testwebapp.html"/>
  +      <item name="Authentication Guide" href="/authentication.html"/>
  +      <item name="Sample Code" href="http://cvs.apache.org/viewcvs/jakarta-commons/httpclient/src/examples/"/>
         <item name="Release Process" href="/releases.html"/>
       </menu>
     </body>
  
  
  
  1.9       +14 -4     jakarta-commons/httpclient/xdocs/releases.xml
  
  Index: releases.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/releases.xml,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- releases.xml	9 Feb 2003 16:17:34 -0000	1.8
  +++ releases.xml	20 Feb 2003 00:43:52 -0000	1.9
  @@ -85,19 +85,29 @@
           <li>Upload the binary and source distribution files to the newly created
directory
             on daedalus.
             <pre>
  -            cd $JAKARTA_COMMONS_HOME/httpclient/target
  -            scp distributions/* \
  +            scp target/distributions/* \
               your_apache_id@jakarta.apache.org:\
               /www/jakarta.apache.org/builds/jakarta-commons/release/commons-httpclient/v2.0/
             </pre>
             NOTE: Make sure that the files you copy are group writable.</li>
   
  +        <li>The release packages must also be uploaded to www.apache.org which is
also
  +          hosted by daedalus.
  +          <pre>
  +            scp target/distributions/commons-httpclient-2.0-src.* \
  +              your_apache_id@jakarta.apache.org:\
  +              /www/www.apache.org/dist/jakarta/commons/httpclient/source
  +            scp target/distributions/commons-httpclient-2.0.* \
  +              your_apache_id@jakarta.apache.org:\
  +              /www/www.apache.org/dist/jakarta/commons/httpclient/binary
  +          </pre>
  +          NOTE: Make sure that the files you copy are group writable.</li>
  +
           <li>Update jakarta-site2 module with the news item in xdocs/site/news.xml
             and a one liner in xdocs/index.xml.  jakarta-site2 needs to be
             checked out from the private cvs.  After changes are made run
             the build.sh script to generate the site.  Browse the generated
             html documentation and then commit after you are satisfied.<br/><br/></li>
  -
   
           <li>Follow standard procedures to update the Jakarta web site (stored in
             CVS repository <code>jakarta-site2</code> to reflect the availability
  
  
  
  1.1                  jakarta-commons/httpclient/xdocs/authentication.xml
  
  Index: authentication.xml
  ===================================================================
  <?xml version="1.0" encoding="ISO-8859-1"?>
  
  <document>
  
    <properties>
      <title>HttpClient Authentication Guide</title>
      <author email="jsdever@apache.org">Jeff Dever</author>
      <author email="adrian.sutton@ephox.com">Adrian Sutton</author>
      <revision>$Id: authentication.xml,v 1.1 2003/02/20 00:43:52 jsdever Exp $</revision>
    </properties>
  
    <body>
  
      <section name="Introduction">
        HttpClient supports three different types of http authentication schemes:
        Basic, Digest and NTLM.  These can be used to authenticate with http servers
        or proxies.
      </section>
  
      <section name="Server Authentication">
        <p>HttpClient handles authenticating with servers almost transparently,
          the only thing a developer must do is actually provide the login
          credentials.  These credentials are stored in the HttpState instance
          and can be set or retrieved using the <code>setCredentials(String realm,
            Credentials cred)</code> and <code>getCredentials(String realm)</code>
          methods.</p>
  
        <p>Note: To set default Credentials for any realm that has not been
          explicitly specified, pass in <code>null</code> as the value of
          <code>realm</code>.</p>
  
        <p>The automatic authorization built in to HttpClient can be disabled
          with the method <code>setDoAuthentication(boolean doAuthentication)</code>
          in the HttpMethod class.  The change only affects that method instance.</p>
  
        <p>Preemptive authentication can be enabled within HttpClient.  In this
          mode HttpClient will send the basic authentication response even before
          the server gives an unauthorized response in certain situations, thus 
          reducing the overhead of making the connection.  To enable this use the 
          following:</p>
  
        <p><code>setSystemProperty(Authenticator.PREEMPTIVE_PROPERTY, "true");
        </code></p>
  
        <p>The preemptive authentication conforms to rfc2617:
  
          <blockquote>A client SHOULD assume that all paths at or deeper than the depth
            of the last symbolic element in the path field of the Request-URI also
            are within the protection space specified by the Basic realm value
            of the current challenge.  A client MAY preemptively send the 
            corresponding Authorization header with requests for resources in
            that space without receipt of another challenge from the server.
            Similarly, when a client sends a request to a proxy, it may reuse
            a userid and password in the Proxy-Authorization header field without
            receiving another challenge from the proxy server.</blockquote>
        </p>
      </section>
  
      <section name="Proxy Authentication">
        <p>Proxy authentication in HttpClient is almost identical to server
          authentication with the exception that the credentials for each are
          stored independantly.  So for proxy authentication you must use
          <code>setProxyCredentials(String realm, Credentials cred)</code> and
          <code>getProxyCredentials(String realm)</code>.  As with server
          authentication, passing <code>null</code> as the realm sets or returns
          the default credentials.</p>
      </section>
  
      <section name="Basic">
        <p>Basic authentication is the original and most compatible authentication
          scheme for HTTP.  Unfortunately, it is also the least secure as it sends
          the username and password unencrypted to the server.  Basic authentication
          requires an instance of UsernamePasswordCredentials (which NTCredentials
          extends) to be available, either for the specific realm specified by the
          server or as the default credentials.</p>
      </section>
  
      <section name="Digest">
        <p>Digest authentication was added in the HTTP 1.1 protocol and while
          not being as widely supported as Basic authentication there is a great
          deal of support for it.  Digest authentication is significantly more
          secure than basic authentication as it never transfers the actual
          password across the network, but instead uses it to encrypt a "nonce"
          value sent from the server.</p>
  
        <p>Digest authentication requires an instance of
          UsernamePasswordCredentials (which NTCredentials extends) to be
          available either for the specific realm specified by the server or as
          the default credentials.</p>
      </section>
  
      <section name="NTLM">
        <p>NTLM is the most complex of the authentication protocols supported
          by HttpClient.  It is a proprietary protocol designed by Microsoft
          with no publicly available specification.  Early version of NTLM were
          less secure than Digest authentication due to faults in the design,
          however these were fixed in a service pack for Window NT 4 and the
          protocol is now considered more secure than Digest authentication.</p>
  
        <p>NTLM authentication requires an instance of NTCredentials be
          available for the <i>domain name</i> of the server or the default
          credentials.  Note that since NTLM does not use the notion of realms
          HttpClient uses the domain name of the server as the name of the realm.</p>
  
        <p>There are some significant differences in the way that NTLM works
          compared with basic and digest authentication.  These differences
          are generally handled by HttpClient, however having an
          understanding of these differences can help avoid problems when using
          NTLM authentication.</p>
  
        <p>
          <ol>
            <li>NTLM authentication works almost exactly the same as any other form
of
              authentication in terms of the HttpClient API.  The only difference is that
              you need to supply 'NTCredentials' instead of 'UsernamePasswordCredentials'
              (NTCredentials actually extends UsernamePasswordCredentials so you can use
              NTCredentials right throughout your application if need be).</li>
  
            <li>The realm for NTLM authentication is the domain name of the computer
              being connected to, this can be troublesome as servers often have
              multiple domain names that refer to them.  Only the domain name
              that HttpClient connects to (as specified by the HostConfiguration)
              is used to look up the credentials.
              It is generally advised that while initially testing NTLM
              authentication, you pass the realm in as null which is used as
              the default.</li>
  
            <li>NTLM authenticates a connection and not a request, so you need to
              authenticate every time a new connection is made and keeping the connection
              open during authentication is vital.  Due to this, NTLM cannot
              be used to authenticate with both a proxy and the server, nor can
              NTLM be used with HTTP 1.0 connections or servers that do not
              support HTTP keep-alives.</li>
          </ol>
        </p>
      </section>
  
    </body>
  
  </document>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message