Mojo::JWT(3pm)

1Mojo::JWT(3pm)        User Contributed Perl Documentation       Mojo::JWT(3pm)
2
3
4

NAME

6       Mojo::JWT - JSON Web Token the Mojo way
7

SYNOPSIS

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

DESCRIPTION

13       JSON Web Token is described in <https://tools.ietf.org/html/rfc7519>.
14       Mojo::JWT implements that standard with an API that should feel
15       familiar to Mojolicious users (though of course it is useful
16       elsewhere).  Indeed, JWT is much like Mojolicious::Sessions except that
17       the result is a url-safe text string rather than a cookie.
18
19       In JWT, the primary payload is called the "claims", and a few claims
20       are reserved, as seen in the IETF document.  The header and the claims
21       are signed when stringified to guard against tampering.  Note that
22       while signed, the data is not encrypted, so don't use it to send
23       secrets over clear channels.
24

ATTRIBUTES

26       Mojo::JWT inherits all of the attributes from Mojo::Base and implements
27       the following new ones.
28
29   algorithm
30       The algorithm to be used to sign a JWT during encoding or else the
31       algorithm that was used for the most recent decoding.  Defaults to
32       "HS256" until a decode is performed.
33
34       "none" is an acceptable encoding algorithm, however for it to be used
35       to decode, "allow_none" must be set.
36
37   allow_none
38       To prevent spoofing attacks, "allow_none" must be explicitly set to a
39       true value otherwise decoding a JWT which specifies the "none"
40       algorithm will result in an exception.  The default is of course false.
41
42   claims
43       The payload to be encoded or else the claims from the most recent
44       decoding.  This must be a hash reference, array references are not
45       allowed as the top-level JWT claims.
46
47   expires
48       The epoch time value after which the JWT value should not be considered
49       valid.  This value (if set and not undefined) will be used as the "exp"
50       key in the claims or was extracted from the claims during the most
51       recent decoding.
52
53   header
54       You may set your own headers when encoding the JWT bypassing a hash
55       reference to the "header" attribute. Please note that there are two
56       default headers set. alg is set to the value of "algorithm" or 'HS256'
57       and typ is set to 'JWT'. These cannot be overridden.
58
59   not_before
60       The epoch time value before which the JWT value should not be
61       considered valid.  This value (if set and not undefined) will be used
62       as the "nbf" key in the claims or was extracted from the claims during
63       the most recent decoding.
64
65   public
66       The public key to be used in decoding an asymmetrically signed JWT (eg.
67       RSA).
68
69   secret
70       The symmetric secret (eg. HMAC) or else the private key used in
71       encoding an asymmetrically signed JWT (eg. RSA).
72
73   set_iat
74       If true (false by default), then the "iat" claim will be set to the
75       value of "now" during "encode".
76

METHODS

78       Mojo::JWT inherits all of the methods from Mojo::Base and implements
79       the following new ones.
80
81   decode
82         my $claims = $jwt->decode($token);
83
84         my $peek = sub { my ($jwt, $claims) = @_; ... };
85         my $claims = $jwt->decode($token, $peek);
86
87       Decode and parse a JSON Web Token string and return the claims hashref.
88       Calling this function immediately sets the "token" to the passed in
89       token.  It also sets "algorithm" to "undef" and unsets "claims",
90       "expires" and "not_before".  These values are then set as part of the
91       parsing process.
92
93       Parsing occurs as follows
94
95       ·   The "algorithm" is extracted from the header and set, if not
96           present or permissible an exception is thrown
97
98       ·   If a $peek callback is provided, it is called with the instance and
99           claims as arguments
100
101       ·   The signature is verified or an exception is thrown
102
103       ·   The timing claims ("expires" and "not_before"), if present, are
104           evaluated, failures result in exceptions. On success the values are
105           set in the relevant attributes
106
107       ·   The "claims" attribute is set and the claims are returned.
108
109       Note that when the $peek callback is invoked, the claims have not yet
110       been verified.  This callback is most likely to be used to inspect the
111       "iss" or issuer claim to determine a secret or key for decoding.  The
112       return value is ignored, changes should be made to the instances
113       attributes directly.  Since the "algorithm" has already been parsed, it
114       is available via the instance attribute as well.
115
116   encode
117         my $token = $jwt->encode;
118
119       Encode the data expressed in the instance attributes: "algorithm",
120       "claims", "expires", "not_before".  Note that if the timing attributes
121       are given, they override existing keys in the "claims".  Calling
122       "encode" immediately clears the "token" and upon completion sets it to
123       the result as well as returning it.
124
125       Note also that due to Perl's hash randomization, repeated encoding is
126       not guaranteed to result in the same encoded string.  However any
127       encoded string will survive an encode/decode roundtrip.
128
129   header
130         my $header = $jwt->header;
131
132       Returns a hash reference representing the JWT header, constructed from
133       instance attributes (see "algorithm").
134
135   now
136         my $time = $jwt->now;
137
138       Returns the current time, currently implemented as the core "time"
139       function.
140
141   sign_hmac
142         my $signature = $jwt->sign_hmac($size, $payload);
143
144       Returns the HMAC SHA signature for the given size and payload.  The
145       "secret" attribute is used as the symmetric key.  The result is not yet
146       base64 encoded.  This method is provided mostly for the purposes of
147       subclassing.
148
149   sign_rsa
150         my $signature = $jwt->sign_rsa($size, $payload);
151
152       Returns the RSA signature for the given size and payload.  The "secret"
153       attribute is used as the private key.  The result is not yet base64
154       encoded.  This method is provided mostly for the purposes of
155       subclassing.
156
157   token
158       The most recently encoded or decoded token.  Note that any attribute
159       modifications are not taken into account until "encode" is called
160       again.
161
162   verify_rsa
163         my $bool = $jwt->verify_rsa($size, $payload, $signature);
164
165       Returns true if the given RSA size algorithm validates the given
166       payload and signature.  The "public" attribute is used as the public
167       key.  This method is provided mostly for the purposes of subclassing.
168

SOURCE REPOSITORY

175       <http://github.com/jberger/Mojo-JWT>
176

AUTHOR

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

CONTRIBUTORS

181       Christopher Raa (mishanti1)
182

COPYRIGHT AND LICENSE

184       Copyright (C) 2015 by "AUTHOR" and "CONTRIBTORS".
185
186       This library is free software; you can redistribute it and/or modify it
187       under the same terms as Perl itself.
188
189
190
191perl v5.32.0                      2020-07-28                    Mojo::JWT(3pm)