JWT and JWK authentication

Ktor supports JWT (JSON Web Tokens), which is a mechanism for authenticating JSON-encoded payloads.It is useful to create stateless authenticated APIs in the standard way, since there are client libraries for itin a myriad of languages.

This feature will handle Authorization: Bearer <JWT-TOKEN>.

This feature is defined in the method io.ktor.auth.jwt.jwt in the artifact io.ktor:ktor-auth-jwt:$ktor_version.

dependencies { implementation "io.ktor:ktor-auth-jwt:$ktor_version"}

dependencies { implementation("io.ktor:ktor-auth-jwt:$ktor_version")}

<project> … <dependencies> <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-auth-jwt</artifactId> <version>${ktor.version}</version> <scope>compile</scope> </dependency> </dependencies></project>

Ktor has a couple of classes to use the JWT Payload as Credential or as Principal.

  1. class JWTCredential(val payload: Payload) : Credential
  2. class JWTPrincipal(val payload: Payload) : Principal

Configuring server/routes:

JWT and JWK each have their own method with slightly different parameters. Both require the realm parameter, which is used in the WWW-Authenticate response header.

Using a verifier and a validator:

The verifier will use the secret to verify the signature to trust the source.You can also check the payload within validate callback to ensure everything is right and to produce a Principal.

application.conf:

  1. jwt {
  2.     domain = "https://jwt-provider-domain/"
  3.     audience = "jwt-audience"
  4.     realm = "ktor sample app"
  5. }

JWT auth:

  1. val jwtIssuer = environment.config.property("jwt.domain").getString()
  2. val jwtAudience = environment.config.property("jwt.audience").getString()
  3. val jwtRealm = environment.config.property("jwt.realm").getString()
  5. install(Authentication) {
  6.     jwt {
  7.         realm = jwtRealm
  8.         verifier(makeJwtVerifier(jwtIssuer), jwtIssuer)
  9.         validate { credential ->
  10.             if (credential.payload.audience.contains(jwtAudience)) JWTPrincipal(credential.payload) else null
  11.         }
  12.     }
  13. }

Using a JWK provider:

  1. fun AuthenticationPipeline.jwtAuthentication(jwkProvider: JwkProvider, issuer: String, realm: String, validate: (JWTCredential) -> Principal?)
  1. val jwkIssuer = "https://jwt-provider-domain/"
  2. val jwkRealm = "ktor jwt auth test"
  3. val jwkProvider = JwkProviderBuilder(jwkIssuer)
  4.             .cached(10, 24, TimeUnit.HOURS)
  5.             .rateLimited(10, 1, TimeUnit.MINUTES)
  6.             .build()
  7. install(Authentication) {
  8.     jwt {
  9.         verifier(jwkProvider, jwkIssuer)
  10.         realm = jwkRealm
  11.         validate { credentials ->
  12.             if (credentials.payload.audience.contains(audience)) JWTPrincipal(credentials.payload) else null
  13.         }
  14.     }
  15. }