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
77   jwks
78       An arrayref of JWK objects used by "decode" to verify the input token
79       when matching with the JWTs "kid" field.
80
81           my $jwks = Mojo::UserAgent->new->get('https://example.com/oidc/jwks.json')->result->json('/keys');
82           my $jwt = Mojo::JWT->new(jwks => $jwks);
83           $jwk->decode($token);
84

METHODS

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

SEE ALSO

191       Acme::JWT
192       JSON::WebToken
193       <http://jwt.io/>
194

SOURCE REPOSITORY

196       <http://github.com/jberger/Mojo-JWT>
197

AUTHOR

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

CONTRIBUTORS

202       Christopher Raa (mishanti1)
203
204       Cameron Daniel (ccakes)
205
207       Copyright (C) 2015 by "AUTHOR" and "CONTRIBTORS".
208
209       This library is free software; you can redistribute it and/or modify it
210       under the same terms as Perl itself.
211
212
213
214perl v5.38.0                      2023-07-20                    Mojo::JWT(3pm)
Impressum