Bearer authentication

The Bearer authentication scheme is a part of the HTTP framework used for access control and authentication. This scheme involves security tokens called bearer tokens. The Bearer authentication scheme is used as part of OAuth or JWT, but you can also provide custom logic for authorizing bearer tokens.

You can get general information about authentication in Ktor in the Authentication and authorization section.

Add dependencies

To enable bearer authentication, you need to include the ktor-server-auth artifact in the build script:

implementation("io.ktor:ktor-server-auth:$ktor_version")

implementation "io.ktor:ktor-server-auth:$ktor_version"

        
                    <dependency>
                        <groupId>io.ktor</groupId>
                        <artifactId>ktor-server-auth-jvm</artifactId>
                        <version>${ktor_version}</version>
                    </dependency>
                    
        

Bearer authentication flow

In general, the Bearer authentication flow might look as follows:

After a user successfully authenticates and authorizes access, the server returns an access token to the client.
The client can make a request to a protected resource with a token passed in the Authorization header using the Bearer schema.
GET http://localhost:8080/ Authorization: Bearer abc123
A server receives a request and validates a token.
After validation, a server responds with the contents of a protected resource.

Install bearer authentication

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

import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
    bearer {
        // Configure bearer authentication
    }
}

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

Configure bearer authentication

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

Step 1: Configure a bearer provider

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

The realm property sets the realm to be passed in the WWW-Authenticate header.
The authenticate function checks the token sent by the client and returns a UserIdPrincipal in the case of successful authentication or null if authentication fails.

    install(Authentication) {
        bearer("auth-bearer") {
            realm = "Access to the '/' path"
            authenticate { tokenCredential ->
                if (tokenCredential.token == "abc123") {
                    UserIdPrincipal("jetbrains")
                } else {
                    null
                }
            }
        }
    }

Step 2: Protect specific resources

After configuring the bearer provider, you can protect specific resources in our application using 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.

    routing {
        authenticate("auth-bearer") {
            get("/") {
                call.respondText("Hello, ${call.principal<UserIdPrincipal>()?.name}!")
            }
        }
    }

Last modified: 02 April 2024