Version 10

    <<< Go Back to Security Requirements Document



    This article will talk about the various design elements involved in an authentication api.

    Goals to consider:

    • Non-protocol based mechanisms where the principal passes tokens to the authentication framework - credential, certificate, OTP etc.
    • Protocol based mechanisms such as HTTPDigest, HTTPForm, HTTPBasic etc which can retrieve the user token in a predefined manner.
    • Identity Store that has the Principal's information (credential, serial number, certificate etc).
    • Challenge/Response based semantics (SASL, Nonces/Digest) have to be considered.
    • Minimize indirections such that the API is flexible, extensible yet easy to understand.


    Potential API proposal


    We need an AuthenticationManager that needs to be provided an AuthenticationMechanism.



    interface AuthenticationManager{
       Principal authenticate(AuthenitcationMechanism);


    Now the authentication mechanism can either be protocol based or non-protocol based.


    interface AuthenticationMechanism{
       void setAuthenticationStore(AuthenticationStore authStore);
       Principal authenticate();
    interface DirectAuthenticationMechanism<T> extends AuthenticationMechanism{
       void setUserPassedToken(T token);


    Examples of various AuthenticationMechanism that are protocol driven are as follows


    class HTTPDigestAuthenticationMechanism implements AuthenticationMechanism{
    class HTTPFormAuthenticationMechanism implements AuthenticationMechanism{
    class HTTPBasicAuthenticationMechanism implements AuthenticationMechanism{
    class HTTPCertAuthenticationMechanism implements AuthenticationMechanism{
    class HTTPHeaderAuthenticationMechanism implements AuthenticationMechanism{
    class HTTPCookieAuthenticationMechanism implements AuthenticationMechanism{



    An AuthenticationStore is just a representation of a backend store.



    inteface AuthenticationStore{
      T getUserToken(String userIdentifier);
    class LDAPStore implements AuthenticationStore<char[]>{
       char[] getUserToken(String userDN);



    A non-protocol authentication mechanism will look as follows.  In this case, the user passed token needs to be injected into the mechanism as it does not known how to retrieve it (unlike the http based schemes where they do request.getHeader, request.getParameter or request.getCookie based on the semantics of the mechanism involved).


    class CredentialAuthenticationMechanism implements DirectAuthenticationMechanism<char[]>{
        void setUserPassedToken(char[] pass);
    class CertificateAuthenticationMechanism implements DirectAuthenticationMechanism<X509Certificate>{
        void setUserPassedToken(X509Certificate


    Challenge/Response based mechanisms


    When there is HTTP involved, then the challenge/response mechanisms are primarily HTTP/Digest and SPNego interactions.


    In a non http setup,  SASL is the preferred API for challenge/response based systems.


    PicketBox will build on jboss-sasl project from Remoting3.