The form login is a mechanism, that allows you to create a custom login form, by which way a user may enter the OX frontend. All you need to do, is have the form POST the necessary login information and the location of the OX frontend. The OX server will create a session, set all necessary cookies and forward the browser to the frontend.
The parameters that the OX servers login process expects are:
- The login name. This will usually be a text input.
- The users password. This will usually be a password input field.
- The client parameter used to distinguish between programs using the same cookie store. Since we want the new session to be used by the AJAX frontend, we'll set this to com.openexchange.ox.gui.dhtml for the OX6 frontend, to open-xchange-appsuite for App Suite and com.openexchange.mobileapp for the Mobile UI. This is a hidden field. See also OXSessionGlossary
- A version string. The content is not really relevant, but it will be logged, so we can later find out, where a login request came from. The UI will usually send its version, we'll send Form Login so we can see in the logfile when our spiffy new form was used to log in. This will also be a hidden field.
- This tells the frontend whether to attempt to store the session data for a later autologin. This can only be true if server configuration parameter com.openexchange.sessiond.autologin is enabled as well, otherwise the UI will attempt to store the session and trigger a server error. See OXSessionAutologin for more details about the autologin process.
- A random string used for tracking a login requests way through your apache / OX setup.
So, in essence, what we need is a form for POSTing to the backend with the above parameters. This is pretty basic HTML stuff:
Notice the form sends its entries to /ajax/login?action=formlogin. This relative URL will only work if the form is accessed using the same host name as the OX server. If you want to send the user to the OX server from a different host, specify the whole address in the forms action attribute, e.g. https://ox.mydomain.com/ajax/login?action=formlogin. The uiWebPath though is always considered relative to the OX server (regardless of where the form resides), so you're usually good when using a relative link there.
What happens if an error occurs during the login process? For example, the user might have entered the wrong password? In that case the OX Server uses an error template, you may override, to display an error message. It's basic, but functional:
What does it do? It displays the error message for 5 seconds and the redirects back to the referrer, meaning: Your form. It adds a login=failed parameter to the URL, so your form may react when something went wrong. If you think (like myself) this form lacks the, ah well, je-ne-sais-quoi of a nice error page, then fret not! You can provide your own custom template. To do that, open up the file /opt/openexchange/etc/login.properties and set the com.openexchange.ajax.login.errorPageTemplate to point to a file on the OX system that contains your template. For example:
Then write the template. Keep in mind, that ERROR_MESSAGE will be replaced by the actual error message of the login attempt (say "Your password was not valid" or somesuch). The template above might be a good starting point for you to start experimenting.