ktor-server-auth/io.ktor.server.auth

Package-level declarations

Types

typealias ApplicationCallPredicate = (ApplicationCall) -> Boolean

A predicate function that accepts an application call and returns true or false.

class Authentication(config: AuthenticationConfig)

A plugin that handles authentication and authorization. Typical usage scenarios include logging in users, granting access to specific resources, and securely transmitting information between parties.

AuthenticationChecked

object AuthenticationChecked : Hook<suspend (ApplicationCall) -> Unit>

A hook that is executed after authentication was checked. Note that this hook is also executed for optional authentication or for routes without any authentication, resulting in ApplicationCall.principal being null.

AuthenticationConfig

class AuthenticationConfig(providers: Map<String?, AuthenticationProvider> = emptyMap())

A configuration for the Authentication plugin.

AuthenticationContext

class AuthenticationContext(call: ApplicationCall)

An authentication context for a call.

AuthenticationFailedCause

sealed class AuthenticationFailedCause

Represents a cause for an authentication challenge request.

AuthenticationFunction

typealias AuthenticationFunction<C> = suspend ApplicationCall.(credentials: C) -> Any?

An authentication function that accepts and verifies credentials and returns a principal when verification is successful.

AuthenticationProcedureChallenge

class AuthenticationProcedureChallenge

Represents an authentication challenging procedure requested by authentication mechanism.

AuthenticationProvider

abstract class AuthenticationProvider(config: AuthenticationProvider.Config)

An authentication provider with the specified name.

AuthenticationRouteSelector

class AuthenticationRouteSelector(val names: List<String?>) : RouteSelector

An authentication route node that is used by Authentication plugin and usually created by the Route.authenticate DSL function, so generally there is no need to instantiate it directly unless you are writing an extension.

AuthenticationStrategy

enum AuthenticationStrategy : Enum<AuthenticationStrategy>

A resolution strategy for nested authentication providers. AuthenticationStrategy.Optional - if no authentication is provided by the client, a call continues but with a null Principal. AuthenticationStrategy.FirstSuccessful - client must provide authentication data for at least one provider registered for this route AuthenticationStrategy.Required - client must provide authentication data for all providers registered for this route with this strategy

BasicAuthenticationProvider

class BasicAuthenticationProvider : AuthenticationProvider

A basic Authentication provider.

BearerAuthenticationProvider

class BearerAuthenticationProvider : AuthenticationProvider

A Bearer Authentication provider.

BearerTokenCredential

data class BearerTokenCredential(val token: String)

ChallengeFunction

typealias ChallengeFunction = suspend (AuthenticationProcedureChallenge, ApplicationCall) -> Unit

Credential

interface ~~Credential~~

A marker interface indicating that a class represents credentials for authentication.

DigestAuthenticationProvider

class DigestAuthenticationProvider : AuthenticationProvider

A digest Authentication provider.

DigestCredential

data class DigestCredential(val realm: String, val userName: String, val digestUri: String, val nonce: String, val opaque: String?, val nonceCount: String?, val algorithm: String?, val response: String, val cnonce: String?, val qop: String?)

Digest credentials.

DigestProviderFunction

typealias DigestProviderFunction = suspend (userName: String, realm: String) -> ByteArray?

Provides a message digest for the specified username and realm or returns null if a user is missing. This function could fetch digest from a database or compute it instead.

DynamicProviderConfig

class DynamicProviderConfig(val name: String?) : AuthenticationProvider.Config

A configuration that creates a provider based on the AuthenticationConfig.provider block.

ForbiddenResponse

class ForbiddenResponse(val challenges: HttpAuthHeader) : OutgoingContent.NoContent

Response content with the 403 Forbidden status code and the WWW-Authenticate header of supplied challenges

FormAuthChallengeContext

class FormAuthChallengeContext(val call: ApplicationCall)

A context for FormAuthChallengeFunction.

FormAuthChallengeFunction

