Joken v1.3.0 Joken
Joken is the main API for configuring JWT token generation and validation.
All you need to generate a token is a Joken.Token
struct with proper values.
There you can set:
- json_module: choose your JSON library (currently supports Poison | JSX)
- signer: a map that tells the underlying system how to sign and verify your tokens
- validations: a map of claims keys to function validations
- claims: the map of values you want encoded in a token
- claims_generators: a map of functions for generating claims on each call
- token: the compact representation of a JWT token
- error: message indicating why a sign/verify operation failed
To help you fill that configuration struct properly, use the functions in this module.
Summary
Functions
Helper function to get the current time
See Joken.Signer.eddsa/2
See Joken.Signer.eddsa/2
See Joken.Signer.eddsa/2
See Joken.Signer.eddsa/2
See Joken.Signer.es/2
See Joken.Signer.es/2
See Joken.Signer.es/2
Convenience function to retrieve the claim set. Generated claims will only become available after signing the token
Convenience function to retrieve the compact token
Returns either the claims or the error
Convenience function to retrieve the error
See Joken.Signer.hs/2
See Joken.Signer.hs/2
See Joken.Signer.hs/2
See Joken.Signer.hs/2
Returns the claims without verifying. This is useful if verification and/or validation depends on data contained within the claim
See Joken.Signer.ps/2
See Joken.Signer.ps/2
See Joken.Signer.ps/2
See Joken.Signer.rs/2
See Joken.Signer.rs/2
See Joken.Signer.rs/2
Signs a given set of claims. If signing is successful it will put the compact token in the configuration’s token field and move generated claims into the claims set. Otherwise, it will fill the error field
Same as sign/1
but overrides any signer that was set in the configuration
Generates a Joken.Token
with the following defaults:
- Poison as the json_module
- claims: exp(now + 2 hours), iat(now), nbf(now - 100ms) and iss (“Joken”)
- validations for default :
- with_validation(“exp”, &(&1 > current_time))
- with_validation(“iat”, &(&1 <= current_time))
- with_validation(“nbf”, &(&1 < current_time))
Generates a Joken.Token
with either a custom payload or a compact token.
Defaults Poison as the json module
Runs verification on the token set in the configuration
Same as verify/3
except that it returns either:
{:ok, claims}
{:error, message}
Adds "aud"
claim with a given value
Adds a custom claim with a given value
Adds a claim generation function. This is intended for dynamic values
Adds the given map or struct as the claims for this token
Sets the given compact token into the given Joken.Token
struct
Adds "exp"
claim with a default generated value of now + 2hs
Adds "exp"
claim with a given value
Adds the specified key and value to the JOSE header
Adds the specified map as the JOSE header
Adds "iat"
claim with a default generated value of now
Adds "iat"
claim with a given value
Adds :iss
claim with a given value
Configures the default JSON module for Joken
Adds "jti"
claim with a given value
Adds "nbf"
claim with a default generated value of now - 1s
Adds "nbf"
claim with a given value
Adds a signer to a token configuration
Adds "sub"
claim with a given value
Adds a validation for a given claim key
Removes a validation for this token
Functions
Specs
get_claims(Joken.Token.t) :: map
Convenience function to retrieve the claim set. Generated claims will only become available after signing the token.
Specs
get_compact(Joken.Token.t) :: binary | nil
Convenience function to retrieve the compact token
Specs
get_data(Joken.Token.t) ::
{:ok, map} |
{:error, binary}
Returns either the claims or the error
Specs
get_error(Joken.Token.t) :: binary | nil
Convenience function to retrieve the error
Specs
peek(Joken.Token.t, list) :: map
Returns the claims without verifying. This is useful if verification and/or validation depends on data contained within the claim
Specs
sign(Joken.Token.t) :: Joken.Token.t
Signs a given set of claims. If signing is successful it will put the compact token in the configuration’s token field and move generated claims into the claims set. Otherwise, it will fill the error field.
Specs
sign(Joken.Token.t, Joken.Signer.t) :: Joken.Token.t
Same as sign/1
but overrides any signer that was set in the configuration.
Specs
token :: Joken.Token.t
Generates a Joken.Token
with the following defaults:
- Poison as the json_module
- claims: exp(now + 2 hours), iat(now), nbf(now - 100ms) and iss (“Joken”)
- validations for default :
- with_validation(“exp”, &(&1 > current_time))
- with_validation(“iat”, &(&1 <= current_time))
- with_validation(“nbf”, &(&1 < current_time))
Specs
token(binary | map) :: Joken.Token.t
Generates a Joken.Token
with either a custom payload or a compact token.
Defaults Poison as the json module.
Specs
verify(Joken.Token.t, Joken.Signer.t | nil, list) :: Joken.Token.t
Runs verification on the token set in the configuration.
It first checks the signature comparing the header with the one found in the signer.
Then it runs validations on the decoded payload. If everything passes then the configuration has all the claims available in the claims map.
It can receive options to verification. Acceptable options are:
skip_claims
: list of claim keys to skip validationas
: a module that Joken will use to convert the validated paylod into a struct
Specs
verify!(Joken.Token.t, Joken.Signer.t | nil, list) ::
{:ok, map} |
{:error, binary}
Same as verify/3
except that it returns either:
{:ok, claims}
{:error, message}
Specs
with_aud(Joken.Token.t, any) :: Joken.Token.t
Adds "aud"
claim with a given value.
Specs
with_claim(Joken.Token.t, String.t, any) :: Joken.Token.t
Adds a custom claim with a given value.
Specs
with_claim_generator(Joken.Token.t, String.t, function) :: Joken.Token.t
Adds a claim generation function. This is intended for dynamic values.
Specs
with_claims(Joken.Token.t, %{optional(String.t) => any}) :: Joken.Token.t
Adds the given map or struct as the claims for this token
Specs
with_compact_token(Joken.Token.t, binary) :: Joken.Token.t
Sets the given compact token into the given Joken.Token
struct.
Specs
with_exp(Joken.Token.t) :: Joken.Token.t
Adds "exp"
claim with a default generated value of now + 2hs.
Specs
with_exp(Joken.Token.t, non_neg_integer) :: Joken.Token.t
Adds "exp"
claim with a given value.
Specs
with_header_arg(Joken.Token.t, String.t, any) :: Joken.Token.t
Adds the specified key and value to the JOSE header
Specs
with_header_args(Joken.Token.t, %{optional(String.t) => any}) :: Joken.Token.t
Adds the specified map as the JOSE header.
Specs
with_iat(Joken.Token.t) :: Joken.Token.t
Adds "iat"
claim with a default generated value of now.
Specs
with_iat(Joken.Token.t, non_neg_integer) :: Joken.Token.t
Adds "iat"
claim with a given value.
Specs
with_iss(Joken.Token.t, any) :: Joken.Token.t
Adds :iss
claim with a given value.
Specs
with_json_module(Joken.Token.t, atom) :: Joken.Token.t
Configures the default JSON module for Joken.
Specs
with_jti(Joken.Token.t, any) :: Joken.Token.t
Adds "jti"
claim with a given value.
Specs
with_nbf(Joken.Token.t) :: Joken.Token.t
Adds "nbf"
claim with a default generated value of now - 1s.
Specs
with_nbf(Joken.Token.t, non_neg_integer) :: Joken.Token.t
Adds "nbf"
claim with a given value.
Specs
with_signer(Joken.Token.t, Joken.Signer.t) :: Joken.Token.t
Adds a signer to a token configuration.
This DOES NOT call sign/1
, sign/2
or verify/4
.
It only sets the signer in the token configuration.
Specs
with_sub(Joken.Token.t, any) :: Joken.Token.t
Adds "sub"
claim with a given value.
Specs
with_validation(Joken.Token.t, String.t, function, String.t | nil) :: Joken.Token.t
Adds a validation for a given claim key.
Validation works by applying the given function to the value of the matching claim key in the token payload.
If it is successful (e.g. the function returns a truthy value) the value is added
to the claims. If it fails (e.g. the function return nil or false) no claims
are added, and an error message is added to an "errors"
field. Also one of
the errors is used for the "error"
field.
By default, the error message for a failed validation is "Invalid payload"
,
however an optional argument can be provided, which is used as the error instead.
SECURITY WARNING: As a word of caution, be careful that your custom error messages do not leak detailed security implementations to your end users.
If a claim key in the payload does not have a validation, it WILL BE ADDED to the claim set. If a claim key has a validation, but it is not present in the payload, verification will fail with the default or provided error message.
example validation:
validated_token = token
|> with_validation("admin", &(&1 == true), "Must be admin")
|> with_validation("userId", &(&1 != 7))
|> with_signer(hs256("example"))
|> verify
when used with the following tokens:
#if token.claims == %{"admin" => true, "userId" => 6} then
validated_token == %{ claims: %{"admin" => true, "userId" => 6}, error: nil, errors: nil}
#if token.claims == %{"admin" => true, "userId" => 7} then
validated_token == %{
claims: nil,
error: "Invalid payload",
errors: ["Invalid payload"]
}
#if token == %{"userId" => 7} then
validated_token == %{
claims: nil,
error: #Order is not preserved, so this could be either of the two errors
errors: ["Must be admin", "Invalid payload"]
}
Specs
without_validation(Joken.Token.t, String.t) :: Joken.Token.t
Removes a validation for this token.