OpenWGA 7.5 - OpenWGA Concepts and Features

Authentication » Special features

Custom login pages

The normal way to login to OpenWGA domains is to use the default OpenWGA Login Page. You can generate a URL to this login page using <tml:url type="login"/>.

However for special projects you may want to create your own login page, for example to follow some corporate identity guideline, or to embed login functionality into a page which also does other tasks.

There are two techniques to write custom login pages in OpenWGA.

Login via custom HTML form

This technique actually does the same as the default OpenWGA login form. By posting a simple HTML form with fields of predefined names to a special URL you can simulate the login process which is done by the default login page.

Main downside of this technique is that you have little control about the login process and what happens on success or failure.

The form must meet the following conditions:

  • The method of the form must be POST
  • The action of the form (the URL it is posted to) must be "/login" (relative to the context path of the OpenWGA web application, if this is no default installation)
  • The following fields must be sent
    • domain: Name of the OpenWGA domain for which the login should be
    • username: Login user name
    • password: Login password
  • The following optional fields may be sent
    • redirect: An URL to which OpenWGA should automatically redirect after a successful login

Here is an example form:

<form method="POST" action="<tml:meta name="wgaurl"/>/login">">


Username: <input name="username"><br>

Password: <input name="password" type="password"><br>


<input type="submit" value="Login">


<input type="hidden" name="domain" value="default"/>

<input type="hidden" name="redirect" value="<tml:url type="homepage"/>"/>


</form>

Note that this is no WebTML form but a very simple HTML form. However we assume this code is used within a WebTML module since we use WebTML to retrieve the OpenWGA base URL for the "action" attribute and the homepage of the app for field "redirect".

If the login succeeds then OpenWGA will redirect to the URL given as field "redirect", or - if that is missing - back to the referrer URL of the login page.

If the login fails then an URL parameter "loginerror" is given to indicate the source of the problem. Currently it always returns "1" as value, to indicate that the login credentials were incorrect. The code of the login page can test for this parameter and show an error message accordingly.

Login via TMLScript

As there are methods to perform a login in TMLScript we can also build some WebTML/TMLScript based login functionality. Core part is the TMLScript method WGA.Auth.login(), which actually performs the login.

As the login will be in some TMLScript functionality, most likely a WebTML action, you will have complete control about the login process.

The downside of this technique is, that OpenWGA starts the request which performs the login action unauthorized. So also the accessed app will be opened anonymous. Only in the process of the action the user will get authenticated and will get the right to start an authenticated session on the app. This has two implications:

  • This technique only works when the user has anonymous access to the app hosting the login page. If your app should not want to allow anonymous access then you might need to host your login page on some separate app, whose sole purpose may be to be accessible for anonymous and host functionality needing this.
  • In case the login succeeds then the current app will still be opened anonymously, because that was the authentication that was used at the beginning of the request to open the app. In order to retrieve the page with authentication you should do a redirect at the end of the login action.

This is an example of a WebTML based authentication functionality:

<tml:action id="doLogin">

  if (!WGA.Auth.login(tmlform.username, tmlform.password)) {

tmlform.addMessage("Invalid user or password");

return false;

  }


   WGA.redirectTo(context("name:home").contentURL());

</tml:action>


<tml:form id="login" defaultaction="doLogin">

  

  <div class="inputerror">

    <tml:formmessages/>

  </div>

  Username:  <tml:input name="username" id="username" focus="true"/><br>

  Password: <tml:input name="password" type="password" id="password"/>


  <button type="submit">login</button>


</tml:form>

Note that we use WebTML form functionality to issue a login error message, dependent on the return value of WGA.Auth.login(). Also note the redirect we do at the end of the action, which will guide the browser to the OpenWGA page of name "home".

Another detail of this form is, that it does not provide a WebTML button, but rather a simple HTML submit button. Instead it uses the atttribute "defaultaction"  on <tml:form> to determine what should happen on a simple submit. This techique will let browsers send the login form simply by hitting the enter button, which is more comfortable than to force the user to actually click the button.