Package io.ktor.auth

Types

Link copied to clipboard
typealias ApplicationCallPredicate = (ApplicationCall) -> Boolean

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

Link copied to clipboard
class Authentication(config: Authentication.Configuration)

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

Link copied to clipboard
class AuthenticationContext(call: ApplicationCall)

Represents an authentication context for the call

Link copied to clipboard
sealed class AuthenticationFailedCause

Represents a cause for authentication challenge request

Link copied to clipboard
typealias AuthenticationFunction<C> = suspend ApplicationCall.(C) -> Principal?

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

Link copied to clipboard
class AuthenticationPipeline(developmentMode: Boolean) : Pipeline<AuthenticationContext, ApplicationCall>

Represents authentication Pipeline for checking and requesting authentication

Link copied to clipboard
class AuthenticationProcedureChallenge

Represents authentication challenging procedure requested by authentication mechanism

Link copied to clipboard
open class AuthenticationProvider(config: AuthenticationProvider.Configuration)

Represents an authentication provider with the given name

Link copied to clipboard
class AuthenticationRouteSelector(names: List<String?>) : 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

Link copied to clipboard
class BasicAuthenticationProvider : AuthenticationProvider

Represents a Basic authentication provider

Link copied to clipboard
interface Credential

Marker interface indicating that a class represents credentials for authentication

Link copied to clipboard
object DefaultOAuth2StateProvider : OAuth2StateProvider

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

Link copied to clipboard
class DigestAuthenticationProvider : AuthenticationProvider

Represents a Digest authentication provider

Link copied to clipboard
data class DigestCredential(realm: String, userName: String, digestUri: String, nonce: String, opaque: String?, nonceCount: String?, algorithm: String?, response: String, cnonce: String?, qop: String?) : Credential

Represents Digest credentials

Link copied to clipboard
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.

Link copied to clipboard
class ForbiddenResponse(challenges: HttpAuthHeader) : OutgoingContent.NoContent

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

Link copied to clipboard
sealed class FormAuthChallenge

Specifies what to send back if form authentication fails.

Link copied to clipboard
typealias FormAuthChallengeFunction = suspend PipelineContext<*, ApplicationCall>.(UserPasswordCredential?) -> Unit

Specifies what to send back if form authentication fails.

Link copied to clipboard
class FormAuthenticationProvider : AuthenticationProvider

Represents a form-based authentication provider

Link copied to clipboard
sealed class OAuth1aException : Exception

Represents an OAuth1a server error

Link copied to clipboard
sealed class OAuth2Exception : Exception

Represents a error during communicating to OAuth2 server

Link copied to clipboard
object OAuth2RequestParameters

List of OAuth2 request parameters for both peers

Link copied to clipboard
object OAuth2ResponseParameters

List of OAuth2 server response parameters

Link copied to clipboard
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

Link copied to clipboard
sealed class OAuthAccessTokenResponse : Principal

OAuth access token acquired from the server

Link copied to clipboard
class OAuthAuthenticationProvider : AuthenticationProvider

Represents an OAuth provider for Authentication feature

Link copied to clipboard
sealed class OAuthCallback

OAauth callback parameters

Link copied to clipboard
object OAuthGrantTypes

OAuth grant types constants

Link copied to clipboard
sealed class OAuthServerSettings

Represents OAuth server settings

Link copied to clipboard
enum OAuthVersion : Enum<OAuthVersion>

OAuth versions used in configuration

Link copied to clipboard
interface Principal

Marker interface indicating that a class represents an authenticated principal

Link copied to clipboard
sealed class SessionAuthChallenge<in T : Any>

Specifies what to send back if authentication fails.

Link copied to clipboard
typealias SessionAuthChallengeFunction<T> = suspend PipelineContext<*, ApplicationCall>.(T?) -> Unit

Specifies what to send back if session authentication fails.

Link copied to clipboard
class SessionAuthenticationProvider<T : Any> : AuthenticationProvider

Represents a session-based authentication provider

