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) -> Principal?

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) : Credential

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?) : Credential

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.

OAuth2RequestParameters

object OAuth2RequestParameters

List of OAuth2 request parameters for both peers.

OAuth2ResponseParameters

object OAuth2ResponseParameters

List of OAuth2 server response parameters.

OAuthAccessTokenResponse

sealed class OAuthAccessTokenResponse : Principal

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) : Principal

A user's principal identified by name.

UserPasswordCredential

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

A user's credentials identified by name and password.

Functions

authenticate

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

fun Route.authenticate(vararg configurations: String? = arrayOf(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.

createObtainRequestTokenHeader

fun ~~createObtainRequestTokenHeader~~(callback: String, consumerKey: String, nonce: String, timestamp: LocalDateTime = LocalDateTime.now()): HttpAuthHeader.Parameterized

Creates an HTTP authentication header for OAuth1a obtain token request.

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.

expect suspend fun PipelineContext<Unit, ApplicationCall>.~~oauth~~(client: HttpClient, dispatcher: CoroutineDispatcher, providerLookup: ApplicationCall.() -> OAuthServerSettings?, urlProvider: ApplicationCall.(OAuthServerSettings) -> String)

Installs both OAuth1a and OAuth2 authentication helpers that redirects to an OAuth server authorization page and handles corresponding callbacks.

actual suspend fun PipelineContext<Unit, ApplicationCall>.~~oauth~~(client: HttpClient, dispatcher: CoroutineDispatcher, providerLookup: ApplicationCall.() -> OAuthServerSettings?, urlProvider: ApplicationCall.(OAuthServerSettings) -> String)

Installs both OAuth1a and OAuth2 authentication helpers that redirects to an OAuth server authorization page and handles corresponding callbacks.

oauthHandleCallback

expect suspend fun PipelineContext<Unit, ApplicationCall>.~~oauthHandleCallback~~(client: HttpClient, dispatcher: CoroutineDispatcher, provider: OAuthServerSettings, callbackUrl: String, loginPageUrl: String, block: suspend (OAuthAccessTokenResponse) -> Unit)

Handles an OAuth callback. Usually it leads to requesting an access token.

Handles an OAuth callback.

actual suspend fun PipelineContext<Unit, ApplicationCall>.~~oauthHandleCallback~~(client: HttpClient, dispatcher: CoroutineDispatcher, provider: OAuthServerSettings, callbackUrl: String, loginPageUrl: String, block: suspend (OAuthAccessTokenResponse) -> Unit)

Handles an OAuth callback. Usually it leads to requesting an access token.

Handles an OAuth callback.

Handles an OAuth callback. Usually it leads to requesting an access token.

Handles an OAuth callback.

oauthRespondRedirect

expect suspend fun PipelineContext<Unit, ApplicationCall>.~~oauthRespondRedirect~~(client: HttpClient, dispatcher: CoroutineDispatcher, provider: OAuthServerSettings, callbackUrl: String)

Responds with OAuth redirect.

actual suspend fun PipelineContext<Unit, ApplicationCall>.~~oauthRespondRedirect~~(client: HttpClient, dispatcher: CoroutineDispatcher, provider: OAuthServerSettings, callbackUrl: String)

Responds with OAuth redirect.

actual suspend fun PipelineContext<Unit, ApplicationCall>.~~oauthRespondRedirect~~(client: HttpClient, dispatcher: CoroutineDispatcher, provider: OAuthServerSettings, callbackUrl: String)

Responds with OAuth redirect.

parseAuthorizationHeader

fun ApplicationRequest.parseAuthorizationHeader(): HttpAuthHeader?

Parses an authorization header from a ApplicationRequest returning a HttpAuthHeader.

principal

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

Retrieves an authenticated Principal for this call.

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

Retrieves an authenticated Principal for this call from provider with name provider

session

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

inline fun <T : Any> AuthenticationConfig.session(name: String? = null, 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.

sign

fun HttpAuthHeader.Parameterized.~~sign~~(method: HttpMethod, baseUrl: String, key: String, parameters: List<Pair<String, String>>): HttpAuthHeader.Parameterized

Signs an HTTP auth header.

signatureBaseString

fun ~~signatureBaseString~~(header: HttpAuthHeader.Parameterized, method: HttpMethod, baseUrl: String, parameters: List<HeaderValueParam>): String

Builds an OAuth1a signature base string as per RFC.

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.

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.