Improve Docs for jwt.decode with JWK

[topher96]

https://github.com/mpdavis/python-jose/blob/master/jose/jwt.py#L70v

def decode(token, key, algorithms=None, options=None, audience=None,
issuer=None, subject=None, access_token=None):
"""Verifies a JWT string's signature and validates reserved claims.
...
key (str): A key to attempt to verify the payload with.

It should mention that this key can be a string containing a JSON Web Key - because the example only shows a static password in that field, so its not obvious that it can do more.

https://github.com/mpdavis/python-jose/blob/master/jose/jwt.py#L110

Also consider showing an example where a JSON web key is used.

[bxm156]

+1. It can also be a dictionary with a 'keys' field. This matches the json output of what Auth0 provides me at: https://< auth0 domain>.auth0.com/.well-known/jwks.json

So I can just parse that json into a dict and pass it directly as 'key' into decode. TIL.

[GlennS]

At the moment, the documentation says:

A key to attempt to verify the payload with. Can be individual JWK or JWK set.

This really isn't enough information to go on.

The code mentions rfc7517, and the documentation probably should too.

For an example of why the current documentation is unhelpful, here's the wrong code that I initially wrote, based on what I thought the documentation was telling me to do:

keys = requests.get(
    'https://cognito-idp.%s.amazonaws.com/%s/.well-known/jwks.json' % (AWS_REGION, userPoolId)
).json()['keys']

return set([jwk.construct(key) for key in keys if key['alg'] == 256])

This should actually be:

keys = requests.get(
    'https://cognito-idp.%s.amazonaws.com/%s/.well-known/jwks.json' % (AWS_REGION, userPoolId)
).json()['keys']

return {
    'keys': [ key for key in keys if key['alg'] == RS256 ]
}

[erny]

PR #198