1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
|
API Reference
=============
.. module:: jwt
.. function:: encode(payload, key, algorithm="HS256", headers=None, json_encoder=None)
Encode the ``payload`` as JSON Web Token.
:param dict payload: JWT claims, e.g. ``dict(iss=..., aud=..., sub=...)``
:param key: a key suitable for the chosen algorithm:
* for **asymmetric algorithms**: PEM-formatted private key, a multiline string
* for **symmetric algorithms**: plain string, sufficiently long for security
:type key: str or bytes or jwt.PyJWK
:param str algorithm: algorithm to sign the token with, e.g. ``"ES256"``.
If ``headers`` includes ``alg``, it will be preferred to this parameter.
If ``key`` is a :class:`jwt.PyJWK` object, by default the key algorithm will be used.
:param dict headers: additional JWT header fields, e.g. ``dict(kid="my-key-id")``.
:param json.JSONEncoder json_encoder: custom JSON encoder for ``payload`` and ``headers``
:rtype: str
:returns: a JSON Web Token
.. function:: decode(jwt, key="", algorithms=None, options=None, audience=None, issuer=None, leeway=0)
Verify the ``jwt`` token signature and return the token claims.
:param str jwt: the token to be decoded
:param key: the key suitable for the allowed algorithm
:type key: str or bytes or jwt.PyJWK
:param list algorithms: allowed algorithms, e.g. ``["ES256"]``
If ``key`` is a :class:`jwt.PyJWK` object, allowed algorithms will default to the key algorithm.
.. warning::
Do **not** compute the ``algorithms`` parameter based on
the ``alg`` from the token itself, or on any other data
that an attacker may be able to influence, as that might
expose you to various vulnerabilities (see `RFC 8725 §2.1
<https://www.rfc-editor.org/rfc/rfc8725.html#section-2.1>`_). Instead,
either hard-code a fixed value for ``algorithms``, or
configure it in the same place you configure the
``key``. Make sure not to mix symmetric and asymmetric
algorithms that interpret the ``key`` in different ways
(e.g. HS\* and RS\*).
:param dict options: extended decoding and validation options
* ``verify_signature=True`` verify the JWT cryptographic signature
* ``require=[]`` list of claims that must be present.
Example: ``require=["exp", "iat", "nbf"]``.
**Only verifies that the claims exists**. Does not verify that the claims are valid.
* ``verify_aud=verify_signature`` check that ``aud`` (audience) claim matches ``audience``
* ``verify_iss=verify_signature`` check that ``iss`` (issuer) claim matches ``issuer``
* ``verify_exp=verify_signature`` check that ``exp`` (expiration) claim value is in the future
* ``verify_iat=verify_signature`` check that ``iat`` (issued at) claim value is an integer
* ``verify_nbf=verify_signature`` check that ``nbf`` (not before) claim value is in the past
* ``strict_aud=False`` check that the ``aud`` claim is a single value (not a list), and matches ``audience`` exactly
.. warning::
``exp``, ``iat`` and ``nbf`` will only be verified if present.
Please pass respective value to ``require`` if you want to make
sure that they are always present (and therefore always verified
if ``verify_exp``, ``verify_iat``, and ``verify_nbf`` respectively
is set to ``True``).
:param audience: optional, the value for ``verify_aud`` check
:type audience: Union[str, Iterable]
:param str issuer: optional, the value for ``verify_iss`` check
:param float leeway: a time margin in seconds for the expiration check
:rtype: dict
:returns: the JWT claims
.. class:: PyJWK
A class that represents a `JSON Web Key <https://www.rfc-editor.org/rfc/rfc7517>`_.
.. method:: __init__(self, jwk_data, algorithm=None)
:param dict data: The decoded JWK data.
:param algorithm: The key algorithm. If not specific, the key's ``alg`` will be used.
:type algorithm: str or None
.. staticmethod:: from_json(data, algorithm=None)
:param str data: The JWK data, as a JSON string.
:param algorithm: The key algorithm. If not specific, the key's ``alg`` will be used.
:type algorithm: str or None
:returntype: jwt.PyJWK
Create a :class:`jwt.PyJWK` object from a JSON string.
.. property:: algorithm_name
:type: str
The name of the algorithm used by the key.
.. property:: Algorithm
The ``Algorithm`` class associated with the key.
.. property:: key_type
:type: str or None
The ``kty`` property from the JWK.
.. property:: key_id
:type: str or None
The ``kid`` property from the JWK.
.. property:: public_key_use
:type: str or None
The ``use`` property from the JWK.
.. module:: jwt.api_jwt
.. function:: decode_complete(jwt, key="", algorithms=None, options=None, audience=None, issuer=None, leeway=0)
Identical to ``jwt.decode`` except for return value which is a dictionary containing the token header (JOSE Header),
the token payload (JWT Payload), and token signature (JWT Signature) on the keys "header", "payload",
and "signature" respectively.
:param str jwt: the token to be decoded
:param str key: the key suitable for the allowed algorithm
:param list algorithms: allowed algorithms, e.g. ``["ES256"]``
.. warning::
Do **not** compute the ``algorithms`` parameter based on
the ``alg`` from the token itself, or on any other data
that an attacker may be able to influence, as that might
expose you to various vulnerabilities (see `RFC 8725 §2.1
<https://www.rfc-editor.org/rfc/rfc8725.html#section-2.1>`_). Instead,
either hard-code a fixed value for ``algorithms``, or
configure it in the same place you configure the
``key``. Make sure not to mix symmetric and asymmetric
algorithms that interpret the ``key`` in different ways
(e.g. HS\* and RS\*).
:param dict options: extended decoding and validation options
* ``verify_signature=True`` verify the JWT cryptographic signature
* ``require=[]`` list of claims that must be present.
Example: ``require=["exp", "iat", "nbf"]``.
**Only verifies that the claims exists**. Does not verify that the claims are valid.
* ``verify_aud=verify_signature`` check that ``aud`` (audience) claim matches ``audience``
* ``verify_iss=verify_signature`` check that ``iss`` (issuer) claim matches ``issuer``
* ``verify_exp=verify_signature`` check that ``exp`` (expiration) claim value is in the future
* ``verify_iat=verify_signature`` check that ``iat`` (issued at) claim value is an integer
* ``verify_nbf=verify_signature`` check that ``nbf`` (not before) claim value is in the past
* ``strict_aud=False`` check that the ``aud`` claim is a single value (not a list), and matches ``audience`` exactly
.. warning::
``exp``, ``iat`` and ``nbf`` will only be verified if present.
Please pass respective value to ``require`` if you want to make
sure that they are always present (and therefore always verified
if ``verify_exp``, ``verify_iat``, and ``verify_nbf`` respectively
is set to ``True``).
:param Iterable audience: optional, the value for ``verify_aud`` check
:param str issuer: optional, the value for ``verify_iss`` check
:param float leeway: a time margin in seconds for the expiration check
:rtype: dict
:returns: Decoded JWT with the JOSE Header on the key ``header``, the JWS
Payload on the key ``payload``, and the JWS Signature on the key ``signature``.
.. note:: TODO: Document PyJWS class
Exceptions
----------
.. currentmodule:: jwt.exceptions
.. class:: InvalidTokenError
Base exception when ``decode()`` fails on a token
.. class:: DecodeError
Raised when a token cannot be decoded because it failed validation
.. class:: InvalidSignatureError
Raised when a token's signature doesn't match the one provided as part of
the token.
.. class:: ExpiredSignatureError
Raised when a token's ``exp`` claim indicates that it has expired
.. class:: InvalidAudienceError
Raised when a token's ``aud`` claim does not match one of the expected
audience values
.. class:: InvalidIssuerError
Raised when a token's ``iss`` claim does not match the expected issuer
.. class:: InvalidIssuedAtError
Raised when a token's ``iat`` claim is non-numeric
.. class:: ImmatureSignatureError
Raised when a token's ``nbf`` or ``iat`` claims represent a time in the future
.. class:: InvalidKeyError
Raised when the specified key is not in the proper format
.. class:: InvalidAlgorithmError
Raised when the specified algorithm is not recognized by PyJWT
.. class:: MissingRequiredClaimError
Raised when a claim that is required to be present is not contained
in the claimset
|
