Tink's JWT library allows the creation and verification of JSON Web Tokens (JWT).
We recommend the JWT_ES256 key type for most use cases. For all supported key types, see Supported Key Types.
The following examples shows how to create JWTs, and how to convert the public keyset into the JWK set format.
C++
// An example for signing JSON Web Tokens (JWT).
#include <iostream>
#include <memory>
#include <ostream>
#include <string>
#include <utility>
#include "absl/flags/flag.h"
#include "absl/flags/parse.h"
#include "absl/log/check.h"
#include "absl/strings/string_view.h"
#include "absl/time/clock.h"
#include "absl/time/time.h"
#include "tink/config/global_registry.h"
#include "util/util.h"
#include "tink/jwt/jwt_public_key_sign.h"
#include "tink/jwt/jwt_signature_config.h"
#include "tink/jwt/raw_jwt.h"
#include "tink/keyset_handle.h"
#include "tink/util/status.h"
ABSL_FLAG(std::string, keyset_filename, "", "Keyset file in JSON format");
ABSL_FLAG(std::string, audience, "", "Expected audience in the token");
ABSL_FLAG(std::string, token_filename, "", "Path to the token file");
namespace {
using ::crypto::tink::JwtPublicKeySign;
using ::crypto::tink::KeysetHandle;
using ::crypto::tink::RawJwt;
using ::crypto::tink::RawJwtBuilder;
using ::crypto::tink::util::Status;
using ::crypto::tink::util::StatusOr;
void ValidateParams() {
// ...
}
} // namespace
namespace tink_cc_examples {
// JWT sign example CLI implementation.
Status JwtSign(const std::string& keyset_filename, absl::string_view audience,
const std::string& token_filename) {
Status result = crypto::tink::JwtSignatureRegister();
if (!result.ok()) return result;
// Read the keyset from file.
StatusOr<std::unique_ptr<KeysetHandle>> keyset_handle =
ReadJsonCleartextKeyset(keyset_filename);
if (!keyset_handle.ok()) return keyset_handle.status();
StatusOr<RawJwt> raw_jwt =
RawJwtBuilder()
.AddAudience(audience)
.SetExpiration(absl::Now() + absl::Seconds(100))
.Build();
if (!raw_jwt.ok()) return raw_jwt.status();
StatusOr<std::unique_ptr<JwtPublicKeySign>> jwt_signer =
(*keyset_handle)
->GetPrimitive<crypto::tink::JwtPublicKeySign>(
crypto::tink::ConfigGlobalRegistry());
if (!jwt_signer.ok()) return jwt_signer.status();
StatusOr<std::string> token = (*jwt_signer)->SignAndEncode(*raw_jwt);
if (!token.ok()) return token.status();
return WriteToFile(*token, token_filename);
}
} // namespace tink_cc_examples
int main(int argc, char** argv) {
absl::ParseCommandLine(argc, argv);
ValidateParams();
std::string keyset_filename = absl::GetFlag(FLAGS_keyset_filename);
std::string audience = absl::GetFlag(FLAGS_audience);
std::string token_filename = absl::GetFlag(FLAGS_token_filename);
std::clog << "Using keyset in " << keyset_filename << " to ";
std::clog << " generate and sign a token using audience '" << audience
<< "'; the resulting signature is written to " << token_filename
<< '\n';
CHECK_OK(
tink_cc_examples::JwtSign(keyset_filename, audience, token_filename));
return 0;
}
Go
func Example_signAndVerify() {
// A private keyset created with
// "tinkey create-keyset --key-template=JWT_ES256 --out private_keyset.cfg".
// Note that this keyset has the secret key information in cleartext.
privateJSONKeyset := `{
"primaryKeyId": 1742360595,
"key": [
{
"keyData": {
"typeUrl": "type.googleapis.com/google.crypto.tink.JwtEcdsaPrivateKey",
"value": "GiBgVYdAPg3Fa2FVFymGDYrI1trHMzVjhVNEMpIxG7t0HRJGIiBeoDMF9LS5BDCh6YgqE3DjHwWwnEKEI3WpPf8izEx1rRogbjQTXrTcw/1HKiiZm2Hqv41w7Vd44M9koyY/+VsP+SAQAQ==",
"keyMaterialType": "ASYMMETRIC_PRIVATE"
},
"status": "ENABLED",
"keyId": 1742360595,
"outputPrefixType": "TINK"
}
]
}`
// The corresponding public keyset created with
// "tinkey create-public-keyset --in private_keyset.cfg"
publicJSONKeyset := `{
"primaryKeyId": 1742360595,
"key": [
{
"keyData": {
"typeUrl": "type.googleapis.com/google.crypto.tink.JwtEcdsaPublicKey",
"value": "EAEaIG40E1603MP9RyoomZth6r+NcO1XeODPZKMmP/lbD/kgIiBeoDMF9LS5BDCh6YgqE3DjHwWwnEKEI3WpPf8izEx1rQ==",
"keyMaterialType": "ASYMMETRIC_PUBLIC"
},
"status": "ENABLED",
"keyId": 1742360595,
"outputPrefixType": "TINK"
}
]
}`
// Create a keyset handle from the cleartext private keyset in the previous
// step. The keyset handle provides abstract access to the underlying keyset to
// limit the access of the raw key material. WARNING: In practice,
// it is unlikely you will want to use a insecurecleartextkeyset, as it implies
// that your key material is passed in cleartext, which is a security risk.
// Consider encrypting it with a remote key in Cloud KMS, AWS KMS or HashiCorp Vault.
// See https://github.com/google/tink/blob/master/docs/GOLANG-HOWTO.md#storing-and-loading-existing-keysets.
privateKeysetHandle, err := insecurecleartextkeyset.Read(
keyset.NewJSONReader(bytes.NewBufferString(privateJSONKeyset)))
if err != nil {
log.Fatal(err)
}
// Retrieve the JWT Signer primitive from privateKeysetHandle.
signer, err := jwt.NewSigner(privateKeysetHandle)
if err != nil {
log.Fatal(err)
}
// Use the primitive to create and sign a token. In this case, the primary key of the
// keyset will be used (which is also the only key in this example).
expiresAt := time.Now().Add(time.Hour)
audience := "example audience"
subject := "example subject"
rawJWT, err := jwt.NewRawJWT(&jwt.RawJWTOptions{
Audience: &audience,
Subject: &subject,
ExpiresAt: &expiresAt,
})
if err != nil {
log.Fatal(err)
}
token, err := signer.SignAndEncode(rawJWT)
if err != nil {
log.Fatal(err)
}
// Create a keyset handle from the keyset containing the public key. Because the
// public keyset does not contain any secrets, we can use [keyset.ReadWithNoSecrets].
publicKeysetHandle, err := keyset.ReadWithNoSecrets(
keyset.NewJSONReader(bytes.NewBufferString(publicJSONKeyset)))
if err != nil {
log.Fatal(err)
}
// Retrieve the Verifier primitive from publicKeysetHandle.
verifier, err := jwt.NewVerifier(publicKeysetHandle)
if err != nil {
log.Fatal(err)
}
// Verify the signed token.
validator, err := jwt.NewValidator(&jwt.ValidatorOpts{ExpectedAudience: &audience})
if err != nil {
log.Fatal(err)
}
verifiedJWT, err := verifier.VerifyAndDecode(token, validator)
if err != nil {
log.Fatal(err)
}
// Extract subject claim from the token.
if !verifiedJWT.HasSubject() {
log.Fatal(err)
}
extractedSubject, err := verifiedJWT.Subject()
if err != nil {
log.Fatal(err)
}
fmt.Println(extractedSubject)
// Output: example subject
}
Java
package jwt;
import static java.nio.charset.StandardCharsets.UTF_8;
import com.google.crypto.tink.InsecureSecretKeyAccess;
import com.google.crypto.tink.KeysetHandle;
import com.google.crypto.tink.TinkJsonProtoKeysetFormat;
import com.google.crypto.tink.jwt.JwtPublicKeySign;
import com.google.crypto.tink.jwt.JwtSignatureConfig;
import com.google.crypto.tink.jwt.RawJwt;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.time.Instant;
/**
* A command-line utility for signing JSON Web Tokens (JWTs).
*
* <p>It loads cleartext private keys from disk - this is not recommended!
*
* <p>It requires the following arguments:
*
* <ul>
* <li>private-keyset-file: Name of the input file containing the private keyset.
* <li>audience: The audience claim to be used in the token
* <li>token-file: name of the output file containing the signed JWT.
*/
public final class JwtSign {
public static void main(String[] args) throws Exception {
if (args.length != 3) {
System.err.printf("Expected 3 parameters, got %d\n", args.length);
System.err.println(
"Usage: java JwtSign private-keyset-file audience token-file");
System.exit(1);
}
Path privateKeysetFile = Paths.get(args[0]);
String audience = args[1];
Path tokenFile = Paths.get(args[2]);
// Register all JWT signature key types with the Tink runtime.
JwtSignatureConfig.register();
// Read the private keyset into a KeysetHandle.
KeysetHandle privateKeysetHandle =
TinkJsonProtoKeysetFormat.parseKeyset(
new String(Files.readAllBytes(privateKeysetFile), UTF_8),
InsecureSecretKeyAccess.get());
// Get the primitive.
JwtPublicKeySign signer = privateKeysetHandle.getPrimitive(JwtPublicKeySign.class);
// Use the primitive to sign a token that expires in 100 seconds.
RawJwt rawJwt =
RawJwt.newBuilder()
.addAudience(audience)
.setExpiration(Instant.now().plusSeconds(100))
.build();
String signedToken = signer.signAndEncode(rawJwt);
Files.write(tokenFile, signedToken.getBytes(UTF_8));
}
private JwtSign() {}
}
Python
"""A utility for creating and signing JSON Web Tokens (JWT).
It loads cleartext keys from disk - this is not recommended!
"""
import datetime
from absl import app
from absl import flags
from absl import logging
import tink
from tink import jwt
from tink import secret_key_access
_PRIVATE_KEYSET_PATH = flags.DEFINE_string(
'private_keyset_path', None,
'Path to the keyset used for the JWT signature operation.')
_AUDIENCE = flags.DEFINE_string('audience', None,
'Audience to be used in the token')
_TOKEN_PATH = flags.DEFINE_string('token_path', None, 'Path to the token file.')
def main(argv):
del argv # Unused.
# Initialise Tink
jwt.register_jwt_signature()
# Read the keyset into a KeysetHandle
with open(_PRIVATE_KEYSET_PATH.value, 'rt') as keyset_file:
try:
text = keyset_file.read()
keyset_handle = tink.json_proto_keyset_format.parse(
text, secret_key_access.TOKEN
)
except tink.TinkError as e:
logging.exception('Error reading keyset: %s', e)
return 1
now = datetime.datetime.now(tz=datetime.timezone.utc)
# Get the JwtPublicKeySign primitive
try:
jwt_sign = keyset_handle.primitive(jwt.JwtPublicKeySign)
except tink.TinkError as e:
logging.exception('Error creating JwtPublicKeySign: %s', e)
return 1
# Create token
raw_jwt = jwt.new_raw_jwt(
audiences=[_AUDIENCE.value],
expiration=now + datetime.timedelta(seconds=100))
token = jwt_sign.sign_and_encode(raw_jwt)
with open(_TOKEN_PATH.value, 'wt') as token_file:
token_file.write(token)
logging.info('Token has been written to %s', _TOKEN_PATH.value)
if __name__ == '__main__':
flags.mark_flags_as_required(
['private_keyset_path', 'audience', 'token_path'])
app.run(main)
A common way to share the public keyset is the JWK set format. The following example shows how to convert the public keyset into the JWK set format.
C++
// An example for converting a Tink keyset with public keys into a JWK set.
#include <iostream>
#include <memory>
#include <ostream>
#include <string>
#include "absl/flags/flag.h"
#include "absl/flags/parse.h"
#include "absl/log/check.h"
#include "util/util.h"
#include "tink/jwt/jwk_set_converter.h"
#include "tink/jwt/jwt_signature_config.h"
#include "tink/keyset_handle.h"
#include "tink/util/status.h"
ABSL_FLAG(std::string, public_keyset_filename, "",
"Public keyset file in Tink's JSON format");
ABSL_FLAG(std::string, public_jwk_set_filename, "",
"Path to the output public JWK set file");
namespace {
using ::crypto::tink::JwkSetFromPublicKeysetHandle;
using ::crypto::tink::KeysetHandle;
using ::crypto::tink::util::Status;
using ::crypto::tink::util::StatusOr;
void ValidateParams() {
// ...
}
} // namespace
namespace tink_cc_examples {
Status JwtGeneratePublicJwkSet(const std::string& public_keyset_filename,
const std::string& public_jwk_set_filename) {
Status result = crypto::tink::JwtSignatureRegister();
if (!result.ok()) return result;
StatusOr<std::unique_ptr<KeysetHandle>> keyset_handle =
ReadJsonCleartextKeyset(public_keyset_filename);
if (!keyset_handle.ok()) return keyset_handle.status();
StatusOr<std::string> public_jwk_set =
JwkSetFromPublicKeysetHandle(**keyset_handle);
if (!public_jwk_set.ok()) return keyset_handle.status();
return WriteToFile(*public_jwk_set, public_jwk_set_filename);
}
} // namespace tink_cc_examples
int main(int argc, char** argv) {
absl::ParseCommandLine(argc, argv);
ValidateParams();
std::string public_keyset_filename =
absl::GetFlag(FLAGS_public_keyset_filename);
std::string public_jwk_set_filename =
absl::GetFlag(FLAGS_public_jwk_set_filename);
std::clog << "Convert public keyset in " << public_keyset_filename << " to ";
std::clog << " to JWK set format; the result is written to "
<< public_jwk_set_filename << '\n';
CHECK_OK(tink_cc_examples::JwtGeneratePublicJwkSet(public_keyset_filename,
public_jwk_set_filename));
return 0;
}
Go
func Example_generateJWKS() {
// A Tink keyset in JSON format with one JWT public key.
publicJSONKeyset := `{
"primaryKeyId": 185188009,
"key": [
{
"keyData": {
"typeUrl": "type.googleapis.com/google.crypto.tink.JwtRsaSsaPkcs1PublicKey",
"value": "EAEagQIAs9iifvWObNLbP+x7zupVIYTdHKba4VFgJEnnGtIII21R+KGddTdvNGAokd4GPrFk1GDPitHrAAoW1+NWrafsEUi2J9Sy3uwEyarsKDggewoBCNg2fcWAiZXplPjUyTlhrLvTuyrcL/mGPy+ib7bdmov+D2EP+rKUH6/ydtQGiyHRR3uurTUWfrMD1/6WaBVfngpy5Pxs2nuHXRmBHQKWmPfvErgr4abdjhKDaWIuxzSise1CSAbiWTNcxpIuFYZgPjgQzpqeh93LUXIX9YJds/bhHtXqRdxk6yTisloHOZETItK/rHCCE25dLkkaJ2Li7AtnJdBc6tEUNiuFj2JCjSIDAQAB",
"keyMaterialType": "ASYMMETRIC_PUBLIC"
},
"status": "ENABLED",
"keyId": 185188009,
"outputPrefixType": "TINK"
}
]
}`
// Create a keyset handle from the keyset containing the public key. Because the
// public keyset does not contain any secrets, we can use [keyset.ReadWithNoSecrets].
publicKeysetHandle, err := keyset.ReadWithNoSecrets(
keyset.NewJSONReader(bytes.NewBufferString(publicJSONKeyset)))
if err != nil {
log.Fatal(err)
}
// Create a publicJWKset from publicKeysetHandle.
publicJWKset, err := jwt.JWKSetFromPublicKeysetHandle(publicKeysetHandle)
if err != nil {
log.Fatal(err)
}
// Remove whitespace so that we can compare it to the expected string.
compactPublicJWKset := &bytes.Buffer{}
err = json.Compact(compactPublicJWKset, publicJWKset)
if err != nil {
log.Fatal(err)
}
fmt.Println(compactPublicJWKset.String())
// Output:
// {"keys":[{"alg":"RS256","e":"AQAB","key_ops":["verify"],"kid":"Cwm-qQ","kty":"RSA","n":"ALPYon71jmzS2z_se87qVSGE3Rym2uFRYCRJ5xrSCCNtUfihnXU3bzRgKJHeBj6xZNRgz4rR6wAKFtfjVq2n7BFItifUst7sBMmq7Cg4IHsKAQjYNn3FgImV6ZT41Mk5Yay707sq3C_5hj8vom-23ZqL_g9hD_qylB-v8nbUBosh0Ud7rq01Fn6zA9f-lmgVX54KcuT8bNp7h10ZgR0Clpj37xK4K-Gm3Y4Sg2liLsc0orHtQkgG4lkzXMaSLhWGYD44EM6anofdy1FyF_WCXbP24R7V6kXcZOsk4rJaBzmREyLSv6xwghNuXS5JGidi4uwLZyXQXOrRFDYrhY9iQo0","use":"sig"}]}
}
Java
package jwt;
import static java.nio.charset.StandardCharsets.UTF_8;
import com.google.crypto.tink.InsecureSecretKeyAccess;
import com.google.crypto.tink.KeysetHandle;
import com.google.crypto.tink.TinkJsonProtoKeysetFormat;
import com.google.crypto.tink.jwt.JwkSetConverter;
import com.google.crypto.tink.jwt.JwtSignatureConfig;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
/**
* A command-line example for generating the public JWT keyset in JWK set format.
*
* <p>It loads cleartext private keys from disk - this is not recommended!
*
* <p>It requires the following arguments:
*
* <ul>
* <li>private-keyset-file: Name of the input file containing the private keyset.
* <li>public-jwkset-file: Name of the output file containing the public key in JWK set format.
*/
public final class JwtGeneratePublicJwkSet {
public static void main(String[] args) throws Exception {
if (args.length != 2) {
System.err.printf("Expected 2 parameters, got %d\n", args.length);
System.err.println(
"Usage: java JwtGeneratePublicJwkSet private-keyset-file public-jwk-set-file");
System.exit(1);
}
Path privateKeysetFile = Paths.get(args[0]);
Path publicJwkSetFile = Paths.get(args[1]);
// Register all JWT signature key types with the Tink runtime.
JwtSignatureConfig.register();
// Read the keyset into a KeysetHandle.
KeysetHandle privateKeysetHandle =
TinkJsonProtoKeysetFormat.parseKeyset(
new String(Files.readAllBytes(privateKeysetFile), UTF_8),
InsecureSecretKeyAccess.get());
// Export the public keyset as JWK set.
String publicJwkSet =
JwkSetConverter.fromPublicKeysetHandle(privateKeysetHandle.getPublicKeysetHandle());
Files.write(publicJwkSetFile, publicJwkSet.getBytes(UTF_8));
}
private JwtGeneratePublicJwkSet() {}
}
Python
"""A utility for generating the public JWK set from the public keyset.
"""
from absl import app
from absl import flags
from absl import logging
import tink
from tink import jwt
_PUBLIC_KEYSET_PATH = flags.DEFINE_string(
'public_keyset_path', None,
'Path to the public keyset in Tink JSON format.')
_PUBLIC_JWK_SET_PATH = flags.DEFINE_string(
'public_jwk_set_path', None, 'Path to public keyset in JWK format.')
def main(argv):
del argv # Unused.
# Initialise Tink
jwt.register_jwt_signature()
# Read the keyset into a KeysetHandle
with open(_PUBLIC_KEYSET_PATH.value, 'rt') as keyset_file:
try:
text = keyset_file.read()
public_keyset_handle = tink.read_no_secret_keyset_handle(
tink.JsonKeysetReader(text))
except tink.TinkError as e:
logging.exception('Error reading keyset: %s', e)
return 1
# Export Public Keyset as JWK set
public_jwk_set = jwt.jwk_set_from_public_keyset_handle(public_keyset_handle)
with open(_PUBLIC_JWK_SET_PATH.value, 'wt') as public_jwk_set_file:
public_jwk_set_file.write(public_jwk_set)
logging.info('The public JWK set has been written to %s',
_PUBLIC_JWK_SET_PATH.value)
if __name__ == '__main__':
flags.mark_flags_as_required(['public_keyset_path', 'public_jwk_set_path'])
app.run(main)