Package io.ktor.auth

Types

Authentication

class Authentication

Authentication feature supports pluggable mechanisms for checking and challenging a client to provide credentials

AuthenticationContext

class AuthenticationContext

Represents an authentication context for the call

AuthenticationFailedCause

sealed class AuthenticationFailedCause

Represents a cause for authentication challenge request

AuthenticationPipeline

class AuthenticationPipeline : 
    Pipeline<AuthenticationContext, ApplicationCall>

Represents authentication Pipeline for checking and requesting authentication

AuthenticationProcedureChallenge

class AuthenticationProcedureChallenge

Represents authentication challenging procedure requested by authentication mechanism

AuthenticationProvider

open class AuthenticationProvider

Represents an authentication provider with the given name

AuthenticationRouteSelector

class AuthenticationRouteSelector : RouteSelector

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

BasicAuthenticationProvider

class BasicAuthenticationProvider : AuthenticationProvider

Represents a Basic authentication provider

Credential

interface Credential

Marker interface indicating that a class represents credentials for authentication

DefaultOAuth2StateProvider

object DefaultOAuth2StateProvider : OAuth2StateProvider

The default state provider that does generate random nonce and don’t keep them

DigestAuthenticationProvider

class DigestAuthenticationProvider : AuthenticationProvider

Represents a Digest authentication provider

DigestCredential

data class DigestCredential : Credential

Represents Digest credentials

FormAuthChallenge

sealed class FormAuthChallenge

Specifies what to send back if form authentication fails.

FormAuthenticationProvider

class FormAuthenticationProvider : AuthenticationProvider

Represents a form-based authentication provider

OAuth2RequestParameters

object OAuth2RequestParameters

List of OAuth2 request parameters for both peers

OAuth2ResponseParameters

object OAuth2ResponseParameters

List of OAuth2 server response parameters

OAuth2StateProvider

interface OAuth2StateProvider

Provides states for OAuth2. State could be just a random number (nonce) or could contain additional form fields or a signature. It is important that it should be a way to verify state. So all states need to be saved somehow or a state need to be a signed set of parameters that could be verified later

OAuthAccessTokenResponse

sealed class OAuthAccessTokenResponse : Principal

OAuth access token acquired from the server

OAuthAuthenticationProvider

class OAuthAuthenticationProvider : AuthenticationProvider

Represents an OAuth provider for Authentication feature

OAuthCallback

sealed class OAuthCallback

OAauth callback parameters

OAuthGrantTypes

object OAuthGrantTypes

OAuth grant types constants

OAuthServerSettings

sealed class OAuthServerSettings

Represents OAuth server settings

OAuthVersion

enum class OAuthVersion

OAuth versions used in configuration

Principal

interface Principal

Marker interface indicating that a class represents an authenticated principal

SessionAuthChallenge

sealed class SessionAuthChallenge<in T : Any>

Specifies what to send back if form authentication fails.

SessionAuthenticationProvider

class SessionAuthenticationProvider<T : Any> : 
    AuthenticationProvider

Represents a session-based authentication provider

UnauthorizedResponse

class UnauthorizedResponse : NoContent

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

UserHashedTableAuth

class UserHashedTableAuth

Simple in-memory table that keeps user names and password hashes

UserIdPrincipal

data class UserIdPrincipal : Principal

Represents a simple user’s principal identified by name

UserPasswordCredential

data class UserPasswordCredential : Credential

Represents a simple user name and password credential pair

Exceptions

OAuth1aException

sealed class OAuth1aException : Exception

Represents an OAuth1a server error

OAuth2Exception

sealed class OAuth2Exception : Exception

Represents a error during communicating to OAuth2 server

Type Aliases

ApplicationCallPredicate

typealias ApplicationCallPredicate = (ApplicationCall) -> Boolean

Predicate function that accepts an application call and returns true or false

AuthenticationFunction

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

Authentication function that accepts and verifies credentials and returns a principal when verification successful.

DigestProviderFunction

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

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

Properties

OAuthKey

val OAuthKey: Any

OAuth provider key

