NAME

    Mojo::JWT - JSON Web Token the Mojo way

SYNOPSIS

      my $jwt = Mojo::JWT->new(claims => {...}, secret => 's3cr3t')->encode;
      my $claims = Mojo::JWT->new(secret => 's3cr3t')->decode($jwt);

DESCRIPTION

    JSON Web Token is described in https://tools.ietf.org/html/rfc7519.
    Mojo::JWT implements that standard with an API that should feel
    familiar to Mojolicious users (though of course it is useful
    elsewhere). Indeed, JWT is much like Mojolicious::Sessions except that
    the result is a url-safe text string rather than a cookie.

    In JWT, the primary payload is called the claims, and a few claims are
    reserved, as seen in the IETF document. The header and the claims are
    signed when stringified to guard against tampering. Note that while
    signed, the data is not encrypted, so don't use it to send secrets over
    clear channels.

ATTRIBUTES

    Mojo::JWT inherits all of the attributes from Mojo::Base and implements
    the following new ones.

 algorithm

    The algorithm to be used to sign a JWT during encoding or else the
    algorithm that was used for the most recent decoding. Defaults to HS256
    until a decode is performed.

    none is an acceptable encoding algorithm, however for it to be used to
    decode, "allow_none" must be set.

 allow_none

    To prevent spoofing attacks, allow_none must be explicitly set to a
    true value otherwise decoding a JWT which specifies the none algorithm
    will result in an exception. The default is of course false.

 claims

    The payload to be encoded or else the claims from the most recent
    decoding. This must be a hash reference, array references are not
    allowed as the top-level JWT claims.

 expires

    The epoch time value after which the JWT value should not be considered
    valid. This value (if set and not undefined) will be used as the exp
    key in the claims or was extracted from the claims during the most
    recent decoding.

 header

    You may set your own headers when encoding the JWT bypassing a hash
    reference to the "header" attribute. Please note that there are two
    default headers set. alg is set to the value of "algorithm" or 'HS256'
    and typ is set to 'JWT'. These cannot be overridden.

 not_before

    The epoch time value before which the JWT value should not be
    considered valid. This value (if set and not undefined) will be used as
    the nbf key in the claims or was extracted from the claims during the
    most recent decoding.

 public

    The public key to be used in decoding an asymmetrically signed JWT (eg.
    RSA). This can be any public key in a string format accepted by
    Crypt::PK::RSA or a Crypt::PK::RSA object (if used a
    Crypt::OpenSSL::RSA object will be converted).

 secret

    The symmetric secret (eg. HMAC) or else the private key used in
    encoding an asymmetrically signed JWT (eg. RSA). Symmetric secrets
    should be a string. A private key can be in a string format accepted by
    Crypt::PK::RSA or a Crypt::PK::RSA object (if used a
    Crypt::OpenSSL::RSA object will be converted).

 set_iat

    If true (false by default), then the iat claim will be set to the value
    of "now" during "encode".

 jwks

    An arrayref of JWK objects used by decode to verify the input token
    when matching with the JWTs kid field.

        my $jwks = Mojo::UserAgent->new->get('https://example.com/oidc/jwks.json')->result->json('/keys');
        my $jwt = Mojo::JWT->new(jwks => $jwks);
        $jwk->decode($token);

METHODS

    Mojo::JWT inherits all of the methods from Mojo::Base and implements
    the following new ones.

 add_jwkset

        my $jwkset = Mojo::UserAgent->new->get('https://example.com/oidc/jwks.json')->result->json;
        my $jwt = Mojo::JWT->new->add_jwkset($jwksset);
        $jwk->decode($token);

    Helper for appending a jwkset to the "jwks". Accepts a hashref with a
    keys field that is an arrayref of jwks and also an arrayref directly.
    Appends the JWKs to "jwks". Returns the instance.

 decode

      my $claims = $jwt->decode($token);
    
      my $peek = sub { my ($jwt, $claims) = @_; ... };
      my $claims = $jwt->decode($token, $peek);

    Decode and parse a JSON Web Token string and return the claims hashref.
    Calling this function immediately sets the "token" to the passed in
    token. It also sets "algorithm" to undef and unsets "claims", "expires"
    and "not_before". These values are then set as part of the parsing
    process.

    Parsing occurs as follows

      * The "algorithm" is extracted from the header and set, if not
      present or permissible an exception is thrown

      * Any JWKs in /jwks are checked against the headers and if one is
      found then it is set in "public" or "secret" as appropriate to the
      "algorithm"

      * If a $peek callback is provided, it is called with the instance and
      claims as arguments

      * The signature is verified or an exception is thrown

      * The timing claims ("expires" and "not_before"), if present, are
      evaluated, failures result in exceptions. On success the values are
      set in the relevant attributes

      * The "claims" attribute is set and the claims are returned.

    Note that when the $peek callback is invoked, the claims have not yet
    been verified. This callback is most likely to be used to inspect the
    iss or issuer claim to determine a secret or key for decoding. The
    return value is ignored, changes should be made to the instances
    attributes directly. Since the "algorithm" has already been parsed, it
    is available via the instance attribute as well.

 encode

      my $token = $jwt->encode;

    Encode the data expressed in the instance attributes: "algorithm",
    "claims", "expires", "not_before". Note that if the timing attributes
    are given, they override existing keys in the "claims". Calling encode
    immediately clears the "token" and upon completion sets it to the
    result as well as returning it.

    Note also that due to Perl's hash randomization, repeated encoding is
    not guaranteed to result in the same encoded string. However any
    encoded string will survive an encode/decode roundtrip.

 header

      my $header = $jwt->header;

    Returns a hash reference representing the JWT header, constructed from
    instance attributes (see "algorithm").

 now

      my $time = $jwt->now;

    Returns the current time, currently implemented as the core time
    function.

 sign_hmac

      my $signature = $jwt->sign_hmac($size, $payload);

    Returns the HMAC SHA signature for the given size and payload. The
    "secret" attribute is used as the symmetric key. The result is not yet
    base64 encoded. This method is provided mostly for the purposes of
    subclassing.

 sign_rsa

      my $signature = $jwt->sign_rsa($size, $payload);

    Returns the RSA signature for the given size and payload. The "secret"
    attribute is used as the private key. The result is not yet base64
    encoded. This method is provided mostly for the purposes of
    subclassing.

 token

    The most recently encoded or decoded token. Note that any attribute
    modifications are not taken into account until "encode" is called
    again.

 verify_rsa

      my $bool = $jwt->verify_rsa($size, $payload, $signature);

    Returns true if the given RSA size algorithm validates the given
    payload and signature. The "public" attribute is used as the public
    key. This method is provided mostly for the purposes of subclassing.

SEE ALSO

    Acme::JWT

    JSON::WebToken

    http://jwt.io/

SOURCE REPOSITORY

    http://github.com/jberger/Mojo-JWT

AUTHOR

    Joel Berger, <joel.a.berger@gmail.com>

CONTRIBUTORS

    Christopher Raa (mishanti1)

    Cameron Daniel (ccakes)

COPYRIGHT AND LICENSE

    Copyright (C) 2015 by "AUTHOR" and "CONTRIBTORS".

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.