auth.md

Required dependencies: io.ktor:ktor-client-auth

The Auth plugin handles authentication and authorization in your client application.

Ktor provides the Auth plugin to handle authentication and authorization in your client application. Typical usage scenarios include logging in users and gaining access to specific resources.

Supported authentication types {id="supported"}

HTTP provides a general framework for access control and authentication. The Ktor client allows you to use the following HTTP authentication schemes:

• Basic - uses Base64 encoding 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. For example, you can use this scheme as a part of OAuth flow to authorize users of your application by using external providers, such as Google, Facebook, Twitter, and so on.

Add dependencies {id="add_dependencies"}

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

Install Auth {id="install_plugin"}

To install the Auth plugin, pass it to the install function inside a client configuration block:

val client = HttpClient(CIO) {
    install(Auth) {
        // Configure authentication
    }
}

Now you can configure the required authentication provider.

Configure authentication {id="configure_authentication"}

Step 1: Choose an authentication provider {id="choose-provider"}

To use a specific authentication provider (basic, digest, or bearer), you need to call the corresponding function inside the install block. For example, to use the basic authentication, call the basic function:

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

Inside the block, you can configure settings specific to this provider.

Step 2: (Optional) Configure the realm {id="realm"}

Optionally, you can configure the realm using the realm property:

install(Auth) {
    basic {
        realm = "Access to the '/' path"
        // ...
    }
}

You can create several providers with different realms to access different resources:

install(Auth) {
    basic {
        realm = "Access to the '/' path"
        // ...
    }
    basic {
        realm = "Access to the '/admin' path"
        // ...
    }
}

In this case, the client chooses the necessary provider based on the WWW-Authenticate response header, which contains the realm.

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

To learn how to configure settings for a specific provider, see a corresponding topic: