pyJWT : encode /decode / registerd claim names

install

$ pip install pyjwt

install pyjwt로 설치하자. jwt를 사용하기 위해 설치하는 pyjwt의 공식문서는 https://pyjwt.readthedocs.io/en/stable/ 이 주소이다.

 

token 생성

jwt를 생성하려면 jwt.encode() 함수를 사용하자. 필요한 parameter는 3개이다. 'payload', 'key', 'algorithm'

PARAMETER_NAME	설명
payload	jwt 안에 포함시킬 내용을 뜻한다.
key	jwt를 생성하는 필요한 암호화 키를 뜻한다.
algorithm	jwt를 생성하는 어떤 암호 알고리즘을 적용할것인지를 뜻한다.

import jwt

token = jwt.encode(
    payload={"key1": "value1"},
    key='abcd',
    algorithm='HS256'
)
print(token)

# OutPut
# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkxIjoidmFsdWUxIn0.7XQOq3HJVlOFd-tEIJpckestLaTdPRJJoPHNEP95zaQ

사용방법 자체가 워낙간단해서 encode하는데 필요한 무언가를 부가적으로 설명할게 없다. 

 

 

token 복호화

jwt.encode를 통해서 나온 token을 다시 복호화 시키려면 jwt.decode()를 사용하면된다. decode를 할 때도 paramter는 똑같이 3개이다. 

PARAMETER	설명
jwt	jwt.encode()를 통해 나온 값이다.
key	jwt.encode()를 할 때 사용했던 암호화 키이다.
algorithms	decode에 사용할 암호화 알고리즘이다.

jwt.decode(
    jwt=token,
    key='abcd',
    algorithms='HS256'
)

# OutPut
# {'key1': 'value1'}

 

Registered Claim Names

pyjwt에서는 payload 안에 "registered claim names"라고 해서 이미 등록된 이름들이 존재한다. 즉 간단히 말해서 payload안에서 특정 "키"들을 사용할 때는 지정된 동작들이 일어난다. 어렵게 생각할 필요는 없어보이며 대체로 token의 시간에 관련되서 제어할 수 있게 미리 제공된 기능정도로 이해하면 될 듯하다. 

 

추가적으로 해당 키들이 어떤 Exception을 일으킬 수 있는지도 같이 참고하면 token을 처리하는데 유용하다.

 

exp, Expiration Time

payload 안에 "exp"를 지정한 토큰의 만료  시간을 지정할 수 있다. 예를 들어 payload를 다음과 같이 설정했다고 가정해보자.

import jwt
import datetime

jwt.encode(
    payload={
        "key1": "value1",
        "exp" : datetime.datetime.utcnow() + datetime.timedelta(seconds=1)
    },
    key='abcd',
    algorithm='HS256'
)

"exp"에 지정된 시간이 utc 기준으로 1초뒤이다. 이는 jwt.encode()를 수행한뒤 1초뒤 jwt.decode()를 수행하면 Error가 일어난다.

import jwt
import datetime

token = jwt.encode(
    payload={
        "key1": "value1",
        "exp": datetime.datetime.utcnow() + datetime.timedelta(seconds=1)
    },
    key='abcd',
    algorithm='HS256'
)

import time

time.sleep(1)
decode_token = jwt.decode(token, 'abcd', algorithms='HS256')

이를 실행하면 다음과 같이 ExpireSignatureError를 이용해 토큰이 만료되었다고 알려준다.

jwt.exceptions.ExpiredSignatureError: Signature has expired

 

nbf, Not Before

payload 안에 "nbf"를 지정하면 해당 토큰은 nbf 이전 시간에는 사용하지 못하게된다. 즉 미래 어느 시점부터 사용가능한 토큰을 만들 떄 유용하다.

import jwt
import datetime

token = jwt.encode(
    payload={
        "key1": "value1",
        "nbf": datetime.datetime.utcnow() + datetime.timedelta(seconds=5)
    },
    key='abcd',
    algorithm='HS256'
)

위 예제에서는 token이 utc 기준이며 현재 시간 뒤 5초뒤에 사용이 가능함을 뜻한다. 만약 5초전에 사용하려고 decode를 시도하면 다음과 같은 에러가 일어난다.

jwt.exceptions.ImmatureSignatureError: The token is not yet valid (nbf)

 

iss, Issuer Claim

payload 안에 'iss'를 지정하면 해당 토큰을 발행한 사람이 누구인지를 뜻한다.

import jwt

token = jwt.encode(
    payload={
        "key1": "value1",
        "iss": "jako"
    },
    key='abcd',
    algorithm='HS256'
)

iss를 decode할 때 발생할 수 있는 시나리오는 암호화 키가 틀린 경우이다.

import jwt

token = jwt.encode(
    payload={
        "key1": "value1",
        "iss": "jako"
    },
    key='abcd',
    algorithm='HS256'
)

decode_token = jwt.decode(token, 'abce', algorithms='HS256')

encode하는데 사용한 key와 decode하는데 사용된 key가 다르다는데 주의하자

jwt.exceptions.InvalidSignatureError: Signature verification failed

 

aud, Audience

payload 안에 "aud"가 지정된 경우 이는 "토큰 발급의 대상"이 누구인지를 뜻한다. "대상"이라고 하니 추상적인 개념이 얽혀있지만 대체로 "시스템"을 의미한다.

import jwt

token = jwt.encode(
    payload={
        "key1": "value1",
        "aud": "jako:api"
    },
    key='abcd',
    algorithm='HS256'
)

decode할 때는 audience 를 지정해줘야한다.

decode_token = jwt.decode(token, 'abcd', audience="jako:api", algorithms='HS256')

audience를 주지 않으면 다음과 같은 에러가 발생한다.

jwt.exceptions.InvalidAudienceError: Invalid audience

 

iat, Issued At

iat는 토큰이 발급된 시간을 나타낸다. "발급된 시간"이기 때문에 유추할 수 있듯이 토큰이 언제 생성되었는지를 나타낸다.

import jwt
import datetime

jwt.encode(
    payload={
        "key1": "value1",
        "iat": datetime.datetime.utcnow()
    },
    key='abcd',
    algorithm='HS256'
)

iat는 decode할 때 특정 Exception을 일으키진 않는다. 허나 토큰의 유효성 검증 로직에서 iat를 이용하여 처리할 때는 주의해야한다. 이는 특정 로직에 의해 검증하는 과정에서 발생시키는 exception을 특별히 지정해서 사용할 수 있다라 해석할 수 있다.

 

정리

지금까지 registered claim names을 간단히 정리하면 다음과 같다.

claim	뜻	exception
exp, expiration time	토큰의 만료시간	jwt.exceptions.ExpiredSignatureError: Signature has expired
nbf, not before	토큰의 사용시점	jwt.exceptions.ImmatureSignatureError: The token is not yet valid (nbf)
iss, issued at	토큰을 발급한 주체	jwt.exceptions.InvalidSignatureError: Signature verification failed
aud, audience	토큰의 사용주체	jwt.exceptions.InvalidAudienceError: Invalid audience
iat, issued at	토큰이 발급된 시간