diff --git a/src/docbkx/authentication.xml b/src/docbkx/authentication.xml index 5e718eb13..8f501ee42 100644 --- a/src/docbkx/authentication.xml +++ b/src/docbkx/authentication.xml @@ -115,6 +115,19 @@ pwd distributions. + + + SPNEGO/Kerberos: + SPNEGO (Simple and + Protected GSSAPI + Negotiation Mechanism) is a GSSAPI + "pseudo mechanism" that is used to negotiate one of a number of possible + real mechanisms. SPNEGO's most visible use is in Microsoft's HTTP + Negotiate authentication extension. The negotiable + sub-mechanisms include NTLM and Kerberos supported by Active Directory. + Presently HttpClient supports Kerberos sub-mechanism only. + +
@@ -146,9 +159,8 @@ pwd AuthSchemes when authenticating with the target host. This parameter expects a value of type java.util.Collection. The collection is expected - to contain java.lang.String instances representing a - name of an authentication scheme as returned by - AuthScheme#getSchemeName() + to contain java.lang.String instances representing + an id of an authentication scheme. @@ -158,9 +170,8 @@ pwd AuthSchemes when authenticating with the proxy host. This parameter expects a value of type java.util.Collection. The collection is expected - to contain java.lang.String instances representing a - name of an authentication scheme as returned by - AuthScheme#getSchemeName() + to contain java.lang.String instances representing + an id of an authentication scheme. @@ -194,10 +205,13 @@ httpclient.getParams().setParameter(AuthPNames.PROXY_AUTH_PREF, authpref); - Please note NTLM scheme is NOT registered per - default. For details on how to enable NTLM support please refer to - the NTLM_SUPPORT.txt document included with HttpClient - distributions. + Please note NTLM and SPNEGO schemes are + NOT registered per default. For details on how to enable + NTLM support please refer to the + NTLM_SUPPORT.txt document included with HttpClient distributions. + SPNEGO setup tends to be system specific and must be properly + configured in order to be functional. See section on SPNEGO + authentication for details.
Credentials provider @@ -364,112 +378,86 @@ httpclient.addRequestInterceptor(preemptiveAuth, 0); ]]>
-
+
<literal>SPNEGO</literal>/Kerberos Authentication SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) is designed to allow for authentication to services when neither end knows what the other can use/provide. It is most commonly used to do Kerberos authentication. It can wrap other mechanisms, however the current version - in HTTPClient is designed solely with Kerberos in mind. The image below shows a simple - authentication process. - - - - - + in HttpClient is designed solely with Kerberos in mind. - 1. Client Web Browser does HTTP GET for resource. - 2. Web server returns HTTP 401 status and a header: "WWW-Authenticate: - Negotiate - 3. Client generates a NegTokenInit, base64 encodes it, and resubmits the GET with - an Authorization header: "Authorization: Negotiate <base64 - encoding>". - 4. Server decodes the NegTokenInit, extracts the supported MechTypes (only - Kerberos V5 in our case), ensures it is one of the expected ones, and then extracts - the MechToken (Kerberos Token) and authenticates it. - 4a. If more processing is required another HTTP 401 is returned to the client with - more data in the the WWW-Authenticate header. Client takes the info and generates - another token passing this back in the Authorization header.... until - complete. - 5. When the client has been authenticated the Web server should return the HTTP - 200 status, a final WWW-Authenticate header and the page content. + + + Client Web Browser does HTTP GET for resource. + + + Web server returns HTTP 401 status and a header: + WWW-Authenticate: Negotiate + + + Client generates a NegTokenInit, base64 encodes it, and + resubmits the GET with an Authorization header: + Authorization: Negotiate <base64 + encoding>. + + + Server decodes the NegTokenInit, extracts the supported + MechTypes (only Kerberos V5 in our case), ensures it + is one of the expected ones, and then extracts the + MechToken (Kerberos Token) and authenticates + it. + If more processing is required another HTTP 401 is returned to the client + with more data in the the WWW-Authenticate header. Client + takes the info and generates another token passing this back in the + Authorization header until complete. + + + When the client has been authenticated the Web server should return the + HTTP 200 status, a final WWW-Authenticate header and the + page content. + +
- HTTPClient Implementation - - Supports Sun Java versions 1.5 and up. - The JRE provides the supporting classes to do nearly all the kerberos and SPNEGO - token handling. This means that a lot of the setup is for the GSS classes. The - NegotiateScheme is a simple class to handle marshalling the tokens and reading and - writing the correct headers. -
-
- Usage. - - The best way to start is to grab the KerberosHttpClient.java file in examples and - try and get it to work. There are a lot of issues that can happen but if lucky it'll - work without too much problem. It should also provide some output to debug - with. + <literal>SPNEGO</literal> support in HttpClient + SPNEGO authentication scheme is compatible with Sun Java + versions 1.5 and up. + The Sun JRE provides the supporting classes to do nearly all the kerberos and + SPNEGO token handling. This means that a lot of the setup is + for the GSS classes. The NegotiateScheme is a simple class to + handle marshalling the tokens and reading and writing the correct headers. + The best way to start is to grab the KerberosHttpClient.java + file in examples and try and get it to work. There are a lot of issues that can + happen but if lucky it'll work without too much problem. It should also provide some + output to debug with. In windows it should default to using the logged in credentials, this can be overridden by using 'kinit' e.g. $JAVA_HOME\bin\kinit testuser@AD.EXAMPLE.NET, which is very helpful for testing and debugging issues. Remove the cache file created to revert back to the windows Kerberos cache. - Make sure to list domain_realms in the krb5.conf file. This is a major source of - problems. + Make sure to list domain_realms in the + krb5.conf file. This is a major source of problems.
- NegotiateSchemeFactory Class - - NegotiateScheme has a few class properties that can be set. -
-
- setStripPort(boolean) - - Strips the port off service names e.g. HTTP/webserver.ad.example.net:8080 -> - HTTP/webserver.ad.example.net - - Found it useful when using JbossNegotiation. -
-
- setSpnegoCreate(boolean) - - If using Java 1.5 or a Kerberos ticket an attempt will be made to wrap it up into - a SPNEGO token. Again for JbossNegotiation. II7 accepts plain Kerberos - tickets. -
-
- setSpengoGenerator(SpnegoTokenGenerator) - - Inject a custom SpnegoTokenGenerator class to do the Kerberos to SPNEGO token - wrapping. BouncySpnegoTokenGenerator example is provided. This requires the - BouncyCastle libs "http://www.bouncycastle.org/java.html" - -
-
- GSS/Java Kerberos Setup. - - This documentation assumes you are using windows but much of the - informationapplies to Unix as well. - The org.ietf.jgss classes have lots of possible configuration parameters, mainly - in the krb5.conf/krb5.ini file. Some more info on the format at GSS/Java Kerberos Setup + This documentation assumes you are using windows but much of the information + applies to Unix as well. + The org.ietf.jgss classes have lots of possible + configuration parameters, mainly in the + krb5.conf/krb5.ini file. Some more info on + the format at http://web.mit.edu/kerberos/krb5-1.4/krb5-1.4.1/doc/krb5-admin/krb5.conf.html.
- login.conf file - + <literal>login.conf</literal> file The following configuration is a basic setup that works in Windows XP against both - IIS7 and JbossNegotiate modules. - The system property that can be use to point to the login.conf file is - java.security.auth.login.config. - Sample usage... - System.setProperty("java.security.auth.login.config", "login.conf"); - - Example file contents... + IIS7 and JbossNegotiate modules. + The system property java.security.auth.login.config can be use + to point at the login.conf file. + login.conf content may look like the following:
- krb5.conf/krb5.ini file - If unspecified the system default will be used. Override with... - System.setProperty("java.security.krb5.conf", "krb5.conf"); - Example file contents... - + <literal>krb5.conf</literal> / <literal>krb5.ini</literal> file + If unspecified the system default will be used. Override if needed by the setting + system property java.security.krb5.conf to point at a custom + krb5.conf file. + krb5.conf content may look like the following:
- Windows Specific help - To allow windows to use the current users tickets do ... - System.setProperty("javax.security.auth.useSubjectCredsOnly","false"); - and ... + Windows Specific configuration + To allow windows to use the current users tickets system property + javax.security.auth.useSubjectCredsOnly must be set to + false and Windows registry key + allowtgtsessionkey should be added and set correctly to allow + session keys to be sent in the Kerberos Ticket-Granting Ticket. + On the Windows Server 2003 and Windows 2000 SP4, here is the required registry + setting: + + Here is the location of the registry setting on Windows XP SP2: + - + +
+
+ Activating and customizing <literal>SPNEGO</literal> authentication + scheme + Please note SPNEGO authentication scheme is NOT active per + default! + In order to activate SPNEGO support an instance of + NegotiateSchemeFactory class must be created and + registered with the authentication scheme registry of HttpClient. + + + There are several methods that can be used to customize the behaviour of + NegotiateSchemeFactory. +
+ + <methodname>setStripPort</methodname> + + Strips the port off service names e.g. + HTTP/webserver.ad.example.net:8080 -> + HTTP/webserver.ad.example.net + Found it useful when using JbossNegotiation. +
+
+ + <methodname>setSpnegoCreate</methodname> + + If using Java 1.5 or a Kerberos ticket an attempt will be made to wrap it up + into a SPNEGO token. Again for JbossNegotiation. II7 accepts + plain Kerberos tickets. +
+
+ + <methodname>setSpengoGenerator</methodname> + + Use this method to inject a custom + SpnegoTokenGenerator class to do the Kerberos + to SPNEGO token wrapping. + BouncySpnegoTokenGenerator implementation is provided + as unsupported contribution from the contrib package. This requires the + BouncyCastle libs "http://www.bouncycastle.org/java.html" + +