1Mojo::JWT(3pm) User Contributed Perl Documentation Mojo::JWT(3pm)
2
6 Mojo::JWT - JSON Web Token the Mojo way
7
9 my $jwt = Mojo::JWT->new(claims => {...}, secret => 's3cr3t')->encode;
10 my $claims = Mojo::JWT->new(secret => 's3cr3t')->decode($jwt);
11
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 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
26 Mojo::JWT inherits all of the attributes from Mojo::Base and implements
27 the following new ones.
28 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 "none" is an acceptable encoding algorithm, however for it to be used
35 to decode, "allow_none" must be set.
36 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 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 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 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 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 public
66 The public key to be used in decoding an asymmetrically signed JWT (eg.
67 RSA).
68 secret
70 The symmetric secret (eg. HMAC) or else the private key used in
71 encoding an asymmetrically signed JWT (eg. RSA).
72 set_iat
74 If true (false by default), then the "iat" claim will be set to the
75 value of "now" during "encode".
76 jwks
78 An arrayref of JWK objects used by "decode" to verify the input token
79 when matching with the JWTs "kid" field.
80 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
86 Mojo::JWT inherits all of the methods from Mojo::Base and implements
87 the following new ones.
88 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 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 decode
99 my $claims = $jwt->decode($token);
100 my $peek = sub { my ($jwt, $claims) = @_; ... };
102 my $claims = $jwt->decode($token, $peek);
103 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 Parsing occurs as follows
111 • The "algorithm" is extracted from the header and set, if not
113 present or permissible an exception is thrown
114 • 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 • If a $peek callback is provided, it is called with the instance and
120 claims as arguments
121 • The signature is verified or an exception is thrown
123 • 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 • The "claims" attribute is set and the claims are returned.
129 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 encode
138 my $token = $jwt->encode;
139 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 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 header
151 my $header = $jwt->header;
152 Returns a hash reference representing the JWT header, constructed from
154 instance attributes (see "algorithm").
155 now
157 my $time = $jwt->now;
158 Returns the current time, currently implemented as the core "time"
160 function.
161 sign_hmac
163 my $signature = $jwt->sign_hmac($size, $payload);
164 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 sign_rsa
171 my $signature = $jwt->sign_rsa($size, $payload);
172 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 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 verify_rsa
184 my $bool = $jwt->verify_rsa($size, $payload, $signature);
185 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
191 Acme::JWT
192 JSON::WebToken
193 <http://jwt.io/>
194
196 <http://github.com/jberger/Mojo-JWT>
197
199 Joel Berger, <joel.a.berger@gmail.com>
200
202 Christopher Raa (mishanti1)
203 Cameron Daniel (ccakes)
205
207 Copyright (C) 2015 by "AUTHOR" and "CONTRIBTORS".
208 This library is free software; you can redistribute it and/or modify it
210 under the same terms as Perl itself.
211perl v5.38.0 2023-07-20 Mojo::JWT(3pm)