Package org.silverpeas.sso.kerberos.spnego

# Class SpnegoHttpURLConnection

java.lang.Object
org.silverpeas.sso.kerberos.spnego.SpnegoHttpURLConnection

public final class SpnegoHttpURLConnection extends Object
This Class may be used by custom clients as a convenience when connecting to a protected HTTP server.

This mechanism is an alternative to HTTP Basic Authentication where the HTTP server does not support Basic Auth but instead has SPNEGO support (take a look at `KerberosSpnegoFilter`).

A krb5.conf and a login.conf is required when using this class. Take a look at the spnego.sourceforge.net documentation for an example krb5.conf and login.conf file. Also, you must provide a keytab file, or a username and password, or allowtgtsessionkey.

Example usage (username/password):

         public static void main(final String[] args) throws Exception {
             System.setProperty("java.security.krb5.conf", "krb5.conf");
             System.setProperty("sun.security.krb5.debug", "true");
             System.setProperty("java.security.auth.login.config", "login.conf");

             SpnegoHttpURLConnection spnego = null;

             try {
                 spnego = new SpnegoHttpURLConnection("spnego-client", "dfelix", "myp@s5");
                 spnego.connect(new URL("http://medusa:8080/index.jsp"));

                 System.out.println(spnego.getResponseCode());

             } finally {
                 if (null != spnego) {
                     spnego.disconnect();
                 }
             }
         }

Alternatively, if the server supports HTTP Basic Authentication, this Class is NOT needed and instead you can do something like the following:

         public static void main(final String[] args) throws Exception {
             final String creds = "dfelix:myp@s5";

             final String token = Base64.encode(creds.getBytes());

             URL url = new URL("http://medusa:8080/index.jsp");

             HttpURLConnection conn = (HttpURLConnection) url.openConnection();

             conn.setRequestProperty(Constants.AUTHZ_HEADER
                     , Constants.BASIC_HEADER + " " + token);

             conn.connect();

             System.out.println("Response Code:" + conn.getResponseCode());
         }

To see a working example and instructions on how to use a keytab, take a look at the creating a client keytab example.

Finally, the `SpnegoSOAPConnection` class is another example of a class that uses this class.

Author:
  Darwin V. Felix

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SpnegoHttpURLConnection(String loginModuleName)`
  Creates an instance where the LoginContext relies on a keytab file being specified by "java.security.auth.login.config" or where LoginContext relies on tgtsessionkey.
  `SpnegoHttpURLConnection(String loginModuleName, String username, String password)`
  Creates an instance where the LoginContext does not require a keytab file.
  `SpnegoHttpURLConnection(GSSCredential creds)`
  Create an instance where the GSSCredential is specified by the parameter and where the GSSCredential is automatically disposed after use.
  `SpnegoHttpURLConnection(GSSCredential creds, boolean dispose)`
  Create an instance where the GSSCredential is specified by the parameter and whether the GSSCredential should be disposed after use.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addRequestProperty(String key, String value)`
  Adds an HTTP Request property.
  `HttpURLConnection`
  `connect(URL url, ByteArrayOutputStream dooutput)`
  `HttpURLConnection`
  `connect(URL url, Proxy proxy, ByteArrayOutputStream output)`
  Opens a communications link to the resource referenced by this URL, if such a connection has not already been established.
  `void`
  `disconnect()`
  Logout and clear request properties.
  `InputStream`
  `getErrorStream()`
  Returns an error stream that reads from this open connection.
  `InputStream`
  `getInputStream()`
  Returns an input stream that reads from this open connection.
  `boolean`
  `isContextEstablished()`
  Returns true if GSSContext has been established.
  `void`
  `requestCredDeleg(boolean requestDelegation)`
  Request that this GSSCredential be allowed for delegation.
  `void`
  `setRequestMethod(String method)`
  May override the default GET method.
  `void`
  `setRequestProperty(String key, String value)`
  Sets an HTTP Request property.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### SpnegoHttpURLConnection

    public SpnegoHttpURLConnection(String loginModuleName) throws LoginException
    Creates an instance where the LoginContext relies on a keytab file being specified by "java.security.auth.login.config" or where LoginContext relies on tgtsessionkey.
    Parameters:
      `loginModuleName` - name of the login module
    Throws:
      `LoginException` - if the authentication fails

  - ### SpnegoHttpURLConnection

    public SpnegoHttpURLConnection(GSSCredential creds)
    Create an instance where the GSSCredential is specified by the parameter and where the GSSCredential is automatically disposed after use.
    Parameters:
      `creds` - credentials to use

  - ### SpnegoHttpURLConnection

    public SpnegoHttpURLConnection(GSSCredential creds, boolean dispose)
    Create an instance where the GSSCredential is specified by the parameter and whether the GSSCredential should be disposed after use.
    Parameters:
      `creds` - credentials to use
      `dispose` - true if GSSCredential should be diposed after use

  - ### SpnegoHttpURLConnection

    public SpnegoHttpURLConnection(String loginModuleName, String username, String password) throws LoginException
    Creates an instance where the LoginContext does not require a keytab file. However, the "java.security.auth.login.config" property must still be set prior to instantiating this object.
    Parameters:
      `loginModuleName` - the name of the login module
      `username` - the login id of the user
      `password` - the password of the user
    Throws:
      `LoginException` - if the authentication fails.

