Let's take a closer look at an extremely simple example of an Authenticator. The following code demonstrates an Authenticator implementation that simply tests the username and password credentials that the user has provided against hard coded values of jsmith for the username, and abc123 for the password, and if they match then authentication is deemed to be a success:

@PicketLink

public class SimpleAuthenticator extends BaseAuthenticator {


    @Inject DefaultLoginCredentials credentials;


    @Override

    public void authenticate() {

        if ("jsmith".equals(credentials.getUserId()) &&

                "abc123".equals(credentials.getPassword())) {

            setStatus(AuthenticationStatus.SUCCESS);

            setAccount(new User("jsmith"));

        } else {

            setStatus(AuthenticationStatus.FAILURE);

            FacesContext.getCurrentInstance().addMessage(null, new FacesMessage(

                    "Authentication Failure - The username or password you provided were invalid."));

        }

    }

}

The first thing we can notice about the above code is that the class is annotated with the @PicketLink annotation. This annotation indicates that this bean should be used for the authentication process. The next thing is that the authenticator class extends something called BaseAuthenticator. This abstract base class provided by PicketLink implements the Authenticator interface and provides implementations of the getStatus() and getAccount() methods (while also providing matching setStatus() and setAccount() methods), and also provides an empty implementation of the postAuthenticate() method. By extending BaseAuthenticator, our Authenticator implementation simply needs to implement the authenticate() method itself.

We can see in the above code that in the case of a successful authentication, the setStatus() method is used to set the authentication status to SUCCESS, and the setAccount() method is used to set the user (in this case by creating a new instance of User). For an unsuccessful authentication, the setStatus() method is used to set the authentication status to FAILURE, and a new FacesMessage is created to indicate to the user that authentication has failed. While this code is obviously meant for a JSF application, it's possible to execute whichever suitable business logic is required for the view layer technology being used.

One thing that hasn't been touched on yet is the following line of code:

@Inject DefaultLoginCredentials credentials;

This line of code injects the credentials that have been provided by the user using CDI's @Inject annotation, so that our Authenticator implementation can query the credential values to determine whether they're valid or not. We'll take a look at credentials in more detail in the next section.

If your application needs to support multiple authentication methods, you can provide the authenticator selection logic within a producer method annotated with @PicketLink, like so:

@RequestScoped

@Named

public class AuthenticatorSelector {


    @Inject Instance<CustomAuthenticator> customAuthenticator;

    @Inject Instance<IdmAuthenticator> idmAuthenticator;

    

    private String authenticator;

    

    public String getAuthenticator() {

        return authenticator;

    }

    

    public void setAuthenticator(String authenticator) {

        this.authenticator = authenticator;

    }


    @Produces

    @PicketLink

    public Authenticator selectAuthenticator() {

        if ("custom".equals(authenticator)) {

            return customAuthenticator.get();

        } else {

            return idmAuthenticator.get();

        }

    }

}

This @Named bean exposes an authenticator property that can be set by a user interface control in the view layer. If its value is set to "custom" then CustomAuthenticator will be used, otherwise IdmAuthenticator (the Authenticator used to authenticate using the identity management API) will be used instead. This is an extremely simple example but should give you an idea of how to implement a producer method for authenticator selection.

Credentials are something that provides evidence of a user's identity; for example a username and password, an X509 certificate or some kind of biometric data such as a fingerprint. PicketLink has extensive support for a variety of credential types, and also makes it relatively simple to add custom support for credential types that PicketLink doesn't support out of the box itself.

In the previous section, we saw a code example in which a DefaultLoginCredentials (an implementation of the Credentials interface that supports a user ID and a credential value) was injected into the SimpleAuthenticator bean. The most important thing to know about the Credentials interface in relation to writing your own custom Authenticator implementation is that you're not forced to use it. However, while the Credentials interface is mainly designed for use with the Identity Management API (which is documented in a separate chapter) and its methods would rarely be used in a custom Authenticator, PicketLink provides some implementations which are suitably convenient to use as such, DefaultLoginCredentials being one of them.

So, in a custom Authenticator such as this:

public class SimpleAuthenticator extends BaseAuthenticator {


    @Inject DefaultLoginCredentials credentials;

    

    // code snipped

}

The credential injection is totally optional. As an alternative example, it is totally valid to create a request-scoped bean called UsernamePassword with simple getters and setters like so:

public @RequestScoped class UsernamePassword {

    private String username;

    private String password;

    

    public String getUsername() { return username; }

    public String getPassword() { return password; }

    

    public void setUsername(String username) { this.username = username; }

    public void setPassword(String password) { this.password = password; }

}

And then inject that into the Authenticator bean instead:

public class SimpleAuthenticator extends BaseAuthenticator {


    @Inject UsernamePassword usernamePassword;

    

    // code snipped

}

Of course it is not recommended that you actually do this, however this simplistic example serves adequately for demonstrating the case in point.

The DefaultLoginCredentials bean is provided by PicketLink as a convenience, and is intended to serve as a general purpose Credentials implementation suitable for a variety of use cases. It supports the setting of a userId and credential property, and provides convenience methods for working with text-based passwords. It is a request-scoped bean and is also annotated with @Named so as to make it accessible directly from the view layer.

A view technology with support for EL binding (such as JSF) can access the DefaultLoginCredentials bean directly via its bean name, loginCredentials. The following code snippet shows some JSF markup that binds the controls of a login form to DefaultLoginCredentials:

<div class="loginRow">

  <h:outputLabel for="name" value="Username" styleClass="loginLabel"/>

  <h:inputText id="name" value="#{loginCredentials.userId}"/>

</div>



<div class="loginRow">

  <h:outputLabel for="password" value="Password" styleClass="loginLabel"/>

  <h:inputSecret id="password" value="#{loginCredentials.password}" redisplay="true"/>

</div>