typealias FormAuthChallengeFunction = suspend FormAuthChallengeContext.(UserPasswordCredential?) -> Unit

Specifies what to send back if form-based authentication fails.

FormAuthenticationProvider

class FormAuthenticationProvider : AuthenticationProvider

A form-based authentication provider.

OAuth1aException

sealed class OAuth1aException : Exception

An OAuth1a server error.

OAuth2Exception

sealed class OAuth2Exception : Exception

Represents an error during communicating to OAuth2 server.

OAuth2RedirectError

class OAuth2RedirectError(val error: String, val errorDescription: String?) : AuthenticationFailedCause.Error

Error container for when the upstream identity provider does not respond with the token credentials, and instead responds with error query parameters.

OAuth2RequestParameters

object OAuth2RequestParameters

List of OAuth2 request parameters for both peers.

OAuth2ResponseParameters

object OAuth2ResponseParameters

List of OAuth2 server response parameters.

OAuthAccessTokenResponse

sealed class OAuthAccessTokenResponse

An OAuth access token acquired from the server.

OAuthAuthenticationProvider

class OAuthAuthenticationProvider : AuthenticationProvider

An OAuth Authentication provider.

OAuthCallback

sealed class OAuthCallback

OAuth callback parameters.

OAuthGrantTypes

object OAuthGrantTypes

OAuth grant types constants.

OAuthServerSettings

sealed class OAuthServerSettings

OAuth server settings.

OAuthVersion

enum OAuthVersion : Enum<OAuthVersion>

OAuth versions used in configuration.

Principal

interface ~~Principal~~

A marker interface indicating that a class represents an authenticated principal.

RouteAuthenticationConfig

class RouteAuthenticationConfig

A configuration for the AuthenticationInterceptors plugin.

SessionAuthChallengeFunction

typealias SessionAuthChallengeFunction<T> = suspend SessionChallengeContext.(T?) -> Unit

Specifies what to send back if session authentication fails.

SessionAuthenticationProvider

class SessionAuthenticationProvider<T : Any> : AuthenticationProvider

A session-based Authentication provider.

SessionChallengeContext

class SessionChallengeContext(val call: ApplicationCall)

A context for SessionAuthChallengeFunction.

UnauthorizedResponse

class UnauthorizedResponse(val challenges: HttpAuthHeader) : OutgoingContent.NoContent

Response content with the 401 Unauthorized status code and the WWW-Authenticate header of supplied challenges.

UserHashedTableAuth

class UserHashedTableAuth(val digester: (String) -> ByteArray, val table: Map<String, ByteArray>)

An in-memory table that keeps usernames and password hashes. This allows you not to compromise user passwords if your data source is leaked.

UserIdPrincipal

data class UserIdPrincipal(val name: String)

A user's principal identified by name.

UserPasswordCredential

data class UserPasswordCredential(val name: String, val password: String)

A user's credentials identified by name and password.

Properties

authentication

val ApplicationCall.authentication: AuthenticationContext

Retrieves an AuthenticationContext for this call.

AuthenticationInterceptors

val AuthenticationInterceptors: RouteScopedPlugin<RouteAuthenticationConfig>

A plugin that authenticates calls. Usually used via the authenticate function inside routing.

OAuthKey

val OAuthKey: Any

An OAuth provider key.

SessionAuthChallengeKey

const val SessionAuthChallengeKey: String

A key used to register authentication challenge.

Functions

authenticate

fun Route.authenticate(vararg configurations: String? = arrayOf<String?>(null), strategy: AuthenticationStrategy, build: Route.() -> Unit): Route

fun Route.authenticate(vararg configurations: String? = arrayOf<String?>(null), optional: Boolean = false, build: Route.() -> Unit): Route

Creates a route that allows you to define authorization scope for application resources. This function accepts names of authentication providers defined in the Authentication plugin configuration.

authentication

fun Application.authentication(block: AuthenticationConfig.() -> Unit)

