Form-based authentication
Form-based authentication uses a web form to collect credential information and authenticate a user. To create a web form in Ktor, you can use HTML DSL or choose between JVM template engines, such as FreeMarker, Velocity, and so on.
Add dependencies
To enable form
authentication, you need to include the ktor-server-auth
artifact in the build script:
Form-based authentication flow
The form-based authentication flow might look as follows:
An unauthenticated client makes a request to a specific route in a server application.
A server returns an HTML page that consists at least from an HTML-based web form, which prompts a user for a username and password.
When a user submits a username and password, a client makes a request containing web form data (which includes the username and password) to a server.
POST http://localhost:8080/login Content-Type: application/x-www-form-urlencoded username=jetbrains&password=foobarIn Ktor, you need to specify parameter names used to fetch a username and password.
A server validates credentials sent by a client and responds with the requested content.
Install form authentication
To install the form
authentication provider, call the form function inside the install
block:
You can optionally specify a provider name that can be used to authenticate a specified route.
Configure form authentication
Step 1: Configure a form provider
The form
authentication provider exposes its settings via the FormAuthenticationProvider.Config class. In the example below, the following settings are specified:
The
userParamName
andpasswordParamName
properties specify parameter names used to fetch a username and password.The
validate
function validates a username and password. Thevalidate
function checksUserPasswordCredential
and returns aUserIdPrincipal
in the case of successful authentication ornull
if authentication fails.The
challenge
function specifies an action performed if authentication fails. For instance, you can redirect back to a login page or send UnauthorizedResponse.
Step 2: Protect specific resources
After configuring the form
provider, you need to define a post
route where the data gets sent. Then, add this route inside the authenticate function. In the case of successful authentication, you can retrieve an authenticated UserIdPrincipal inside a route handler using the call.principal
function and get a name of an authenticated user.
You can use Session authentication to store a logged-in user's ID. For example, when a user logs in using a web form for the first time, you can save a username to a cookie session and authorize this user on subsequent requests using the session
provider.