Authentication

• Auth Channels and User Providers
  • Auth Channel
  • User Provider
  • Auth Channel Registration
• HttpCall and Authentication
• Custom Auth Channel
• Route Auth Channels
• Authentication Middleware

/info/ This section contains some advanced concepts, and many times dives deeper into some internal workings of Alpas. This is done intentionally to teach how authentication works to those who are unfamiliar with it as well as talk about Alpas's internal implementation for the curious among us. It is okay if you get overwhelmed and/or get confused. Just read it once, take a break, and come back again when you feel like it and read it again. Eventually it will click!

Alpas comes with an authentication system setup right out-of-box and requires you to do the absolute minimal to integrate it with your app. It is easy to get started with just one simple Alpas command.

Authentication sounds magical and complex. But, at the core mechanism, is a very simple — you look for an id, and you match the id. If the id matches, you fetch more information about that id and mark the current session being authenticated. That's it!

However, there are a few moving parts that make this magic work. Before we get into scaffolding an authentication boilerplate, let's talk about some core concepts that you need to understand about authentication first.

Auth Channels and User Providers

At the core, Alpas's authentication is divided into two parts — auth channels and user providers. Channels define how users are authenticated for each incoming request. SessionAuthChannel is an example of an authentication channel that determines whether a user is authenticated or not based on sessions and cookies.

For a modern web app, only determining whether a user is authenticated or not isn't enough. You need to know more about the user as well. This is where providers come into play. They are responsible for retrieving user information from a persistent storage such as a database. Alpas ships with one such UserProvider class already wired to retrieve user info from a database.

Auth Channel

Each HttpCall gets its own instance of an AuthChannel that you can use for authentication related tasks. SessionAuthChannel is one of the concrete implementations of AuthChannel but there could be more including one of your own.

The following methods are few of the methods available on AuthChannel. Let's see them through the lens of SessionAuthChannel implementation.

User Provider

A concrete implementation of UserProvider interface is responsible for fetching a user from a persistent store.

When we were talking about AuthChannel, notice how we were careful not talking retrieving user from a database!

While for most apps it is true that you would be fetching users from a database; but, that is just the implementation details. UserProvider's consumer doesn't care how you retrieve a user as long as you correctly retrieve it. In fact, you can write your own implementation of UserProvider that looks up a user in a hashmap if you want as long as your implementation provides the following two methods:

Auth Channel Registration

You can configure what AuthChannel to use by default in multiple ways.

When scaffolding a new project, Alpas creates an AuthConfig class for you. If you open it, you'll see that it adds a new channel under session name. Notice how the value of the channel is not an instance of SessionAuthChannel but is a callback that creates the actual instance.

As discussed earlier, a new instance of an auth channel is created for every call. This makes sense because each call could be associated with different users; we don't want to share it among calls.

Also, notice how the second parameter is a Users object, which implements UserProvider interface. This means SessionAuthChannel uses Users object when it needs to fetch an Authenticatable object. It just happens that Users object fetches it from a database, but remember it doesn't need to!

Remember that when adding an auth channel all we are doing is registering a channel but not using it at this time. This means you can add another auth channel of your own and give it a name.

So how does Alpas know what auth channel to use?

Well, you can decide what auth channel to apply by default to all calls by setting AUTH_CHANNEL variable in your .env file. If you didn't set any, Alpas uses the name called session by default. This is the reason why when registering an auth channel in AuthConfig, we named it session because that's the default! We told you, it will click :)

HttpCall and Authentication

For most apps, you'll never have to deal with all the concepts we talked about up until this point. Most of the times, you are only concerned about whether the current user is authenticated or not. And, if authenticated, who is authenticated. HttpCall proxies all these. All you need is to know the following properties:

Custom Auth Channel

To create a custom auth channel, you just need to implement AuthChannel interface and override a couple of things. The most important one being the check() method.

Let's say, hypothetically, we want to write an auth channel that checks X-ADMIN-API-KEY header of the incoming request and, if it matches your API key, then you consider this session to be authenticated. The user is then authorized as an admin.

class AdminApiAuthChannel(private val call: HttpCall) : AuthChannel {
    override var user: Authenticatable? = null
    override fun check(): Boolean {
        val authHeader = call.header("X-ADMIN-API-KEY") ?: return false
        val isAuthenticated = 
        if(authHeader == "abracadabra"){
            // fetch the user somehow
            user = Users.findByRole("admin").firstOrNull()
        }
        return user != null
    }
}

class AuthConfig(env: Environment) : BaseConfig(env) {
    init {
        addChannel("session") { call -> AdminApiAuthChannel(call) }
    }
}

Now AdminApiAuthChannel will be used for authenticating all auth only routes.

Route Auth Channels

You may want to have multiple auth channels for your app depending on different routes.

For an example, while SessionAuthChannel may be appropriate for web routes, it may not be appropriate for API routes. API routes will probably use some other ways of validating a user — such as checking a personal token in the header rather than checking the cookies — and you might want a dedicated auth channel for this.

Alpas allows you to easily apply an auth channel for a specific route or a route group by passing an auth channel name to mustBeAuthenticated() method.

fun Router.addRoutes() {
    // authenticate the user using an auth channel named "api"
    group("/api/docs") {
        get(DocsController::class)
    }.mustBeAuthenticated("api")

    // authenticate the user using an auth channel named "session"
    group("/web/admin") {
        get(ProfileController::class)
    }.mustBeAuthenticated("session")
}

class AuthConfig(env: Environment) : BaseConfig(env) {
    init {
        addChannel("session") { call -> SessionAuthChannel(call, Users) }
        addChannel("api") { call -> ApiAuthChannel(call) }
    }
}

/tip/ alpas route:list command shows more information about all your routes in a nicely formatted table. It also shows auth channels applied to each authorized only routes.

Authentication Middleware

You need to assign AuthOnlyMiddleware to each of your routes that you want to be accessible only to authorized users. If you want some routes to be accessible only by guests and not by authorized users, then you need to apply GuestOnlyMiddleware instead.

AuthConfig's ifUnauthorizedRedirectToPath property decides where to redirect unauthorized users trying to access authorized only routes. This is set to /login by default.

Similarly, AuthConfig's ifAuthorizedRedirectToPath property decides where to redirect users who are already authorized but trying to access guests only routes. This is set to / by default.

You are more than welcome to change these properties to fit your needs.