Link copied to clipboard
class UnauthorizedResponse(challenges: HttpAuthHeader) : OutgoingContent.NoContent

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

Link copied to clipboard
class UserHashedTableAuth(digester: (String) -> ByteArray, table: Map<String, ByteArray>)

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

Link copied to clipboard
data class UserIdPrincipal(name: String) : Principal

Represents a simple user's principal identified by name

Link copied to clipboard
data class UserPasswordCredential(name: String, password: String) : Credential

Represents a simple user name and password credential pair

Functions

Link copied to clipboard
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

Link copied to clipboard
fun Application.authentication(block: Authentication.Configuration.() -> 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.

Link copied to clipboard
fun Authentication.Configuration.basic(name: String? = null, configure: BasicAuthenticationProvider.Configuration.() -> Unit)

Installs Basic Authentication mechanism

Link copied to clipboard
fun ApplicationRequest.basicAuthenticationCredentials(charset: Charset? = null): UserPasswordCredential?

Retrieves Basic authentication credentials for this ApplicationRequest

Link copied to clipboard
fun createObtainRequestTokenHeader(callback: String, consumerKey: String, nonce: String, timestamp: LocalDateTime = LocalDateTime.now()): HttpAuthHeader.Parameterized

Create an HTTP auth header for OAuth1a obtain token request

Link copied to clipboard
fun createUpgradeRequestTokenHeader(consumerKey: String, token: String, nonce: String, timestamp: LocalDateTime = LocalDateTime.now()): HttpAuthHeader.Parameterized

Create an HTTP auth header for OAuth1a upgrade token request

Link copied to clipboard
fun Authentication.Configuration.digest(name: String? = null, configure: DigestAuthenticationProvider.Configuration.() -> Unit)

Installs Digest Authentication mechanism

Link copied to clipboard

Retrieves DigestCredential from this call

Link copied to clipboard
fun DigestCredential.expectedDigest(method: HttpMethod, digester: MessageDigest, userNameRealmPasswordDigest: ByteArray): ByteArray

Calculates expected digest bytes for this DigestCredential

Link copied to clipboard
fun Authentication.Configuration.form(name: String? = null, configure: FormAuthenticationProvider.Configuration.() -> Unit)

Installs Form Authentication mechanism

Link copied to clipboard
fun Authentication.Configuration.oauth(name: String? = null, configure: OAuthAuthenticationProvider.Configuration.() -> Unit)

Installs OAuth Authentication mechanism

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

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

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

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

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

Handle OAuth callback.

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

Respond OAuth redirect

Link copied to clipboard

Parses an authorization header from a ApplicationRequest returning a HttpAuthHeader.

Link copied to clipboard
inline fun <P : Principal> ApplicationCall.principal(): P?

Retrieves authenticated Principal for this call

Link copied to clipboard
inline fun <T : Principal> Authentication.Configuration.session(name: String? = null)
inline fun <T : Principal> Authentication.Configuration.session(name: String? = null, challenge: SessionAuthChallenge<T>)

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

inline fun <T : Any> Authentication.Configuration.session(name: String? = null, configure: SessionAuthenticationProvider.Configuration<T>.() -> 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

Link copied to clipboard
fun HttpAuthHeader.Parameterized.sign(method: HttpMethod, baseUrl: String, key: String, parameters: List<Pair<String, String>>): HttpAuthHeader.Parameterized

Sign an HTTP auth header

Link copied to clipboard
fun signatureBaseString(header: HttpAuthHeader.Parameterized, method: HttpMethod, baseUrl: String, parameters: List<HeaderValueParam>): String

Build an OAuth1a signature base string as per RFC

Link copied to clipboard
Link copied to clipboard
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

Link copied to clipboard

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

Properties

Link copied to clipboard
val ApplicationCall.authentication: AuthenticationContext

Retrieves an AuthenticationContext for this call

Link copied to clipboard
val OAuthKey: Any

OAuth provider key

Link copied to clipboard
const val SessionAuthChallengeKey: String

A key used to register auth challenge