Installs the Authentication plugin if not yet installed and invokes block on its config. You can modify the existing authentication configuration only in the authentication's block or using the Authentication.configure function. Changing captured instance of configuration outside of block may have no effect or damage application's state.

basic

fun AuthenticationConfig.basic(name: String? = null, configure: BasicAuthenticationProvider.Config.() -> Unit)

Installs the basic Authentication provider. You can use basic authentication for logging in users and protecting specific routes. To learn how to configure it, see Basic authentication.

basicAuthenticationCredentials

fun ApplicationRequest.basicAuthenticationCredentials(charset: Charset? = null): UserPasswordCredential?

Retrieves basic authentication credentials for this ApplicationRequest.

bearer

fun AuthenticationConfig.bearer(name: String? = null, configure: BearerAuthenticationProvider.Config.() -> Unit)

Installs the Bearer Authentication provider. Bearer auth requires the developer to provide a custom 'authenticate' function to authorize the token, and return the associated principal.

digest

fun AuthenticationConfig.digest(name: String? = null, configure: DigestAuthenticationProvider.Config.() -> Unit)

Installs the digest Authentication provider. To learn how to configure it, see Digest authentication.

digestAuthenticationCredentials

fun ApplicationCall.digestAuthenticationCredentials(): DigestCredential?

Retrieves DigestCredential for this call.

expectedDigest

fun DigestCredential.expectedDigest(method: HttpMethod, digester: MessageDigest, userNameRealmPasswordDigest: ByteArray): ByteArray

Calculates the expected digest bytes for this DigestCredential.

form

fun AuthenticationConfig.form(name: String? = null, configure: FormAuthenticationProvider.Config.() -> Unit)

Installs the form-based Authentication provider. Form-based authentication uses a web form to collect credential information and authenticate a user. To learn how to configure it, see Form-based authentication.

oauth

fun AuthenticationConfig.oauth(name: String? = null, configure: OAuthAuthenticationProvider.Config.() -> Unit)

Installs the OAuth Authentication provider. OAuth can be used to authorize users of your application by using external providers, such as Google, Facebook, Twitter, and so on. To learn how to configure it, see OAuth.

parseAuthorizationHeader

fun ApplicationRequest.parseAuthorizationHeader(): HttpAuthHeader?

Parses an authorization header from a ApplicationRequest returning a HttpAuthHeader.

principal

inline fun <P : Any> ApplicationCall.principal(): P?

Retrieves an authenticated principal Any for this call.

inline fun <P : Any> ApplicationCall.principal(provider: String?): P?

Retrieves an authenticated principal Any for this call from provider with name provider

session

inline fun <T : Any> AuthenticationConfig.session(name: String? = null)

inline fun <T : Any> AuthenticationConfig.session(name: String? = null, noinline configure: SessionAuthenticationProvider.Config<T>.() -> Unit)

fun <T : Any> AuthenticationConfig.session(name: String? = null, kClass: KClass<T>)

fun <T : Any> AuthenticationConfig.session(name: String?, kClass: KClass<T>, configure: SessionAuthenticationProvider.Config<T>.() -> Unit)

Installs the session Authentication provider. This provider provides the ability to authenticate a user that already has an associated session.

toDigestCredential

fun HttpAuthHeader.Parameterized.toDigestCredential(): DigestCredential

Converts HttpAuthHeader to DigestCredential.

verifier

suspend fun DigestCredential.verifier(method: HttpMethod, digester: MessageDigest, userNameRealmPasswordDigest: suspend (String, String) -> ByteArray?): Boolean

Verifies that credentials are valid for a given method, digester, and userNameRealmPasswordDigest.

verifyWithOAuth2

suspend fun verifyWithOAuth2(credential: UserPasswordCredential, client: HttpClient, settings: OAuthServerSettings.OAuth2ServerSettings): OAuthAccessTokenResponse.OAuth2

Implements Resource Owner Password Credentials Grant.