~~ Licensed under the Apache License, Version 2.0 (the "License");
~~ you may not use this file except in compliance with the License.
~~ You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing, software
~~ distributed under the License is distributed on an "AS IS" BASIS,
~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~~ See the License for the specific language governing permissions and
~~ limitations under the License. See accompanying LICENSE file.

  ---
  Hadoop Auth, Java HTTP SPNEGO ${project.version} - Examples
  ---
  ---
  ${maven.build.timestamp}

Hadoop Auth, Java HTTP SPNEGO ${project.version} - Examples

* Accessing a Hadoop Auth protected URL Using a browser

  <<IMPORTANT:>> The browser must support HTTP Kerberos SPNEGO. For example,
  Firefox or Internet Explorer.

  For Firefox access the low level configuration page by loading the
  <<<about:config>>> page. Then go to the
  <<<network.negotiate-auth.trusted-uris>>> preference and add the hostname or
  the domain of the web server that is HTTP Kerberos SPNEGO protected (if using
  multiple domains and hostname use comma to separate them).
  
* Accessing a Hadoop Auth protected URL Using <<<curl>>>

  <<IMPORTANT:>> The <<<curl>>> version must support GSS, run <<<curl -V>>>.

+---+
$ curl -V
curl 7.19.7 (universal-apple-darwin10.0) libcurl/7.19.7 OpenSSL/0.9.8l zlib/1.2.3
Protocols: tftp ftp telnet dict ldap http file https ftps
Features: GSS-Negotiate IPv6 Largefile NTLM SSL libz
+---+

  Login to the KDC using <<kinit>> and then use <<<curl>>> to fetch protected
  URL:

+---+
$ kinit
Please enter the password for tucu@LOCALHOST:
$ curl --negotiate -u foo -b ~/cookiejar.txt -c ~/cookiejar.txt http://localhost:8080/hadoop-auth-examples/kerberos/who
Enter host password for user 'tucu':

Hello Hadoop Auth Examples!
+---+

  * The <<<--negotiate>>> option enables SPNEGO in <<<curl>>>.

  * The <<<-u foo>>> option is required but the user ignored (the principal
    that has been kinit-ed is used).

  * The <<<-b>>> and <<<-c>>> are use to store and send HTTP Cookies.

* Using the Java Client

  Use the <<<AuthenticatedURL>>> class to obtain an authenticated HTTP
  connection:

+---+
...
URL url = new URL("http://localhost:8080/hadoop-auth/kerberos/who");
AuthenticatedURL.Token token = new AuthenticatedURL.Token();
...
HttpURLConnection conn = new AuthenticatedURL(url, token).openConnection();
...
conn = new AuthenticatedURL(url, token).openConnection();
...
+---+

* Building and Running the Examples

  Download Hadoop-Auth's source code, the examples are in the
  <<<src/main/examples>>> directory.

** Server Example:

  Edit the <<<hadoop-auth-examples/src/main/webapp/WEB-INF/web.xml>>> and set the
  right configuration init parameters for the <<<AuthenticationFilter>>>
  definition configured for Kerberos (the right Kerberos principal and keytab
  file must be specified). Refer to the {{{./Configuration.html}Configuration
  document}} for details.

  Create the web application WAR file by running the <<<mvn package>>> command.

  Deploy the WAR file in a servlet container. For example, if using Tomcat,
  copy the WAR file to Tomcat's <<<webapps/>>> directory.

  Start the servlet container.

** Accessing the server using <<<curl>>>

  Try accessing protected resources using <<<curl>>>. The protected resources
  are:

+---+
$ kinit
Please enter the password for tucu@LOCALHOST:

$ curl http://localhost:8080/hadoop-auth-examples/anonymous/who

$ curl http://localhost:8080/hadoop-auth-examples/simple/who?user.name=foo

$ curl --negotiate -u foo -b ~/cookiejar.txt -c ~/cookiejar.txt http://localhost:8080/hadoop-auth-examples/kerberos/who
+---+

** Accessing the server using the Java client example

+---+
$ kinit
Please enter the password for tucu@LOCALHOST:

$ cd examples

$ mvn exec:java -Durl=http://localhost:8080/hadoop-auth-examples/kerberos/who

....

Token value: "u=tucu,p=tucu@LOCALHOST,t=kerberos,e=1295305313146,s=sVZ1mpSnC5TKhZQE3QLN5p2DWBo="
Status code: 200 OK

You are: user[tucu] principal[tucu@LOCALHOST]

....

+---+