Authentication and authorization
Ktor provides the Authentication plugin to handle authentication and authorization. Typical usage scenarios include logging in users, granting access to specific resources, and securely transmitting information between parties. You can also use
Authentication with Sessions to keep a user's information between requests.
Supported authentication types
Ktor supports the following authentications and authorization schemes:
HTTP provides a general framework for access control and authentication. In Ktor, you can use the following HTTP authentication schemes:
Basic - uses
Base64encoding to provide a username and password. Generally is not recommended if not used in combination with HTTPS.
Digest - an authentication method that communicates user credentials in an encrypted form by applying a hash function to the username and password.
Bearer- an authentication scheme that involves security tokens called bearer tokens. You can use JSON Web Tokens as bearer tokens and use the
jwtauthentication in Ktor to validate and authorize a request.
JSON Web Tokens (JWT)
JSON Web Token is an open standard for securely transmitting information between parties as a JSON object. You can use JSON Web Tokens for authorization: when the user is logged in, each request will include a token, allowing the user to access resources that are permitted with that token. In Ktor, you can verify a token and validate the claims contained within it using the
OAuth is an open standard for securing access to APIs. The
oauth provider in Ktor allows you to implement authentication using external providers such as Google, Facebook, Twitter, and so on.
Sessions provide a mechanism to persist data between different HTTP requests. Typical use cases include storing a logged-in user's ID, the contents of a shopping basket, or keeping user preferences on the client. In Ktor, a user that already has an associated session can be authenticated using the
session provider. Learn how to do this from Session authentication.
Authentication, you need to include the
ktor-server-auth artifact in the build script:
To install the
Authentication plugin, pass it to the
install function in the application initialization code. Depending on the way used to create a server, this can be the
embeddedServer function call ...
... or a specified module.
After installing Authentication, you can configure and use
Authentication as follows:
Step 1: Choose an authentication provider
To use a specific authentication provider (basic, digest, form, and so on), you need to call the corresponding function inside the
install block. For example, to use the
basic authentication, call the basic function:
Inside this function, you can configure settings specific to this provider.
Step 2: Specify a provider name
A function for using a specific provider optionally allows you to specify a provider name. A code sample below installs the basic and form providers with the auth-basic and auth-form names, respectively:
These names can be used later to authenticate different routes using different providers.
Step 3: Configure a provider
Each provider type has its own configuration. For instance, the BasicAuthenticationProvider.Config class contains options passed to the basic function. The most important function exposed by this class is validate that validates a username and password. A code sample below shows how it can look:
To understand how the
validate function works, we need to introduce two terms:
A principal is an entity that can be authenticated: a user, a computer, a service, etc. In Ktor, various authentication providers might use different principals. For example, the
formproviders authenticate UserIdPrincipal while the
jwtprovider verifies JWTPrincipal.
A credential is a set of properties for a server to authenticate a principal: a user/password pair, an API key, and so on. For instance, the
formproviders use UserPasswordCredential to validate a username and password while
Step 4: Define authorization scope
The final step is to define the authorization for the different resources in our application. You can do this by using the authenticate function. This function can accept a name of a provider used to authenticate nested routes. The code snippet below uses a provider with the auth-basic name to protect the
Note that you can omit a provider name to use an unnamed provider.
Step 5: Get a principal inside a route handler
In a case of successful authentication, you can retrieve an authenticated Principal inside a route handler using the
call.principal function. This function accepts a specific principal type returned by the configured authentication provider. In a code sample below,
call.principal is used to obtain
UserIdPrincipal and get a name of an authenticated user.
If you use session authentication, a principal might be a data class that stores session data. So, you need to pass this data class to