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
|
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 str 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
:param str algorithm: algorithm to sign the token with, e.g. ``"ES256"``.
If ``headers`` includes ``alg``, it will be preferred to this parameter.
: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 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
.. 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: the JWT claims
.. 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
.. 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 in the future
.. class:: ImmatureSignatureError
Raised when a token's ``nbf`` claim represents 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
|
