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

current_time()

Helper function to get the current time

es256(key)

See Joken.Signer.es/2

es384(key)

See Joken.Signer.es/2

es512(key)

See Joken.Signer.es/2

get_claims(token)

Specs

get_claims(Joken.Token.t) :: map

Convenience function to retrieve the claim set

get_compact(token)

Specs

get_compact(Joken.Token.t) :: binary | nil

Convenience function to retrieve the compact token

get_data(token)

Specs

get_data(Joken.Token.t) ::
  {:ok, map} |
  {:error, binary}

Returns either the claims or the error

get_error(token)

Specs

get_error(Joken.Token.t) :: binary | nil

Convenience function to retrieve the error

hs256(secret)

See Joken.Signer.hs/2

hs384(secret)

See Joken.Signer.hs/2

hs512(secret)

See Joken.Signer.hs/2

none(secret)

See Joken.Signer.hs/2

peek(token, options \\ [])

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

ps256(key)

See Joken.Signer.ps/2

ps384(key)

See Joken.Signer.ps/2

ps512(key)

See Joken.Signer.ps/2

rs256(key)

See Joken.Signer.rs/2

rs384(key)

See Joken.Signer.rs/2

rs512(key)

See Joken.Signer.rs/2

sign(token)

Specs

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.

sign(token, signer)

Same as sign/1 but overrides any signer that was set in the configuration.

token()

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))
token(payload)

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.

verify(token, signer \\ nil, options \\ [])

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 validation
  • as: a module that Joken will use to convert the validated paylod into a sturct
verify!(token, signer \\ nil, options \\ [])

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}
with_aud(token, aud)

Specs

with_aud(Joken.Token.t, any) :: Joken.Token.t

Adds "aud" claim with a given value.

with_claim(token, claim_key, claim_value)

Specs

with_claim(Joken.Token.t, String.t, any) :: Joken.Token.t

Adds a custom claim with a given value.

with_claim_generator(token, claim, fun)

Specs

with_claim_generator(Joken.Token.t, String.t, function) :: Joken.Token.t

Adds a claim generation function. This is intended for dynamic values.

with_claims(token, claims)

Specs

with_claims(Joken.Token.t, %{String.t => any}) :: Joken.Token.t

Adds the given map or struct as the claims for this token

with_compact_token(token, compact)

Specs

with_compact_token(Joken.Token.t, binary) :: Joken.Token.t

Sets the given compact token into the given Joken.Token struct.

with_exp(token)

Specs

Adds "exp" claim with a default generated value of now + 2hs.

with_exp(token, time_to_expire)

Specs

with_exp(Joken.Token.t, non_neg_integer) :: Joken.Token.t

Adds "exp" claim with a given value.

with_header_arg(token, key, value)

Specs

with_header_arg(Joken.Token.t, String.t, any) :: Joken.Token.t

Adds the specified key and value to the JOSE header

with_header_args(token, header)

Specs

with_header_args(Joken.Token.t, %{String.t => any}) :: Joken.Token.t

Adds the specified map as the JOSE header.

with_iat(token)

Specs

Adds "iat" claim with a default generated value of now.

with_iat(token, time_issued_at)

Specs

with_iat(Joken.Token.t, non_neg_integer) :: Joken.Token.t

Adds "iat" claim with a given value.

with_iss(token, issuer)

Specs

with_iss(Joken.Token.t, any) :: Joken.Token.t

Adds :iss claim with a given value.

with_json_module(token, module)

Specs

with_json_module(Joken.Token.t, atom) :: Joken.Token.t

Configures the default JSON module for Joken.

with_jti(token, jti)

Specs

with_jti(Joken.Token.t, any) :: Joken.Token.t

Adds "jti" claim with a given value.

with_nbf(token)

Specs

Adds "nbf" claim with a default generated value of now - 1s.

with_nbf(token, time_not_before)

Specs

with_nbf(Joken.Token.t, non_neg_integer) :: Joken.Token.t

Adds "nbf" claim with a given value.

with_signer(token, signer)

Specs

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.

with_sub(token, sub)

Specs

with_sub(Joken.Token.t, any) :: Joken.Token.t

Adds "sub" claim with a given value.

with_validation(token, claim, function)

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.

without_validation(token, claim)

Specs

without_validation(Joken.Token.t, String.t) :: Joken.Token.t

Removes a validation for this token.