feat: add clockSkewSeconds (firebase#714)

* feat: add clockSkewSeconds per feedback in firebase#625 (comment) adds unit and integration tests as well. unit tests and lint pass. * fix: test * chore: version bump for testing * chore: address CR * fix:lint * chore: address CR * chore: remove test * fix: remove more tests * chore: address CR

Author: stillmatic

firebase_admin/__init__.py

@@ -50,8 +50,9 @@ def initialize_app(credential=None, options=None, name=_DEFAULT_APP_NAME):
  Google Application Default Credentials are used.
  options: A dictionary of configuration options (optional). Supported options include
  ``databaseURL``, ``storageBucket``, ``projectId``, ``databaseAuthVariableOverride``,
- ``serviceAccountId`` and ``httpTimeout``. If ``httpTimeout`` is not set, the SDK
- uses a default timeout of 120 seconds.
+ ``serviceAccountId`` and ``httpTimeout``. If ``httpTimeout`` is not set, the SDK uses
+ a default timeout of 120 seconds.
+
  name: Name of the app (optional).
  Returns:
  App: A newly initialized instance of App.

firebase_admin/_auth_client.py

@@ -92,7 +92,7 @@ def create_custom_token(self, uid, developer_claims=None):
  return self._token_generator.create_custom_token(
  uid, developer_claims, tenant_id=self.tenant_id)
 
- def verify_id_token(self, id_token, check_revoked=False):
+ def verify_id_token(self, id_token, check_revoked=False, clock_skew_seconds=0):
  """Verifies the signature and data for the provided JWT.
 
  Accepts a signed token string, verifies that it is current, was issued
@@ -102,6 +102,8 @@ def verify_id_token(self, id_token, check_revoked=False):
  id_token: A string of the encoded JWT.
  check_revoked: Boolean, If true, checks whether the token has been revoked or
  the user disabled (optional).
+ clock_skew_seconds: The number of seconds to tolerate when checking the token.
+ Must be between 0-60. Defaults to 0.
 
  Returns:
  dict: A dictionary of key-value pairs parsed from the decoded JWT.
@@ -124,7 +126,7 @@ def verify_id_token(self, id_token, check_revoked=False):
  raise ValueError('Illegal check_revoked argument. Argument must be of type '
  ' bool, but given "{0}".'.format(type(check_revoked)))
 
- verified_claims = self._token_verifier.verify_id_token(id_token)
+ verified_claims = self._token_verifier.verify_id_token(id_token, clock_skew_seconds)
  if self.tenant_id:
  token_tenant_id = verified_claims.get('firebase', {}).get('tenant')
  if self.tenant_id != token_tenant_id:

firebase_admin/_token_gen.py

@@ -289,11 +289,11 @@ def __init__(self, app):
  invalid_token_error=InvalidSessionCookieError,
  expired_token_error=ExpiredSessionCookieError)
 
- def verify_id_token(self, id_token):
- return self.id_token_verifier.verify(id_token, self.request)
+ def verify_id_token(self, id_token, clock_skew_seconds=0):
+ return self.id_token_verifier.verify(id_token, self.request, clock_skew_seconds)
 
- def verify_session_cookie(self, cookie):
- return self.cookie_verifier.verify(cookie, self.request)
+ def verify_session_cookie(self, cookie, clock_skew_seconds=0):
+ return self.cookie_verifier.verify(cookie, self.request, clock_skew_seconds)
 
 
 class _JWTVerifier:
@@ -313,7 +313,7 @@ def __init__(self, **kwargs):
  self._invalid_token_error = kwargs.pop('invalid_token_error')
  self._expired_token_error = kwargs.pop('expired_token_error')
 
- def verify(self, token, request):
+ def verify(self, token, request, clock_skew_seconds=0):
  """Verifies the signature and data for the provided JWT."""
  token = token.encode('utf-8') if isinstance(token, str) else token
  if not isinstance(token, bytes) or not token:
@@ -328,6 +328,11 @@ def verify(self, token, request):
  'or set your Firebase project ID as an app option. Alternatively set the '
  'GOOGLE_CLOUD_PROJECT environment variable.'.format(self.operation))
 
+ if clock_skew_seconds < 0 or clock_skew_seconds > 60:
+ raise ValueError(
+ 'Illegal clock_skew_seconds value: {0}. Must be between 0 and 60, inclusive.'
+ .format(clock_skew_seconds))
+
  header, payload = self._decode_unverified(token)
  issuer = payload.get('iss')
  audience = payload.get('aud')
@@ -393,7 +398,8 @@ def verify(self, token, request):
  token,
  request=request,
  audience=self.project_id,
- certs_url=self.cert_url)
+ certs_url=self.cert_url,
+ clock_skew_in_seconds=clock_skew_seconds)
  verified_claims['uid'] = verified_claims['sub']
  return verified_claims
  except google.auth.exceptions.TransportError as error:

firebase_admin/auth.py

@@ -191,7 +191,7 @@ def create_custom_token(uid, developer_claims=None, app=None):
  return client.create_custom_token(uid, developer_claims)
 
 
-def verify_id_token(id_token, app=None, check_revoked=False):
+def verify_id_token(id_token, app=None, check_revoked=False, clock_skew_seconds=0):
  """Verifies the signature and data for the provided JWT.
 
  Accepts a signed token string, verifies that it is current, and issued
@@ -202,7 +202,8 @@ def verify_id_token(id_token, app=None, check_revoked=False):
  app: An App instance (optional).
  check_revoked: Boolean, If true, checks whether the token has been revoked or
  the user disabled (optional).
-
+ clock_skew_seconds: The number of seconds to tolerate when checking the token.
+ Must be between 0-60. Defaults to 0.
  Returns:
  dict: A dictionary of key-value pairs parsed from the decoded JWT.
 
@@ -217,7 +218,8 @@ def verify_id_token(id_token, app=None, check_revoked=False):
  record is disabled.
  """
  client = _get_client(app)
- return client.verify_id_token(id_token, check_revoked=check_revoked)
+ return client.verify_id_token(
+ id_token, check_revoked=check_revoked, clock_skew_seconds=clock_skew_seconds)
 
 
 def create_session_cookie(id_token, expires_in, app=None):
@@ -243,7 +245,7 @@ def create_session_cookie(id_token, expires_in, app=None):
  return client._token_generator.create_session_cookie(id_token, expires_in)
 
 
-def verify_session_cookie(session_cookie, check_revoked=False, app=None):
+def verify_session_cookie(session_cookie, check_revoked=False, app=None, clock_skew_seconds=0):
  """Verifies a Firebase session cookie.
 
  Accepts a session cookie string, verifies that it is current, and issued
@@ -254,6 +256,7 @@ def verify_session_cookie(session_cookie, check_revoked=False, app=None):
  check_revoked: Boolean, if true, checks whether the cookie has been revoked or the
  user disabled (optional).
  app: An App instance (optional).
+ clock_skew_seconds: The number of seconds to tolerate when checking the cookie.
 
  Returns:
  dict: A dictionary of key-value pairs parsed from the decoded JWT.
@@ -270,7 +273,8 @@ def verify_session_cookie(session_cookie, check_revoked=False, app=None):
  """
  client = _get_client(app)
  # pylint: disable=protected-access
- verified_claims = client._token_verifier.verify_session_cookie(session_cookie)
+ verified_claims = client._token_verifier.verify_session_cookie(
+ session_cookie, clock_skew_seconds)
  if check_revoked:
  client._check_jwt_revoked_or_disabled(
  verified_claims, RevokedSessionCookieError, 'session cookie')

integration/test_auth.py

@@ -617,6 +617,7 @@ def test_verify_session_cookie_revoked(new_user, api_key):
  claims = auth.verify_session_cookie(session_cookie, check_revoked=True)
  assert claims['iat'] * 1000 >= user.tokens_valid_after_timestamp
 
+
 def test_verify_session_cookie_disabled(new_user, api_key):
  custom_token = auth.create_custom_token(new_user.uid)
  id_token = _sign_in(custom_token, api_key)

tests/test_token_gen.py

@@ -440,14 +440,19 @@ class TestVerifyIdToken:
  'iat': int(time.time()) - 10000,
  'exp': int(time.time()) - 3600
  }),
+ 'ExpiredTokenShort': _get_id_token({
+ 'iat': int(time.time()) - 10000,
+ 'exp': int(time.time()) - 30
+ }),
  'BadFormatToken': 'foobar'
  }
 
  tokens_accepted_in_emulator = [
  'NoKid',
  'WrongKid',
  'FutureToken',
- 'ExpiredToken'
+ 'ExpiredToken',
+ 'ExpiredTokenShort',
  ]
 
  def _assert_valid_token(self, id_token, app):
@@ -555,6 +560,20 @@ def test_expired_token(self, user_mgt_app):
  assert excinfo.value.cause is not None
  assert excinfo.value.http_response is None
 
+ def test_expired_token_with_tolerance(self, user_mgt_app):
+ _overwrite_cert_request(user_mgt_app, MOCK_REQUEST)
+ id_token = self.invalid_tokens['ExpiredTokenShort']
+ if _is_emulated():
+ self._assert_valid_token(id_token, user_mgt_app)
+ return
+ claims = auth.verify_id_token(id_token, app=user_mgt_app,
+ clock_skew_seconds=60)
+ assert claims['admin'] is True
+ assert claims['uid'] == claims['sub']
+ with pytest.raises(auth.ExpiredIdTokenError):
+ auth.verify_id_token(id_token, app=user_mgt_app,
+ clock_skew_seconds=20)
+
  def test_project_id_option(self):
  app = firebase_admin.initialize_app(
  testutils.MockCredential(), options={'projectId': 'mock-project-id'}, name='myApp')
@@ -619,6 +638,10 @@ class TestVerifySessionCookie:
  'iat': int(time.time()) - 10000,
  'exp': int(time.time()) - 3600
  }),
+ 'ExpiredCookieShort': _get_session_cookie({
+ 'iat': int(time.time()) - 10000,
+ 'exp': int(time.time()) - 30
+ }),
  'BadFormatCookie': 'foobar',
  'IDToken': TEST_ID_TOKEN,
  }
@@ -627,7 +650,8 @@ class TestVerifySessionCookie:
  'NoKid',
  'WrongKid',
  'FutureCookie',
- 'ExpiredCookie'
+ 'ExpiredCookie',
+ 'ExpiredCookieShort',
  ]
 
  def _assert_valid_cookie(self, cookie, app, check_revoked=False):
@@ -715,6 +739,20 @@ def test_expired_cookie(self, user_mgt_app):
  assert excinfo.value.cause is not None
  assert excinfo.value.http_response is None
 
+ def test_expired_cookie_with_tolerance(self, user_mgt_app):
+ _overwrite_cert_request(user_mgt_app, MOCK_REQUEST)
+ cookie = self.invalid_cookies['ExpiredCookieShort']
+ if _is_emulated():
+ self._assert_valid_cookie(cookie, user_mgt_app)
+ return
+ claims = auth.verify_session_cookie(cookie, app=user_mgt_app, check_revoked=False,
+ clock_skew_seconds=59)
+ assert claims['admin'] is True
+ assert claims['uid'] == claims['sub']
+ with pytest.raises(auth.ExpiredSessionCookieError):
+ auth.verify_session_cookie(cookie, app=user_mgt_app, check_revoked=False,
+ clock_skew_seconds=29)
+
  def test_project_id_option(self):
  app = firebase_admin.initialize_app(
  testutils.MockCredential(), options={'projectId': 'mock-project-id'}, name='myApp')