jwt
Signature
def jwt(): Directive1[JwtClaims]
def jwt(settings: scaladsl.JwtSettings): Directive1[JwtClaims]
Description
This directive provides a way to validate a JSON Web Token (JWT) from a request and extracts its claims for further processing. For details on what a valid JWT is, see jwt.io or consult RFC 7519.
JWTs are validated against a predefined secret or public key, depending on the used algorithm, and provided by configuration. The directive uses config defined under akka.http.jwt
, or an explicitly provided JwtSettings
instance.
Dependency
The Akka dependencies are available from Akka’s library repository. To access them there, you need to configure the URL for this repository.
To use Akka HTTP Caching, add the module to your project:
- sbt
val AkkaHttpVersion = "10.6.3" libraryDependencies += "com.typesafe.akka" %% "akka-http-jwt" % AkkaHttpVersion
- Gradle
- Maven
Example
The jwt
directive will extract and validate a JWT from the request and provide the extracted claims to the inner route in the format of a JwtClaims
instance, which offers utility methods to extract a specific claims:
- Scala
-
source
val route = jwt() { _.stringClaim("role") match { case Some("admin") => complete(s"You're in!") case _ => reject(AuthorizationFailedRejection) } } // tests: // regular request // manually injected valid JWT for test purposes with a claim "role" -> "admin" val jwtToken = Authorization(OAuth2BearerToken( "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwicm9sZSI6ImFkbWluIn0.6JBvEPNY4KVZpZYfoG6y5UOh3RLUbG-kPyxKHim_La8")) Get() ~> addHeader(jwtToken) ~> route ~> check { responseAs[String] shouldEqual "You're in!" }
- Java
Reference configuration
sourcejwt {
# Enables or disables the JWT signature validation.
# This is useful for development and testing purposes
# where you can still assert presence of claims without using a real signature.
dev = off
# The realm to use in the WWW-Authenticate header when a token is missing or invalid.
realm = "akka-http-jwt"
# Allows configuration for the JWT secrets used to verify tokens.
# The list of supported algorithms is as follows:
# - symmetric: HMD5, HS224, HS256, HS384 and HS512
# - asymmetric: RS256, RS384, RS512, ES256, ES384, ES512 and Ed25519
# Symmetric algorithms require either a secret in 'secret' or a filesystem path with a secret via 'secret-path', the former is ignored and the later takes precedence.
# Asymmetric algorithms require a filesystem path for a public key via 'public-key'.
#
# An example config would be:
# secrets: [
# {
# # The key-id is mandatory and should be unique for each secret.
# key-id: my-key-symmetric
# # The issuer is optional and can be used to validate the 'iss' claim.
# issuer: my-issuer
# algorithm: HS256
# # The secret can be set via an environment variable or loaded from a file.
# # To load the secret from an environment variables use:
# secret: ${MY_PRECIOUS_SECRET}
# # To load the secret from a file use (and remove the above secret setting):
# # secret-path: /path/to/secret.key
# },
# {
# key-id: my-key-asymmetric
# issuer: my-issuer
# algorithm: RS256
# # The public key used for JWT validation should be provided with the following setting:
# public-key: /path/to/public.key
# }
# ]
#
# NOTE: If configuring multiple secrets for the same algorithm, the first one found will be used
# in cases where the Key Id ("kid") is not specified in the JWT token header.
secrets: []
}