https://github.com/vonage/vonage-jwt-jdk
Library to assist with generating JWT tokens in JVM-based languages for use with the Vonage API.
https://github.com/vonage/vonage-jwt-jdk
Last synced: about 2 months ago
JSON representation
Library to assist with generating JWT tokens in JVM-based languages for use with the Vonage API.
- Host: GitHub
- URL: https://github.com/vonage/vonage-jwt-jdk
- Owner: Vonage
- License: mit
- Created: 2022-08-09T11:13:12.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-07-11T16:36:40.000Z (12 months ago)
- Last Synced: 2024-07-11T19:46:39.992Z (12 months ago)
- Language: Kotlin
- Size: 77.1 KB
- Stars: 1
- Watchers: 10
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Vonage JWT JDK Library
[](https://central.sonatype.com/artifact/com.vonage/jwt)
[](https://github.com/Vonage/vonage-jwt-jdk/actions/workflows/build.yml)
[](https://codecov.io/gh/Vonage/vonage-jwt-jdk)
[](https://scorecard.dev/viewer/?uri=github.com/Vonage/vonage-jwt-jdk)
[](https://sloc.xyz/github/Vonage/vonage-jwt-jdk)
[](https://javadoc.io/doc/com.vonage/jwt/latest/index.html)
[](CODE_OF_CONDUCT.md)
[](LICENSE)
This library provides a wrapper for generating JWTs using Vonage-specific claims.
It is mainly used by the [Vonage Java Server SDK](https://github.com/Vonage/vonage-java-sdk).
Learn more about [Authenticating with JSON Web Tokens](https://developer.vonage.com/concepts/guides/authentication#json-web-tokens-jwt).
## Installation
For Gradle:
```groovy
dependencies {
implementation 'com.vonage:jwt:2.0.1'
}
```
For Maven:
```xml
com.vonage
jwt
2.0.1
```
## Usage
The JWT library provides a `Jwt.Builder` which can be used to construct a `Jwt` representation.
The `Jwt` class contains a `generate()` method for generating JSON Web Signatures that can then
be used to authenticate with the API.
### Generating a JWT
The API requires an `application_id` claim, and the token needs to be signed with a private key.
The corresponding public key is uploaded to Vonage for signature verification.
The library expects you to provide a `PKCS#8` key contents or file path.
#### Generating a JWT with Private Key Contents
To generate a JWT with these properties you can use:
```java
var jws = Jwt.builder()
.applicationId("your-application-uuid")
.privateKeyContents("private key contents")
.build().generate();
```
#### Generating a JWT with Private Key Path
You can also provide a `Path` to the location of your private key:
```java
var jws = Jwt.builder()
.applicationId("your-application-id")
.privateKeyPath("/path/to/private.key")
.build().generate();
```
### Setting the claims
All token claims (both standard and custom) can be set
using the builder's methods before calling `.build()`. You can also leverage the underlying
[Auth0 JWT library](https://github.com/auth0/java-jwt)'s builder using the `withProperties`
method. For example, to set the `nbf` ("not before") and `exp` ("expires at") claims as a
`Date` or `Instant`, you can do:
```java
var jws = Jwt.builder()
.applicationId("your-application-id")
.privateKeyPath("/path/to/private.key")
.withProperties(jb -> jb
.withNotBefore(Instant.now())
.withExpiresAt(Instant.now().plus(Duration.ofHours(6)))
)
.build().generate();
```
#### Generating a JWT with Custom Claims
In some instances, you might want to define custom claims.
```java
// Add them individually using addClaim
var jws = Jwt.builder()
.applicationId("your-application-id")
.privateKeyPath("/path/to/private.key")
.addClaim("foo", "bar")
.addClaim("bat", "baz")
.build().generate();
// Or add multiples using a map
var jws = Jwt.builder()
.applicationId("your-application-id")
.privateKeyPath("/path/to/private.key")
.claims(Map.of("foo", "bar", "bat", "baz"))
.build().generate();
// Or add using the Auth0 builder
var jws = Jwt.builder()
.applicationId("your-application-id")
.privateKeyPath("/path/to/private.key")
.withProperties(jb -> jb.withClaim("claim-name", claimValue))
.build().generate();
```