basic.md

Required dependencies: io.ktor:%artifact_name%

Code examples: auth-basic, auth-basic-hash-table

The Basic authentication scheme is a part of HTTP framework used for access control and authentication. In this scheme, user credentials are transmitted as username/password pairs encoded using Base64.

Ktor allows you to use basic authentication for logging in users and protecting specific routes. You can get general information about authentication in Ktor in the section.

Given that basic authentication passes username and password as clear text, you need to use HTTPS/TLS to protect sensitive information.

Add dependencies {id="add_dependencies"}

To enable basic authentication, you need to include the %artifact_name% artifact in the build script:

Basic authentication flow {id="flow"}

The basic authentication flow looks as follows:

1. A client makes a request without the Authorization header to a specific route in a server application.

2. A server responds to a client with a 401 (Unauthorized) response status and uses a WWW-Authenticate response header to provide information that the basic authentication scheme is used to protect a route. A typical WWW-Authenticate header looks like this:

   WWW-Authenticate: Basic realm="Access to the '/' path", charset="UTF-8"
   

   {style="block"}

   In Ktor, you can specify the realm and charset using corresponding properties when configuring the basic authentication provider.

3. Usually a client displays a login dialog where a user can enter credentials. Then, a client makes a request with the Authorization header containing a username and password pair encoded using Base64, for example:

   Authorization: Basic amV0YnJhaW5zOmZvb2Jhcg
   

   {style="block"}

4. A server validates credentials sent by a client and responds with the requested content.

Install basic authentication {id="install"}

To install the basic authentication provider, call the basic function inside the install block:

install(Authentication) {
    basic {
        // Configure basic authentication
    }
}

You can optionally specify a provider name that can be used to authenticate a specified route.

Configure basic authentication {id="configure"}

To get a general idea on how to configure different authentication providers in Ktor, see . In this section, we'll see on configuration specifics of the basic authentication provider.

Step 1: Configure a basic provider {id="configure-provider"}

The basic authentication provider exposes its settings via the BasicAuthenticationProvider.Configuration class. In the example below, the following settings are specified:

• The realm property sets the realm to be passed in WWW-Authenticate header.
• The validate function validates a username and password.

{src="snippets/auth-basic/src/main/kotlin/com/example/Application.kt" lines="9-20"}

The validate function checks UserPasswordCredential and returns a UserIdPrincipal in a case of successful authentication or null if authentication fails.

You can also use UserHashedTableAuth to validate users stored in an in-memory table that keeps usernames and password hashes.

Step 2: Define authorization scope {id="authenticate-route"}

After configuring the basic 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.

{src="snippets/auth-basic/src/main/kotlin/com/example/Application.kt" lines="21-27"}

Validate with UserHashedTableAuth {id="validate-user-hash"}

Ktor allows you to use UserHashedTableAuth to validate users stored in an in-memory table that keeps usernames and password hashes. This allows you not to compromise user passwords if your data source is leaked.

To use UserHashedTableAuth for validating users, follow the steps below:

1. Create a digest function with the specified algorithm and salt provider using the getDigestFunction function:

   {src="snippets/auth-basic-hash-table/src/main/kotlin/com/example/Application.kt" lines="9"}

2. Initialize a new instance of UserHashedTableAuth and specify the following properties:

   • Provide a table of usernames and hashed passwords using the table property.
   • Assign a digest function to the digester property.

   {src="snippets/auth-basic-hash-table/src/main/kotlin/com/example/Application.kt" lines="10-16"}

3. Inside the validate function, call the UserHashedTableAuth.authenticate function to authenticate a user and return an instance of UserIdPrincipal if the credentials are valid:

   {src="snippets/auth-basic-hash-table/src/main/kotlin/com/example/Application.kt" lines="19-26"}