Scala support for JSON Web Token (JWT). Supports Java 1.6+, Scala 2.11.x and Scala 2.12.x. Optional helpers for Play Framework, Play JSON, Json4s Native, Json4s Jackson, Circe and uPickle.
JWT Scala is divided in several sub-projects each targeting a specific use-case. Depending on your need, you want to pick the right one.
Name | Description | Samples | Scaladoc |
---|---|---|---|
jwt-core |
Pure Scala | Jwt | API |
jwt-play-json |
play-json lib | JwtJson | API |
jwt-play |
Play framework | JwtSession | API |
jwt-json4s-native |
json4s Native implementation | JwtJson4s | API |
jwt-json4s-jackson |
json4s Jackson implementation | JwtJson4s | API |
jwt-circe |
circe lib | JwtCirce | API |
jwt-upickle |
uPickle lib | JwtUpickle | API |
If you need a previous version of the Scaladoc API, check the bottom of this page
You can also check a standalone Play application using jwt-play
and implementating a small REST API with authentication and admin role (include a UI too!).
In the following snippet, replace [name]
with the actual name of the project you need. Using Java 1.6 or 1.7? Add -legacy
after the name of the project. See below why.
build.sbt
libraryDependencies ++= Seq(
"com.pauldijou" %% "[name]" % "0.14.1"
)
build.sbt
libraryDependencies ++= Seq(
"com.pauldijou" %% "jwt-play-legacy" % "0.14.1"
)
"org.bouncycastle" % "bcpkix-jdk15on"
"commons-codec" % "commons-codec"
(only if Java 1.6 or 1.7)
If you are using String
key, please keep in mind that such keys need to be parsed. Rather than implementing a super complex parser, the one in JWT Scala is pretty simple and might not work for all use-cases (especially for ECDSA keys). In such case, consider using SecretKey
or PrivateKey
or PublicKey
directly. It is way better for you. All API support all those types.
Check ECDSA samples for more infos.
Name | Description |
---|---|
HMD5 | HMAC using MD5 algorithm |
HS224 | HMAC using SHA-224 algorithm |
HS256 | HMAC using SHA-256 algorithm |
HS384 | HMAC using SHA-384 algorithm |
HS512 | HMAC using SHA-512 algorithm |
RS256 | RSASSA using SHA-256 algorithm |
RS384 | RSASSA using SHA-384 algorithm |
RS512 | RSASSA using SHA-512 algorithm |
ES256 | ECDSA using SHA-256 algorithm |
ES384 | ECDSA using SHA-384 algorithm |
ES512 | ECDSA using SHA-512 algorithm |
Actually, all sub-projects have two flavours. One target Java 1.8+, using the new Time API and the new Base64 util. This is the default one. If you are using Java 1.6 or 1.7 (which have both reached end-of-life by the way), you will have to use the "legacy" version of the lib. It's exactly the same (in fact, 99% of the code source is shared) except it's using the old Calendar API and the Base64 util from Apache Commons Codec (introducing one small dependency in this particular use-case).
This lib doesn't want to impose anything, that's why, by default, a JWT claim is totally empty. That said, you should always add an issuedAt
attribute to it, probably using claim.issuedNow
. The reason is that even HTTPS isn't perfect and having always the same chunk of data transfered can be of a big help to crack it. Generating a slightly different token at each request is way better even if it adds a bit of payload to the response. If you are using a session timeout through the expiration
attribute which is extended at each request, that's fine too. I can't find the article I read about that vulnerability but if someone has some resources about the topic, I would be glad to link them.
If you found any bug or need more documentation, immediately feel an issue in GitHub. I should read most of them.
If you want to submit a PR to improve the project, that would be awesome. If, in top of that, you want to run the tests (yeah, because there are tests! A few of them...) before submitting it, you are just amasing but also don't run the tests globally. If you do sbt test
, the whole universe will nearly collapse due to classpath errors that are totally beyond the understanding of the current me. Run them by project, like playEdge/test
inside an sbt
console. And even so, they might fail because of a LinkageError
, just run them twice and it will work... I don't know why... I drank too much whisky trying to understand it so I just stopped. If you are a classpath God, just ping me and I will have questions for you.
- Test: run all tests with
sbt testAll
(ifjava.lang.LinkageError
, just re-run the command) - Publish: update version numbers in
build.sbt
and runsbt release
(be sure to eitherreload
inside sbt or start a new sbt) - Scaladoc: to manually generate all scaladoc, run
sbt scaladoc
- Publish docs: to manually build and push online the doc website, run
sbt publish-doc
- Docs: to have a locally running doc website:
sbt ~docs/makeSite
cd docs/target/site
jekyll serve
- Go to http://localhost:4000/jwt-scala/
This software is licensed under the Apache 2 license, quoted below.
Copyright 2015 Paul Dijou (http://pauldijou.fr).
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.