SessionAuthChallengeKey

const val SessionAuthChallengeKey: String

A key used to register auth challenge

authentication

Retrieves an AuthenticationContext for this call

Functions

authenticate

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

Creates an authentication route that does handle authentication by the specified providers referred by configurations names. null could be used to point to the default provider and could be also mixed with other provider names. Other routes, handlers and interceptors could be nested into this node

authentication

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

Installs Authentication feature if not yet installed and invokes block on it’s config. One is allowed to modify existing authentication configuration only in authentication’s block or via Authentication.configure function. Changing captured instance of configuration outside of block may have no effect or damage application’s state.

basic

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

Installs Basic Authentication mechanism

basicAuthenticationCredentials

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

Retrieves Basic authentication credentials for this ApplicationRequest

createObtainRequestTokenHeader

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

Create an HTTP auth header for OAuth1a obtain token request

createUpgradeRequestTokenHeader

fun createUpgradeRequestTokenHeader(
    consumerKey: String,
    token: String,
    nonce: String,
    timestamp: LocalDateTime = LocalDateTime.now()
): Parameterized

Create an HTTP auth header for OAuth1a upgrade token request

digest

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

Installs Digest Authentication mechanism

digestAuthenticationCredentials

fun ApplicationCall.digestAuthenticationCredentials(): DigestCredential?

Retrieves DigestCredential from this call

expectedDigest

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

Calculates expected digest bytes for this DigestCredential

form

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

Installs Form Authentication mechanism

oauth

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

Install both OAuth1a and OAuth2 authentication helpers that do redirect to OAuth server authorization page and handle corresponding callbacks

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

Installs OAuth Authentication mechanism

oauthHandleCallback

suspend fun PipelineContext<Unit, ApplicationCall>.oauthHandleCallback(
    client: HttpClient,
    dispatcher: CoroutineDispatcher,
    provider: OAuthServerSettings,
    callbackUrl: String,
    loginPageUrl: String,
    configure: HttpRequestBuilder.() -> Unit = {},
    block: suspend (OAuthAccessTokenResponse) -> Unit
): Unit

Handle OAuth callback

oauthRespondRedirect

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

Respond OAuth redirect

obtainRequestTokenHeader

fun obtainRequestTokenHeader(
    callback: String,
    consumerKey: String,
    nonce: String,
    timestamp: LocalDateTime = LocalDateTime.now()
): Parameterized

parseAuthorizationHeader

fun ApplicationRequest.parseAuthorizationHeader(): HttpAuthHeader?

Parses an authorization header from a ApplicationRequest returning a HttpAuthHeader.

principal

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

Retrieves authenticated Principal for this call

session

fun <T : Principal> Configuration.session(
    name: String? = null,
    challenge: SessionAuthChallenge<T> = SessionAuthChallenge.Default
): Unit

Provides ability to authenticate users via sessions. It only works if T session type denotes Principal as well otherwise use full session with lambda function with SessionAuthenticationProvider.Configuration.validate configuration

fun <T : Any> Configuration.session(
    name: String? = null,
    configure: Configuration<T>.() -> Unit
): Unit

Provides ability to authenticate users via sessions. It is important to have specified SessionAuthenticationProvider.Configuration.validate and SessionAuthenticationProvider.Configuration.challenge in the lambda to get it work property

sign

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

Sign an HTTP auth header

signatureBaseString

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

Build an OAuth1a signature base string as per RFC

toDigestCredential

fun Parameterized.toDigestCredential(): DigestCredential

Converts HttpAuthHeader to DigestCredential

upgradeRequestTokenHeader

fun upgradeRequestTokenHeader(
    consumerKey: String,
    token: String,
    nonce: String,
    timestamp: LocalDateTime = LocalDateTime.now()
): Parameterized

Create an HTTP auth header for OAuth1a upgrade token request

verifier

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

Verifies credentials are valid for given method and digester and userNameRealmPasswordDigest

verifyWithOAuth2

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

Implements Resource Owner Password Credentials Grant see http://tools.ietf.org/html/rfc6749#section-4.3