Form-based authentication
Form-based authentication uses a web form to collect credential information and authenticate a user.
Add dependencies
To enable form
authentication, you need to include the ktor-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/ 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/Configuration 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.
The validate
function checks UserPasswordCredential
and returns a UserIdPrincipal
in a case of successful authentication or null
if authentication fails.
Step 2: Define authorization scope
After configuring the form
provider, you can define the authorization for the different resources in our application using the authenticate
function. In a 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.