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

    All Methods Instance Methods Concrete Methods
    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 Detail

    - #### 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 Detail

    - #### 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)`