Package org.silverpeas.sso.kerberos.spnego

## Class SpnegoAuthenticator

- java.lang.Object
- - org.silverpeas.sso.kerberos.spnego.SpnegoAuthenticator

-     public final class SpnegoAuthenticator
      extends Object

  Handles SPNEGO or Basic authentication.

  Package scope is deliberate; this Class MUST NOT be used/referenced directly outside of this package. Be cautious about who you give a reference to.

  Basic Authentication must be enabled through the filter configuration. See an example web.xml configuration in the installing on tomcat documentation or the `KerberosSpnegoFilter` javadoc.

  Localhost is supported but must be enabled through the filter configuration. Allowing requests to come from the DNS http://localhost will obviate the requirement that a service must have an SPN. Note that Kerberos authentication (if localhost) does not occur but instead simply returns the `System.getProperty("user.name")` or the Server's pre-authentication username.

  NTLM tokens are NOT supported. However it is still possible to avoid an error being returned by downgrading the authentication from Negotiate NTLM to Basic Auth.

  See the reference docs on how to configure the web.xml to prompt when if a request is being made using NTLM.

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

  Author:
    Darwin V. Felix

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SpnegoAuthenticator​(Map<String,​String> config)` | Create an authenticator for SPNEGO and/or BASIC authentication.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `SpnegoPrincipal` | `authenticate​(javax.servlet.http.HttpServletRequest req, SpnegoHttpServletResponse resp)` | Returns the KerberosPrincipal of the user/client making the HTTP request.
    `void` | `dispose()` | Logout.

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

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

- - ### Constructor Detail

    - #### SpnegoAuthenticator

          public SpnegoAuthenticator​(Map<String,​String> config)
                              throws LoginException,
                                     GSSException,
                                     PrivilegedActionException,
                                     FileNotFoundException

      Create an authenticator for SPNEGO and/or BASIC authentication. For third-party code/frameworks that want to authenticate via their own filter/valve/code/etc.

      The ExampleSpnegoAuthenticatorValve.java demonstrates a working example of how to use this constructor.

      Example of some Map keys and values:
      ``

      Map map = new HashMap(); map.put("spnego.krb5.conf", "krb5.conf"); map.put("spnego.allow.basic", "true"); map.put("spnego.preauth.username", "dfelix"); map.put("spnego.preauth.password", "myp@s5"); ...

      SpnegoAuthenticator authenticator = new SpnegoAuthenticator(map); ...
      Parameters:
        `config` - the authentication configuration parameters
      Throws:
        `LoginException` - if the authentication fails
        `GSSException` - if the SSO negotiation fails
        `PrivilegedActionException` - if a disallowed action is performed
        `FileNotFoundException` - if no login configuration file is found

  - ### Method Detail

    - #### authenticate

          public SpnegoPrincipal authenticate​(javax.servlet.http.HttpServletRequest req,
                                              SpnegoHttpServletResponse resp)
                                       throws GSSException,
                                              IOException

      Returns the KerberosPrincipal of the user/client making the HTTP request.

      Null may be returned if client did not provide auth info.

      Method will throw UnsupportedOperationException if client authorization request is NOT "Negotiate" or "Basic".

      Parameters:
        `req` - servlet request
        `resp` - servlet response
      Returns:
        null if auth not complete else SpnegoPrincipal of client
      Throws:
        `GSSException` - if the SSO negotiation fails
        `IOException` - if the IO communication with the Spnego server fails.

    - #### dispose

          public void dispose()

      Logout. Since server uses LoginContext to login/pre-authenticate, we must also logout when we are done using this object.

      Generally, instantiators of this class should be the only to call dispose() as it indicates that this class will no longer be used.