Payloads¶
As discussed, JWTs have a payload that is essentially a key/value store of information.
With Sanic JWT, there are three main uses of the payload:
- passing claims (See What is a JWT? for more information)
- passing scope (See Scopes for more information)
- passing arbitrary information to the client
Built in Claims¶
Sanic JWT ships with the capability to add, and later verify, five standard claims: exp
, nbf
, iat
, iss
, and aud
.
Expires - exp
¶
Warning
It is possible to disable token expiration. Do NOT do this unless you know what you are doing and why you are doing it.
Initialize(app, verify_exp=False)
Okay, great. You know what you are doing. It is still revommended that you NOT do this. Are you sure you know what you are doing?
Audience - aud
¶
claim_aud
to a str
Initialize(app, claim_aud='my_client_domain.com')
Issued at - iat
¶
claim_iat
to True
Initialize(app, claim_iat=True)
Issuer - iss
¶
claim_iss
to a str
Initialize(app, claim_iss='my_server_domain.com')
Not before - NBF
¶
claim_nbf
to True
, and claim_nbf_delta
to an offset in secondsInitialize(app, claim_nbf=True, claim_nbf_delta=(60 * 3))
Payload Handlers¶
As discussed, there are a few handlers on the Initialize
instance that can be used to modify the payload.
Adding Scopes¶
add_scopes_to_payload
@scoped
decorator, then you will need a way to inject the payload
with the user’s scopes. It should return either a single scope, or a list of scopes. Read about scopes for more information.str
or a list
of str
async def my_scope_extender(user, *args, **kwargs):
return user.scopes
Initialize(app, add_scopes_to_payload=my_scope_extender)
Note
The return of the authenticate
method will be injected into this handler as user
for your convenience.
Extending the payload¶
extend_payload
dict
def my_foo_bar_payload_extender(payload, *args, **kwargs):
payload.update({
'foo': 'bar'
})
return payload
Initialize(app, extend_payload=my_foo_bar_payload_extender)
Token signing¶
JWTs need to be digitally signed to allow for cryptographically verifying that an access token was generated by your application.
secret = 'XXXXXXXXXXXXXXXXXXXXXXXX'
Initialize(
app,
secret=mysecret)
There are several hashing algorithms that can be used to accomplish this. Check out the Configuration page to see which algorithms are supported, and read this for more information.
If you decide to use an RSA or an EC algorithm, then you must provide Sanic JWT with both a public key and a private key to handle the encoding and decoding of the tokens.
from pathlib import Path
public_ec_key = Path('/path') / 'to' / 'my-ec-public-key.pem'
private_ec_key = Path('/path') / 'to' / 'my-ec-private-key.pem'
Initialize(
app,
public_key=public_ec_key,
private_key=private_ec_key,
algorithm='ES256')