joken v1.0.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.es/2
See Joken.Signer.es/2
See Joken.Signer.es/2
Convenience function to retrieve the claim set
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. 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
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. 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 sturct
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, %{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, %{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) :: Joken.Token.t
Adds a validation for a given claim key.
Validation works by applying the given function passing the payload value for that key.
If it is successful the value is added to the claims. If it fails, then it will raise an ArgumentError.
If a claim in the payload has no validation, then it WILL BE ADDED to the claim set.
Specs
without_validation(Joken.Token.t, String.t) :: Joken.Token.t
Removes a validation for this token.