0Pricing
Kotlin Academy · Aula

Plugins de autenticação: JWT e sessão

Proteja rotas Ktor usando tokens portadores JWT e autenticação baseada em sessão.

Plugins de autenticação: JWT e sessão é uma aula grátis de Kotlin Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Kotlin Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Kotlin Academy inclui 4 aulas no total.

Visão geral da autenticação do Ktor

O plugin Authentication do Ktor fornece uma API unificada para proteger rotas. Configure um ou mais provedores (JWT, Session, Basic, OAuth etc.) e envolva as rotas em um bloco authenticate("providerName") { }.

Adicionando dependências de autenticação

Adicione as bibliotecas de autenticação e JWT à sua compilação:

dependencies {
    implementation("io.ktor:ktor-server-auth:2.3.12")
    implementation("io.ktor:ktor-server-auth-jwt:2.3.12")
    implementation("io.ktor:ktor-server-sessions:2.3.12")
}

Configurando a autenticação JWT

Instale o plugin Authentication e configure um provedor JWT. O verifier valida a assinatura do token; validate extrai o principal do conteúdo:

install(Authentication) {
    jwt("auth-jwt") {
        realm = "ktor app"
        verifier(
            JWT.require(Algorithm.HMAC256(secret))
                .withAudience(audience)
                .withIssuer(issuer)
                .build()
        )
        validate { credential ->
            if (credential.payload.getClaim("username").asString() != null)
                JWTPrincipal(credential.payload)
            else null
        }
    }
}

Protegendo rotas com JWT

Envolva qualquer grupo de rotas em authenticate("auth-jwt") { }. Solicitações não autenticadas recebem automaticamente uma resposta 401:

routing {
    authenticate("auth-jwt") {
        get("/protected") {
            val principal = call.principal<JWTPrincipal>()!!
            val username = principal.payload.getClaim("username").asString()
            call.respondText("Hello, $username")
        }
    }
}

Emitindo um token JWT

Gere e assine um JWT no endpoint de login usando a biblioteca java-jwt:

post("/login") {
    val user = call.receive<LoginRequest>()
    // validate credentials ...
    val token = JWT.create()
        .withAudience(audience)
        .withIssuer(issuer)
        .withClaim("username", user.username)
        .withExpiresAt(Date(System.currentTimeMillis() + 3_600_000))
        .sign(Algorithm.HMAC256(secret))
    call.respond(mapOf("token" to token))
}

Autenticação por sessão

As sessões armazenam o estado do usuário no servidor (ou no cliente, como cookies assinados). Instale o plugin Sessions e defina uma classe de dados da sessão:

data class UserSession(val userId: Long, val username: String)

install(Sessions) {
    cookie<UserSession>("user_session") {
        cookie.path = "/"
        cookie.httpOnly = true
    }
}

Configurando o provedor de autenticação por sessão

Crie um provedor de autenticação por sessão que leia a sessão e retorne um principal:

install(Authentication) {
    session<UserSession>("auth-session") {
        validate { session -> session }
        challenge { call.respond(HttpStatusCode.Unauthorized) }
    }
}

Definindo e limpando sessões

Defina uma sessão após o login com call.sessions.set() e limpe-a ao sair com call.sessions.clear():

post("/login") {
    val creds = call.receive<LoginRequest>()
    // validate ...
    call.sessions.set(UserSession(userId = 1L, username = creds.username))
    call.respond(HttpStatusCode.OK)
}

post("/logout") {
    call.sessions.clear<UserSession>()
    call.respond(HttpStatusCode.OK)
}

JWT ou sessão: quando usar cada um

JWT: sem estado, adequado para APIs consumidas por clientes móveis ou SPA. O token contém todas as declarações; o servidor não precisa de um armazenamento de sessões. Sessions: com estado, adequado para aplicações web renderizadas no servidor. O ID da sessão fica no cookie; o servidor armazena os dados (na memória, no Redis ou no banco de dados).

Combinando vários provedores de autenticação

Você pode definir vários provedores e exigir qualquer um deles usando authenticate("jwt", "session") { }. O Ktor tenta cada provedor na ordem e aceita a solicitação se qualquer um deles validar com sucesso.

Respostas de desafio personalizadas

Cada provedor tem um bloco challenge que define o que fazer quando a autenticação falha. Retorne um 401 com um corpo de erro em JSON em vez do cabeçalho WWW-Authenticate padrão:

jwt("auth-jwt") {
    // ...
    challenge { _, _ ->
        call.respond(HttpStatusCode.Unauthorized, mapOf("error" to "Token expired or invalid"))
    }
}

Verificação rápida

O que o bloco validate em um provedor JWT do Ktor faz?

Recapitulação: plugins de autenticação — JWT e sessão

Principais pontos:

  • Instale Authentication e configure provedores (jwt, session, basic, oauth)
  • Proteja as rotas com authenticate("providerName") { }
  • JWT: tokens sem estado; assine-os no login, verifique-os com verifier e leia as declarações em validate
  • Sessões: com estado; use call.sessions.set() no login e clear() ao sair
  • Use challenge para personalizar o formato da resposta 401

Perguntas Frequentes

A aula “Plugins de autenticação: JWT e sessão” é grátis?

Sim — o texto completo de “Plugins de autenticação: JWT e sessão” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Kotlin Academy, atualize para CoddyKit PRO. O curso de Kotlin Academy inclui 4 aulas no total.

O que vou aprender em “Plugins de autenticação: JWT e sessão”?

Proteja rotas Ktor usando tokens portadores JWT e autenticação baseada em sessão. Você pratica Kotlin Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Kotlin Academy?

Nenhuma experiência prévia é necessária. Kotlin Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Plugins de autenticação: JWT e sessão”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Kotlin Academy?

Sim. Cada aula de Kotlin Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Configuração de projeto Ktor: embeddedServer e módulos de aplicação
  2. Roteamento e parâmetros tipados
  3. Negociação de conteúdo e kotlinx.serialization
  4. Plugins de autenticação: JWT e sessão
← Voltar para Kotlin Academy