- ## Method Details

  - ### connect

    public HttpURLConnection connect(URL url, ByteArrayOutputStream dooutput) throws GSSException, PrivilegedActionException, IOException
    Throws:
      `GSSException`
      `PrivilegedActionException`
      `IOException`

  - ### connect

    public HttpURLConnection connect(URL url, Proxy proxy, ByteArrayOutputStream output) throws GSSException, PrivilegedActionException, IOException
    Opens a communications link to the resource referenced by this URL, if such a connection has not already been established.
    Parameters:
      `url` - the URL of the resource
      `proxy` - a possible proxy to use to establish a connection with the resource
      `output` - optional message/payload to send to server
    Returns:
      an HttpURLConnection object
    Throws:
      `GSSException` - if the SSO negotiation fails
      `PrivilegedActionException` - if a disallowed action is performed.
      `IOException` - if an IO occurs during the connection
    See Also:
      - `URLConnection.connect()`

  - ### disconnect

    public void disconnect()
    Logout and clear request properties.
    See Also:
      - `HttpURLConnection.disconnect()`

  - ### isContextEstablished

    public boolean isContextEstablished()
    Returns true if GSSContext has been established.
    Returns:
      true if GSSContext has been established, false otherwise.

  - ### addRequestProperty

    public void addRequestProperty(String key, String value)
    Adds an HTTP Request property.
    Parameters:
      `key` - request property name
      `value` - request propery value
    See Also:
      - `URLConnection.addRequestProperty(String, String)`

  - ### setRequestProperty

    public void setRequestProperty(String key, String value)
    Sets an HTTP Request property.
    Parameters:
      `key` - request property name
      `value` - request property value
    See Also:
      - `URLConnection.setRequestProperty(String, String)`

  - ### getErrorStream

    public InputStream getErrorStream()
    Returns an error stream that reads from this open connection.
    Returns:
      error stream that reads from this open connection
    See Also:
      - `HttpURLConnection.getErrorStream()`

  - ### getInputStream

    public InputStream getInputStream() throws IOException
    Returns an input stream that reads from this open connection.
    Returns:
      input stream that reads from this open connection
    Throws:
      `IOException` - if an IO error occurs
    See Also:
      - `URLConnection.getInputStream()`

  - ### requestCredDeleg

    public void requestCredDeleg(boolean requestDelegation)
    Request that this GSSCredential be allowed for delegation.
    Parameters:
      `requestDelegation` - true to allow/request delegation

  - ### setRequestMethod

    public void setRequestMethod(String method)
    May override the default GET method.
    Parameters:
      `method` - the HTTP method to use
    See Also:
      - `HttpURLConnection.setRequestMethod(String)`