kjwt

kjwt = Kotlin JSON Web Tokens

Kotlin multi-platform JSON Web Token (JWT/JWS) library.

Status

Warning

This project is being actively developed but is in an early experimental state. Use the library cautiously and report back any issues. mooncloak is not responsible for any issues faced when using the library.

Getting Started 🏁

Checkout the releases page to get the latest version.

Repository

repositories {
    maven("https://repo.repsy.io/mvn/mooncloak/public")
}

Dependencies

implementation("com.mooncloak.kodetools.kjwt:kjwt-core:VERSION")

Usage

The following library usage examples, and more, can be found in the sample module.

Creating a JWT (Signed JWS)

The following example illustrates how to create a CompactedJwt. The full source code can be found here.

Jwt {
    header {
        signatureAlgorithm = algorithm
        keyId = "MY_KEY_ID"
        // ...
    }

    payload {
        this.issuedAt = Clock.System.now()
        this["custom_claim"] = JsonPrimitive("CUSTOM_CLAIM_VALUE")
        this.putValue(key = "other_custom_claim", value = 0)
        // ...
    }
}.sign(
    resolver = keyResolver
).compact()

Parsing a compacted JWS

The following example illustrates how to parse a CompactedJwt. The full source code can be found here.

val (header, payload, signature) = Jws.parse(
    compacted = compactedJwt,
    resolver = keyResolver
)

JSON Web Keys (JWKs and JWKSets)

JWKs are used to sign, verify, encrypt, and decrypt JWTs. They are essential for working with JWTs and it is up to an application to define where it obtains its JWKs. This library provides Jwk and JwkSet components, as well as a KeyResolver component which is used to obtain a JWK.

Creating a JWK

To create a JSON Web Key, use the [Jwk.invoke] constructor function:

Jwk(keyType = KeyType.RSA) {
    keyId = "abc123"
    signatureAlgorithm = SignatureAlgorithm.HS256
    keyOperations = listOf(KeyOperation.Sign, KeyOperation.Verify)
    use = KeyUse.Sig
    // ...
}

The full source code can be found here

Documentation 📃

More detailed documentation is available in the docs folder. The entry point to the documentation can be found here.

Security 🛡️

For security vulnerabilities, concerns, or issues, please refer to the security policy for more information on appropriate approaches for disclosure.

Contributing ✍️

Outside contributions are welcome for this project. Please follow the code of conduct and coding conventions when contributing. If contributing code, please add thorough documents and tests. Thank you!

License ⚖️

Copyright 2024 mooncloak

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file 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.