Authenticator pattern

What is the Authenticator pattern?

This security pattern is used to implement an authentication mechanism. A class diagram of the pattern is given below.

This pattern allows Subject to be authenticated using a set of objects known as Authentication Information.

These objects are used by an Authenticator to generate a security token known as Proof of Identity.

The authentication mechanism is the generation of Proof of Identity by an Authenticator from a Subject Authentication Information and its assignment in a specific field of the subject class.

How to use the pattern?

Subject entity

• Identify the Subject class. It is the class whose instance you need to authenticate. This class should be annotated with @ModelEntity (to let the PAMELA Framework that it is part of your model) and @AuthenticationSubject(patternID = <patternID>) (to declare this model entity as a subject for the authentication pattern). The <patternid> is a String that identify you pattern. You could, for instance, have the following code:

@ModelEntity
@AuthenticatorSubject("Authenticator pattern 1")
public class MySubject {
    ...
}

• Identify the getter(s) of the Authentication Information of the subject class. The Authentication information are the objects provided by Subjects to be authenticated. These method should be annotated with @AuthenticationInformation(patternID = <patternID>, paramID = <paramID>). Make sure to use the same <patternID> for all the annotations related to the same pattern.. The <paramID> is a string identifying a getter. You could, for instance, have the following code:

@ModelEntity
@AuthenticatorSubject(patternID = "Authenticator pattern 1")
public class MySubject {
    
    @AuthenticationInformation(patternID = "Authenticator pattern 1", paramID = "username")
    public String getUsername(){
        ...
    }

    @AuthenticationInformation(patternID = "Authenticator pattern 1", paramID = "password")
    public int getPasswordHash(){
        ...
    }
}

• Identify the Proof of Identity getter and setter of the Subject. The Proof of Identity is the security token that will be given the Subjects by the Authenticator, once the authentication is done. You should annotate theses methods respectively with @ProofOfIdentityGetter(patternID = <patternID>) and @ProofOfIdentitySetter(patternID = <patternID>). You could, for instance, have the following code:

@ModelEntity
@AuthenticatorSubject(patternID = "Authenticator pattern 1")
public class MySubject {
    
    @AuthenticationInformation(patternID = "Authenticator pattern 1", paramID = "username")
    public String getUsername(){
        ...
    }

    @AuthenticationInformation(patternID = "Authenticator pattern 1", paramID = "password")
    public int getPasswordHash(){
        ...
    }

    @ProofOfIdentityGetter(patternID = "Authenticator pattern 1")
    public SecurityToken getSecurityToken(){
        ...
    }

    @ProofOfIdentitySetter(patternID = "Authenticator pattern 1")
    public void setSecurityToken(SecurityToken token){
        ...
    }
}

• Identify the getter of the Authenticator class and annotated it with @AuthenticatorGetter(patternID = <patternID>). Your could, for instance have the following code.

@ModelEntity
@AuthenticatorSubject(patternID = "Authenticator pattern 1")
public class MySubject {
    
    @AuthenticationInformation(patternID = "Authenticator pattern 1", paramID = "username")
    public String getUsername(){
        ...
    }

    @AuthenticationInformation(patternID = "Authenticator pattern 1", paramID = "password")
    public int getPasswordHash(){
        ...
    }

    @ProofOfIdentityGetter(patternID = "Authenticator pattern 1")
    public SecurityToken getSecurityToken(){
        ...
    }

    @ProofOfIdentitySetter(patternID = "Authenticator pattern 1")
    public void setSecurityToken(SecurityToken token){
        ...
    }

    @AuthenticatorGetter(patternID = "Authenticator pattern 1")
    public MyAuthenticator getAuthenticator(){
        ...
    }
}

• Finally, you just need to add an abstract method (or empty method if the class is not abstract) with the annotation @AuthenticateMethod(patternID = <patternID>). Note that this method can have a body if you want. This method is the one which will be trigger the authentication at each call. You could for instance have the following code:

@ModelEntity
@AuthenticatorSubject(patternID = "Authenticator pattern 1")
public class MySubject {
    
    @AuthenticationInformation(patternID = "Authenticator pattern 1", paramID = "username")
    public String getUsername(){
        ...
    }

    @AuthenticationInformation(patternID = "Authenticator pattern 1", paramID = "password")
    public int getPasswordHash(){
        ...
    }

    @ProofOfIdentityGetter(patternID = "Authenticator pattern 1")
    public SecurityToken getSecurityToken(){
        ...
    }

    @ProofOfIdentitySetter(patternID = "Authenticator pattern 1")
    public void setSecurityToken(SecurityToken token){
        ...
    }

    @AuthenticatorGetter(patternID = "Authenticator pattern 1")
    public MyAuthenticator getAuthenticator(){
        ...
    }

    @AuthenticateMethod(patternID = "Authenticator pattern 1")
    public void authenticate(){
        System.out.println("Authentication succeed, the proof of identity is now " + getSecurityToken());
    }
}

Authenticator entity

• Identify the Authenticator class. It is the class whose instance will authenticate Subjects. This class should be annotated with @ModelEntity and @Authenticator(patternID = <patternID>). Once again, the <patternID> should be the same as the one used to annotated the`Subject class. You could, for instance, have the following code:

@ModelEntity
@Authenticator("Authenticator pattern 1")
public class MyAuthenticator {
    ...
}

• Identify the request method. This method is the one which is called when a subject try to authenticate. Its role is to check the Authentication Information (given as parameter of the method) and return a Proof of Identity. it should be annotated with @RequestMethod(patternID = <patternID>). The parameter of this method should also be annotated with the annotation of the associated Authentication Information getters. You could, for instance, have the following code:

@ModelEntity
@Authenticator(patternID = "Authenticator pattern 1")
public class MyAuthenticator {
    
    @RequestMethod(patternID = "Authenticator pattern 1")
    public SecurityToken createToken(@AuthenticationInformation(patternID = "Authenticator pattern 1", paramID = "username") String username, @AuthenticationInformation(patternID = "Authenticator pattern 1", paramID = "password") int password){
        ...
    }
}

How does it work?

Once the Subject and Authenticator classes are correctly annotated, the PAMELA framework will ensure:

• That every call to the authenticate method of any subject will update its proof of identity with the result of its authenticator request method.
• That the Proof of identity of every subject is always valid (that is the result of the request method of its authenticator). This prevents the Subjects from forging a Proof of Identity.
• That the Authentication information and Authenticator fields of the Subject class are final. Once they are assigned, their value should never change. This prevents the Subjects from forging their Authentication Information or their Authenticator.
• That different Subjects have different Authentication Information. In the example above, different couples (login, hash).

Extra: You can annotate has many Subject methods as you want with @RequiresAuthentication(patternID = <patternID>. This annotation will ensure that every call to the method will first trigger the authentication process (call to the Subject authenticate method).