Authentication Scaffolding

Authentication is a must-have feature in most of today's web apps. Almost all the web apps pretty much need the same exact set of authentication features — user registration, email verification, logging and logging out, password resets, etc.

Lots of work is required to wire all the components of an authentication system — controllers, models, views, forms, routing, middleware, validation, notifications, etc. — and to make them properly work. Alpas comes bundled with a make:auth command that does pretty much everything you need to add an authentication system to your app.

In this section we will dive deep into some files and classes generated by alpas make:auth command. We will also see how we can further customize the authentication system to meet our custom needs.

Getting started

To get started, run alpas make:auth command from your terminal. Once the authentication system is scaffolded, call authRoutes() from your routes file.


fun Router.addRoutes() = apply {
    // ...
    authRoutes()
    // ...
}

That's it!

To make sure it actually is working, visit http://localhost:8080/register You should see a nice looking registration form.

Auth Templates

These are the Pebble templates created by make:auth command under resources/templates folder:

  • layout/app.peb

The authentication aware layout file used by all the auth views. It is designed to work for not just auth templates but for your other templates as well. We recommend using this layout file for all of your templates.

  • auth/register.peb

The registration form page.

  • auth/login.peb

The login form page.

  • auth/verify.peb

A page that informs a user to verify their email address after successfully registering and creating a new account.

Alpas uses templates/auth/emails/verify.peb template to style and render the actual email that gets sent.

  • auth/passwords/reset_email.peb

If a user forgets their login password, they can request your app to receive an email with password reset instructions. This page is where they would make that request by providing an email address.

Alpas uses templates/auth/emails/reset.peb template to style and render the actual email that gets sent.

  • auth/passwords/reset.peb

After a user receives a password reset request email and clicks a link to reset, they are taken to this page where they will be asked to set a new password and confirm the password.

  • home.peb

An example template that shows what an authenticated page looks like. You can modify this template or safely remove it along with its corresponding controller: HomeController.kt.

Auth Controllers

All the controllers that are needed to make the scaffolded authentication system work are put under controllers/auth folder. If you open these controllers, you'll notice that every one of them is empty. This is because to make the authentication system work without any further customization, you really don't have to do anything!

For most of the apps, just the default scaffolded behaviour is enough for a functional authentication system. These controller files are generated for you only for further customizations.

  • controllers/auth/LoginController.kt

Handles user login and logout.

auth/login.peb template is the default template used for showing the login form. If you want to use a different template or want to pass some extra arguments, you need to override fun showLoginForm(call: HttpCall) method and call call.render() method yourself.

After a successful login, users are redirected to the original intended route. If there is no intended route, they are redirected to /home route. If you want to redirect them to somewhere else, override the fun afterLoginRedirectTo(call: HttpCall) method.

Similarly, users are redirected to / route after they logout. You can change the redirected route by overriding fun afterLogoutRedirectTo(call: HttpCall) method.

  • controllers/auth/RegisterController.kt

Handles user registration.

auth/register.peb template is used for showing the registration form. If you want to use a different template or want to pass some extra arguments, you need to override fun showRegistrationForm(call: HttpCall) method and call call.render() method yourself.

After a successful registration, a new User record is inserted in UsersTable and the user is redirected to /login route. If you want to redirect them to somewhere else, override the fun afterRegisterRedirectTo(call: HttpCall) method.

  • controllers/auth/ForgotPasswordController.kt

Handles password reset requests by asking users for the email address that is associated with the account that they would like to reset the password for. The template that contains the form is auth.passwords.reset_email, which you can override in fun showResetLinkRequestForm(call: HttpCall) method.

After verification, a password reset email containing a signed link is sent to the user and are then redirected to the same page containing the form but with a flashed successful message. If you want to redirect them to somewhere else, override the fun afterResetLinkSentRedirectTo(call: HttpCall): String? method and return a different route.

  • controllers/auth/PasswordResetController.kt

Handles actual password resets by showing a reset form asking the user for a new password. The form is rendered using auth/passwords/reset template. Both email and token parameters are passed to the template when rendering.

After the successful reset, users are automatically logged in and then redirected to / route. If you want to redirect them to somewhere else, override the fun afterResetRedirectTo(call: HttpCall) method.

  • controllers/auth/EmailVerificationController.kt

Handles user's email verification process.

If a user's email is already verified, it redirects the user to /home route. It also redirects to the same /home route after a successful verification as well as after (re)sending a verification email. Override the fun ifVerifiedRedirectTo(call: HttpCall): String method if you want to route them to somewhere else.

  • controllers/HomeController.kt

An example controller that just renders a home template.

You can also see how a VerifiedEmailOnlyMiddleware is applied to this controller. This means only verified users can access this controller. If you want to see this controller in action you need to reference it from one of your routes.

Feel free to modify this controller further or remove it completely; it is not referenced by any routes by default.

Previous Topic Next Topic