Session Management API (#147)

* Moved token generation/validation code to new helper module

* Basic session cookie support (without tests)

* Separated token generation and verification into two classes

* Added unit tests for session management

* Fixing a lint error

* Added integration tests

* Handling article in error messages

* Fixed a lint error

* Updated changelog

Author: hiranya911

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Unreleased
 
+- [added] A new `create_session_cookie()` method for creating a long-lived
+  session cookie given a valid ID token.
+- [added] A new `verify_session_cookie()` method for verifying a given
+  cookie string is valid.
 - [added] Added the `mutable_content` optional field to the `messaging.Aps`
   type.
 - [added] Added support for specifying arbitrary custom key-value

firebase_admin/_token_gen.py

@@ -0,0 +1,265 @@
+# Copyright 2018 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Firebase token minting and validation sub module."""
+
+import datetime
+import time
+
+import requests
+import six
+from google.auth import jwt
+from google.auth import transport
+import google.oauth2.id_token
+
+from firebase_admin import credentials
+
+# Provided for overriding during tests.
+_request = transport.requests.Request()
+
+# ID token constants
+ID_TOKEN_ISSUER_PREFIX = 'https://securetoken.google.com/'
+ID_TOKEN_CERT_URI = ('https://www.googleapis.com/robot/v1/metadata/x509/'
+                     '[email protected]')
+
+# Session cookie constants
+COOKIE_ISSUER_PREFIX = 'https://session.firebase.google.com/'
+COOKIE_CERT_URI = 'https://www.googleapis.com/identitytoolkit/v3/relyingparty/publicKeys'
+MIN_SESSION_COOKIE_DURATION_SECONDS = datetime.timedelta(minutes=5).total_seconds()
+MAX_SESSION_COOKIE_DURATION_SECONDS = datetime.timedelta(days=14).total_seconds()
+
+# Custom token constants
+MAX_TOKEN_LIFETIME_SECONDS = datetime.timedelta(hours=1).total_seconds()
+FIREBASE_AUDIENCE = ('https://identitytoolkit.googleapis.com/google.'
+                     'identity.identitytoolkit.v1.IdentityToolkit')
+RESERVED_CLAIMS = set([
+    'acr', 'amr', 'at_hash', 'aud', 'auth_time', 'azp', 'cnf', 'c_hash',
+    'exp', 'firebase', 'iat', 'iss', 'jti', 'nbf', 'nonce', 'sub'
+])
+
+# Error codes
+COOKIE_CREATE_ERROR = 'COOKIE_CREATE_ERROR'
+
+
+class ApiCallError(Exception):
+    """Represents an Exception encountered while invoking the ID toolkit API."""
+
+    def __init__(self, code, message, error=None):
+        Exception.__init__(self, message)
+        self.code = code
+        self.detail = error
+
+
+class TokenGenerator(object):
+    """Generates custom tokens and session cookies."""
+
+    def __init__(self, app, client):
+        self._app = app
+        self._client = client
+
+    def create_custom_token(self, uid, developer_claims=None):
+        """Builds and signs a Firebase custom auth token."""
+        if not isinstance(self._app.credential, credentials.Certificate):
+            raise ValueError(
+                'Must initialize Firebase App with a certificate credential '
+                'to call create_custom_token().')
+
+        if developer_claims is not None:
+            if not isinstance(developer_claims, dict):
+                raise ValueError('developer_claims must be a dictionary')
+
+            disallowed_keys = set(developer_claims.keys()) & RESERVED_CLAIMS
+            if disallowed_keys:
+                if len(disallowed_keys) > 1:
+                    error_message = ('Developer claims {0} are reserved and '
+                                     'cannot be specified.'.format(
+                                         ', '.join(disallowed_keys)))
+                else:
+                    error_message = ('Developer claim {0} is reserved and '
+                                     'cannot be specified.'.format(
+                                         ', '.join(disallowed_keys)))
+                raise ValueError(error_message)
+
+        if not uid or not isinstance(uid, six.string_types) or len(uid) > 128:
+            raise ValueError('uid must be a string between 1 and 128 characters.')
+
+        now = int(time.time())
+        payload = {
+            'iss': self._app.credential.service_account_email,
+            'sub': self._app.credential.service_account_email,
+            'aud': FIREBASE_AUDIENCE,
+            'uid': uid,
+            'iat': now,
+            'exp': now + MAX_TOKEN_LIFETIME_SECONDS,
+        }
+
+        if developer_claims is not None:
+            payload['claims'] = developer_claims
+        return jwt.encode(self._app.credential.signer, payload)
+
+    def create_session_cookie(self, id_token, expires_in):
+        """Creates a session cookie from the provided ID token."""
+        id_token = id_token.decode('utf-8') if isinstance(id_token, six.binary_type) else id_token
+        if not isinstance(id_token, six.text_type) or not id_token:
+            raise ValueError(
+                'Illegal ID token provided: {0}. ID token must be a non-empty '
+                'string.'.format(id_token))
+
+        if isinstance(expires_in, datetime.timedelta):
+            expires_in = int(expires_in.total_seconds())
+        if isinstance(expires_in, bool) or not isinstance(expires_in, int):
+            raise ValueError('Illegal expiry duration: {0}.'.format(expires_in))
+        if expires_in < MIN_SESSION_COOKIE_DURATION_SECONDS:
+            raise ValueError('Illegal expiry duration: {0}. Duration must be at least {1} '
+                             'seconds.'.format(expires_in, MIN_SESSION_COOKIE_DURATION_SECONDS))
+        if expires_in > MAX_SESSION_COOKIE_DURATION_SECONDS:
+            raise ValueError('Illegal expiry duration: {0}. Duration must be at most {1} '
+                             'seconds.'.format(expires_in, MAX_SESSION_COOKIE_DURATION_SECONDS))
+
+        payload = {
+            'idToken': id_token,
+            'validDuration': expires_in,
+        }
+        try:
+            response = self._client.request('post', 'createSessionCookie', json=payload)
+        except requests.exceptions.RequestException as error:
+            self._handle_http_error(COOKIE_CREATE_ERROR, 'Failed to create session cookie', error)
+        else:
+            if not response or not response.get('sessionCookie'):
+                raise ApiCallError(COOKIE_CREATE_ERROR, 'Failed to create session cookie.')
+            return response.get('sessionCookie')
+
+    def _handle_http_error(self, code, msg, error):
+        if error.response is not None:
+            msg += '\nServer response: {0}'.format(error.response.content.decode())
+        else:
+            msg += '\nReason: {0}'.format(error)
+        raise ApiCallError(code, msg, error)
+
+
+class TokenVerifier(object):
+    """Verifies ID tokens and session cookies."""
+
+    def __init__(self, app):
+        self._id_token_verifier = _JWTVerifier(
+            project_id=app.project_id, short_name='ID token',
+            operation='verify_id_token()',
+            doc_url='https://firebase.google.com/docs/auth/admin/verify-id-tokens',
+            cert_url=ID_TOKEN_CERT_URI, issuer=ID_TOKEN_ISSUER_PREFIX)
+        self._cookie_verifier = _JWTVerifier(
+            project_id=app.project_id, short_name='session cookie',
+            operation='verify_session_cookie()',
+            doc_url='https://firebase.google.com/docs/auth/admin/verify-id-tokens',
+            cert_url=COOKIE_CERT_URI, issuer=COOKIE_ISSUER_PREFIX)
+
+    def verify_id_token(self, id_token):
+        return self._id_token_verifier.verify(id_token)
+
+    def verify_session_cookie(self, cookie):
+        return self._cookie_verifier.verify(cookie)
+
+
+class _JWTVerifier(object):
+    """Verifies Firebase JWTs (ID tokens or session cookies)."""
+
+    def __init__(self, **kwargs):
+        self.project_id = kwargs.pop('project_id')
+        self.short_name = kwargs.pop('short_name')
+        self.operation = kwargs.pop('operation')
+        self.url = kwargs.pop('doc_url')
+        self.cert_url = kwargs.pop('cert_url')
+        self.issuer = kwargs.pop('issuer')
+        if self.short_name[0].lower() in 'aeiou':
+            self.articled_short_name = 'an {0}'.format(self.short_name)
+        else:
+            self.articled_short_name = 'a {0}'.format(self.short_name)
+
+    def verify(self, token):
+        """Verifies the signature and data for the provided JWT."""
+        token = token.encode('utf-8') if isinstance(token, six.text_type) else token
+        if not isinstance(token, six.binary_type) or not token:
+            raise ValueError(
+                'Illegal {0} provided: {1}. {0} must be a non-empty '
+                'string.'.format(self.short_name, token))
+
+        if not self.project_id:
+            raise ValueError(
+                'Failed to ascertain project ID from the credential or the environment. Project '
+                'ID is required to call {0}. Initialize the app with a credentials.Certificate '
+                'or set your Firebase project ID as an app option. Alternatively set the '
+                'GCLOUD_PROJECT environment variable.'.format(self.operation))
+
+        header = jwt.decode_header(token)
+        payload = jwt.decode(token, verify=False)
+        issuer = payload.get('iss')
+        audience = payload.get('aud')
+        subject = payload.get('sub')
+        expected_issuer = self.issuer + self.project_id
+
+        project_id_match_msg = (
+            'Make sure the {0} comes from the same Firebase project as the service account used '
+            'to authenticate this SDK.'.format(self.short_name))
+        verify_id_token_msg = (
+            'See {0} for details on how to retrieve {1}.'.format(self.url, self.short_name))
+
+        error_message = None
+        if not header.get('kid'):
+            if audience == FIREBASE_AUDIENCE:
+                error_message = (
+                    '{0} expects {1}, but was given a custom '
+                    'token.'.format(self.operation, self.articled_short_name))
+            elif header.get('alg') == 'HS256' and payload.get(
+                    'v') is 0 and 'uid' in payload.get('d', {}):
+                error_message = (
+                    '{0} expects {1}, but was given a legacy custom '
+                    'token.'.format(self.operation, self.articled_short_name))
+            else:
+                error_message = 'Firebase {0} has no "kid" claim.'.format(self.short_name)
+        elif header.get('alg') != 'RS256':
+            error_message = (
+                'Firebase {0} has incorrect algorithm. Expected "RS256" but got '
+                '"{1}". {2}'.format(self.short_name, header.get('alg'), verify_id_token_msg))
+        elif audience != self.project_id:
+            error_message = (
+                'Firebase {0} has incorrect "aud" (audience) claim. Expected "{1}" but '
+                'got "{2}". {3} {4}'.format(self.short_name, self.project_id, audience,
+                                            project_id_match_msg, verify_id_token_msg))
+        elif issuer != expected_issuer:
+            error_message = (
+                'Firebase {0} has incorrect "iss" (issuer) claim. Expected "{1}" but '
+                'got "{2}". {3} {4}'.format(self.short_name, expected_issuer, issuer,
+                                            project_id_match_msg, verify_id_token_msg))
+        elif subject is None or not isinstance(subject, six.string_types):
+            error_message = (
+                'Firebase {0} has no "sub" (subject) claim. '
+                '{1}'.format(self.short_name, verify_id_token_msg))
+        elif not subject:
+            error_message = (
+                'Firebase {0} has an empty string "sub" (subject) claim. '
+                '{1}'.format(self.short_name, verify_id_token_msg))
+        elif len(subject) > 128:
+            error_message = (
+                'Firebase {0} has a "sub" (subject) claim longer than 128 characters. '
+                '{1}'.format(self.short_name, verify_id_token_msg))
+
+        if error_message:
+            raise ValueError(error_message)
+
+        verified_claims = google.oauth2.id_token.verify_token(
+            token,
+            request=_request,
+            audience=self.project_id,
+            certs_url=self.cert_url)
+        verified_claims['uid'] = verified_claims['sub']
+        return verified_claims

firebase_admin/_user_mgt.py

@@ -17,13 +17,10 @@
 import json
 import re
 
-from google.auth import transport
 import requests
 import six
 from six.moves import urllib
 
-import firebase_admin
-
 
 INTERNAL_ERROR = 'INTERNAL_ERROR'
 USER_NOT_FOUND_ERROR = 'USER_NOT_FOUND_ERROR'
@@ -32,8 +29,6 @@
 USER_DELETE_ERROR = 'USER_DELETE_ERROR'
 USER_DOWNLOAD_ERROR = 'LIST_USERS_ERROR'
 
-ID_TOOLKIT_URL = 'https://www.googleapis.com/identitytoolkit/v3/relyingparty/'
-
 MAX_LIST_USERS_RESULTS = 1000
 MAX_CLAIMS_PAYLOAD_SIZE = 1000
 RESERVED_CLAIMS = set([
@@ -225,12 +220,8 @@ class UserManager(object):
         'photoUrl' : 'PHOTO_URL'
     }
 
-    def __init__(self, app):
-        g_credential = app.credential.get_credential()
-        session = transport.requests.AuthorizedSession(g_credential)
-        version_header = 'Python/Admin/{0}'.format(firebase_admin.__version__)
-        session.headers.update({'X-Client-Version': version_header})
-        self._session = session
+    def __init__(self, client):
+        self._client = client
 
     def get_user(self, **kwargs):
         """Gets the user data corresponding to the provided key."""
@@ -250,7 +241,7 @@ def get_user(self, **kwargs):
             raise ValueError('Unsupported keyword arguments: {0}.'.format(kwargs))
 
         try:
-            response = self._request('post', 'getAccountInfo', json=payload)
+            response = self._client.request('post', 'getAccountInfo', json=payload)
         except requests.exceptions.RequestException as error:
             msg = 'Failed to get user by {0}: {1}.'.format(key_type, key)
             self._handle_http_error(INTERNAL_ERROR, msg, error)
@@ -277,7 +268,7 @@ def list_users(self, page_token=None, max_results=MAX_LIST_USERS_RESULTS):
         if page_token:
             payload['nextPageToken'] = page_token
         try:
-            return self._request('post', 'downloadAccount', json=payload)
+            return self._client.request('post', 'downloadAccount', json=payload)
         except requests.exceptions.RequestException as error:
             self._handle_http_error(USER_DOWNLOAD_ERROR, 'Failed to download user accounts.', error)
 
@@ -286,7 +277,7 @@ def create_user(self, **kwargs):
         payload = self._init_payload('create_user', UserManager._CREATE_USER_FIELDS, **kwargs)
         self._validate(payload, self._VALIDATORS, 'create user')
         try:
-            response = self._request('post', 'signupNewUser', json=payload)
+            response = self._client.request('post', 'signupNewUser', json=payload)
         except requests.exceptions.RequestException as error:
             self._handle_http_error(USER_CREATE_ERROR, 'Failed to create new user.', error)
         else:
@@ -319,7 +310,7 @@ def update_user(self, uid, **kwargs):
 
         self._validate(payload, self._VALIDATORS, 'update user')
         try:
-            response = self._request('post', 'setAccountInfo', json=payload)
+            response = self._client.request('post', 'setAccountInfo', json=payload)
         except requests.exceptions.RequestException as error:
             self._handle_http_error(
                 USER_UPDATE_ERROR, 'Failed to update user: {0}.'.format(uid), error)
@@ -332,7 +323,7 @@ def delete_user(self, uid):
         """Deletes the user identified by the specified user ID."""
         _Validator.validate_uid(uid)
         try:
-            response = self._request('post', 'deleteAccount', json={'localId' : uid})
+            response = self._client.request('post', 'deleteAccount', json={'localId' : uid})
         except requests.exceptions.RequestException as error:
             self._handle_http_error(
                 USER_DELETE_ERROR, 'Failed to delete user: {0}.'.format(uid), error)
@@ -365,25 +356,6 @@ def _validate(self, properties, validators, operation):
                 raise ValueError('Unsupported property: "{0}" in {1} call.'.format(key, operation))
             validator(value)
 
-    def _request(self, method, urlpath, **kwargs):
-        """Makes an HTTP call using the Python requests library.
-
-        Refer to http://docs.python-requests.org/en/master/api/ for more information on supported
-        options and features.
-
-        Args:
-          method: HTTP method name as a string (e.g. get, post).
-          urlpath: URL path of the remote endpoint. This will be appended to the server's base URL.
-          kwargs: An additional set of keyword arguments to be passed into requests API
-              (e.g. json, params).
-
-        Returns:
-          dict: The parsed JSON response.
-        """
-        resp = self._session.request(method, ID_TOOLKIT_URL + urlpath, **kwargs)
-        resp.raise_for_status()
-        return resp.json()
-
 
 class UserIterator(object):
     """An iterator that allows iterating over user accounts, one at a time.