[OmniFaces utilities 2.0] Programmatically login/authenticate/logout in JSF

---

[OmniFaces utilities] The login() method perform programmatic login for container managed FORM based authentication. Note that configuration is container specific and unrelated to JSF. Refer the documentation of the servletcontainer using the keyword "realm".

[OmniFaces utilities] The authenticate() trigger the default container managed authentication mechanism on the current request. It expects the username and password being available as predefinied request parameters on the current request and/or a custom JASPIC implementation.
Note The caller should preferably not catch the potential IOException, but just redeclare it in the action method. The Servlet container will handle it.

[OmniFaces utilities] The logout() method perform programmatic logout for container managed FORM based authentication. Note that this basically removes the user principal from the session. It's however better practice to just invalidate the session altogether, which will implicitly also remove the user principal. Just invoke #invalidateSession() instead. Note that the user principal is still present in the response of the current request, it's therefore recommend to send a redirect after #logout() or #invalidateSession(). You can use #redirect(String, String...) for this.

---

Method Faces#login() - perform programmatic login for container managed FORM based authentication

See also: Faces#getContext() | Faces#getRequest()

Method Faces#authenticate() - trigger the default container managed authentication mechanism on the current request

See also: Faces#getContext() | Faces#getRequest() | Faces#getResponse()

Method Faces#logout() - perform programmatic logout for container managed FORM based authentication

See also: Faces#getContext() | Faces#getRequest()

Usage:

The configuration of a FORM based authentication is specific to container. For example, if you are familiar with GlassFish 3/4, then you know that you must follow an entire process of configurations. Basically, you need to register a realm, declare the roles and groups (e.g. via <security-role-mapping>, <role-name> and   <group-name>) and declare the security constrains (e.g. via <security-constraint>). At the end, configure the login, which may look like this (in web.xml/glassfish-web.xml):

<login-config>

  <auth-method>FORM</auth-method>

  <realm-name>my-realm</realm-name>

  <form-login-config>

    <form-login-page>/faces/login/login.xhtml</form-login-page>

    <form-error-page>/faces/login/error.xhtml</form-error-page>

  </form-login-config>

</login-config>

Finally, you will write the form that it is used by users to login (in login/login.xhtml):

<form action="j_security_check" method="POST">

  <input id="j_username" type="text" name="j_username" placeholder="Username"/>

  <input id="j_password" type="password" name="j_password" placeholder="Password"/>

</form>

In order to login, an user need to type his credentials via this form, while the developer may accomplish the same task programmatically via Faces#login() method. Instead of typing the credentials in the text fields  of this form, is simply pass them as arguments to the login() method:

try {

    Faces.login("admin", "adminpassword");           

    } catch (ServletException ex) {

      Logger.getLogger(MyClass.class.getName()).log(Level.SEVERE, null, ex);

    }

The Faces#login() method is a shortcut for HttpServletRequest#login() method.

If the username and password are available as predefined request parameters on the current request and/or a custom JASPIC then you may want to trigger the default container managed authentication mechanism on the current request implementation. For this, you can use Faces#authenticate() method:

try {

    boolean auth = Faces.authenticate();  // throw IOException 

    if (auth){

        // do something

    }

} catch (ServletException ex) {

    Logger.getLogger(MyClass.class.getName()).log(Level.SEVERE, null, ex);

}

The Faces#authenticate() method is a shortcut for HttpServletRequest#authenticate() method.

If you performed a programmatically login, then probably you will need a programmatically logout. This can be quickly achieve in JSF, via Faces#logout() method (don't forget to follow the recommandations from documentation and invoke after Faces#logout() the Faces#redirect()):

try {

    Faces.logout();
    Faces.redirect(...);  // throw IOException 

    } catch (ServletException ex) {

      Logger.getLogger(MyClass.class.getName()).log(Level.SEVERE, null, ex);

    }

The Faces#logout() method is a shortcut for HttpServletRequest#logout() method.

API GH