Implemented support for databaseAuthVariableOverride option (#36)

* Implemented support for databaseAuthVariableOverride option

* Adding newline at the end of acl.json

* Using an ordered dict for passing additional params. This makes the query string order deterministic.

* Passing params as a string to requests in all API calls. This ensures the order of the query params, and the proper encoding.

* Preformatting the auth override query param

* Implementing support for None auth overrides (guest access). Removed options.get() from the public API.

* _AppOptions is already not a part of the public API. Adding the get() method back.

* Merged rule files into one

* Removing unused variable

* Updated documentation

Author: hiranya911

firebase_admin/__init__.py

@@ -149,9 +149,9 @@ def __init__(self, options):
                              'must be a dictionary.'.format(type(options)))
         self._options = options
 
-    def get(self, key):
+    def get(self, key, default=None):
         """Returns the option identified by the provided key."""
-        return self._options.get(key)
+        return self._options.get(key, default)
 
 
 class App(object):

firebase_admin/db.py

@@ -145,8 +145,7 @@ def set(self, value):
         """
         if value is None:
             raise ValueError('Value must not be None.')
-        params = {'print' : 'silent'}
-        self._client.request_oneway('put', self._add_suffix(), json=value, params=params)
+        self._client.request_oneway('put', self._add_suffix(), json=value, params='print=silent')
 
     def push(self, value=''):
         """Creates a new child node.
@@ -185,8 +184,7 @@ def update(self, value):
             raise ValueError('Value argument must be a non-empty dictionary.')
         if None in value.keys() or None in value.values():
             raise ValueError('Dictionary must not contain None keys or values.')
-        params = {'print':'silent'}
-        self._client.request_oneway('patch', self._add_suffix(), json=value, params=params)
+        self._client.request_oneway('patch', self._add_suffix(), json=value, params='print=silent')
 
     def delete(self):
         """Deleted this node from the database.
@@ -378,7 +376,7 @@ def equal_to(self, value):
         return self
 
     @property
-    def querystr(self):
+    def _querystr(self):
         params = []
         for key in sorted(self._params):
             params.append('{0}={1}'.format(key, self._params[key]))
@@ -396,7 +394,7 @@ def get(self):
         Raises:
           ApiCallError: If an error occurs while communicating with the remote database server.
         """
-        result = self._client.request('get', '{0}?{1}'.format(self._pathurl, self.querystr))
+        result = self._client.request('get', self._pathurl, params=self._querystr)
         if isinstance(result, (dict, list)) and self._order_by != '$priority':
             return _Sorter(result, self._order_by).get()
         return result
@@ -544,14 +542,33 @@ class _Client(object):
     marshalling and unmarshalling of JSON data.
     """
 
-    def __init__(self, url=None, auth=None, session=None):
-        self._url = url
-        self._auth = auth
-        self._session = session
+    def __init__(self, **kwargs):
+        """Creates a new _Client from the given parameters.
+
+        This exists primarily to enable testing. For regular use, obtain _Client instances by
+        calling the from_app() class method.
+
+        Keyword Args:
+          url: Firebase Realtime Database URL.
+          auth: An instance of requests.auth.AuthBase for authenticating outgoing HTTP requests.
+          session: An HTTP session created using the the requests module.
+          auth_override: A dictionary representing auth variable overrides or None (optional).
+              Defaults to empty dict, which provides admin privileges. A None value here provides
+              un-authenticated guest privileges.
+        """
+        self._url = kwargs.pop('url')
+        self._auth = kwargs.pop('auth')
+        self._session = kwargs.pop('session')
+        auth_override = kwargs.pop('auth_override', {})
+        if auth_override != {}:
+            encoded = json.dumps(auth_override, separators=(',', ':'))
+            self._auth_override = 'auth_variable_override={0}'.format(encoded)
+        else:
+            self._auth_override = None
 
     @classmethod
     def from_app(cls, app):
-        """Created a new _Client for a given App"""
+        """Creates a new _Client for a given App"""
         url = app.options.get('databaseURL')
         if not url or not isinstance(url, six.string_types):
             raise ValueError(
@@ -565,7 +582,13 @@ def from_app(cls, app):
             raise ValueError(
                 'Invalid databaseURL option: "{0}". databaseURL must be a valid URL to a '
                 'Firebase Realtime Database instance.'.format(url))
-        return _Client('https://{0}'.format(parsed.netloc), _OAuth(app), requests.Session())
+
+        auth_override = app.options.get('databaseAuthVariableOverride', {})
+        if auth_override is not None and not isinstance(auth_override, dict):
+            raise ValueError('Invalid databaseAuthVariableOverride option: "{0}". Override '
+                             'value must be a dict or None.'.format(auth_override))
+        return _Client(url='https://{0}'.format(parsed.netloc), auth=_OAuth(app),
+                       session=requests.Session(), auth_override=auth_override)
 
     def request(self, method, urlpath, **kwargs):
         return self._do_request(method, urlpath, **kwargs).json()
@@ -591,6 +614,13 @@ def _do_request(self, method, urlpath, **kwargs):
         Raises:
           ApiCallError: If an error occurs while making the HTTP call.
         """
+        if self._auth_override:
+            params = kwargs.get('params')
+            if params:
+                params += '&{0}'.format(self._auth_override)
+            else:
+                params = self._auth_override
+            kwargs['params'] = params
         try:
             resp = self._session.request(method, self._url + urlpath, auth=self._auth, **kwargs)
             resp.raise_for_status()

integration/conftest.py

@@ -34,6 +34,14 @@ def _get_cert_path(request):
     raise ValueError('Service account certificate not specified. Make sure to specify the '
                      '"--cert" command-line option.')
 
+def integration_conf(request):
+    cert_path = _get_cert_path(request)
+    with open(cert_path) as cert:
+        project_id = json.load(cert).get('project_id')
+    if not project_id:
+        raise ValueError('Failed to determine project ID from service account certificate.')
+    return credentials.Certificate(cert_path), project_id
+
 @pytest.fixture(autouse=True, scope='session')
 def default_app(request):
     """Initializes the default Firebase App instance used for all integration tests.
@@ -42,12 +50,7 @@ def default_app(request):
     a test session. It is also marked as autouse, and therefore runs automatically without
     test cases having to call it explicitly.
     """
-    cert_path = _get_cert_path(request)
-    with open(cert_path) as cert:
-        project_id = json.load(cert).get('project_id')
-    if not project_id:
-        raise ValueError('Failed to determine project ID from service account certificate.')
-    cred = credentials.Certificate(cert_path)
+    cred, project_id = integration_conf(request)
     ops = {'databaseURL' : 'https://{0}.firebaseio.com'.format(project_id)}
     return firebase_admin.initialize_app(cred, ops)
 

integration/test_db.py

@@ -18,17 +18,20 @@
 
 import pytest
 
+import firebase_admin
 from firebase_admin import db
+from integration import conftest
 from tests import testutils
 
-def _update_rules():
-    with open(testutils.resource_filename('dinosaurs_index.json')) as index_file:
-        index = json.load(index_file)
+@pytest.fixture(scope='module')
+def update_rules():
+    with open(testutils.resource_filename('dinosaurs_index.json')) as rules_file:
+        new_rules = json.load(rules_file)
     client = db.reference()._client
     rules = client.request('get', '/.settings/rules.json')
     existing = rules.get('rules', dict()).get('_adminsdk')
-    if existing != index:
-        rules['rules']['_adminsdk'] = index
+    if existing != new_rules:
+        rules['rules']['_adminsdk'] = new_rules
         client.request('put', '/.settings/rules.json', json=rules)
 
 @pytest.fixture(scope='module')
@@ -37,7 +40,7 @@ def testdata():
         return json.load(dino_file)
 
 @pytest.fixture(scope='module')
-def testref():
+def testref(update_rules):
     """Adds the necessary DB indices, and sets the initial values.
 
     This fixture is attached to the module scope, and therefore is guaranteed to run only once
@@ -46,7 +49,6 @@ def testref():
     Returns:
         Reference: A reference to the test dinosaur database.
     """
-    _update_rules()
     ref = db.reference('_adminsdk/python/dinodb')
     ref.set(testdata())
     return ref
@@ -134,6 +136,13 @@ def test_update_children_with_existing_values(self, testref):
         ref.update({'since' : 1905})
         assert ref.get() == {'name' : 'Edwin Colbert', 'since' : 1905}
 
+    def test_update_nested_children(self, testref):
+        python = testref.parent
+        ref = python.child('users').push({'name' : 'Edward Cope', 'since' : 1800})
+        nested_key = '{0}/since'.format(ref.key)
+        python.child('users').update({nested_key: 1840})
+        assert ref.get() == {'name' : 'Edward Cope', 'since' : 1840}
+
     def test_delete(self, testref):
         python = testref.parent
         ref = python.child('users').push('foo')
@@ -220,3 +229,93 @@ def test_filter_by_value(self, testref):
         assert len(value) == 2
         assert 'pterodactyl' in value
         assert 'linhenykus' in value
+
+
+@pytest.fixture(scope='module')
+def override_app(request, update_rules):
+    cred, project_id = conftest.integration_conf(request)
+    ops = {
+        'databaseURL' : 'https://{0}.firebaseio.com'.format(project_id),
+        'databaseAuthVariableOverride' : {'uid' : 'user1'}
+    }
+    app = firebase_admin.initialize_app(cred, ops, 'db-override')
+    yield app
+    firebase_admin.delete_app(app)
+
+@pytest.fixture(scope='module')
+def none_override_app(request, update_rules):
+    cred, project_id = conftest.integration_conf(request)
+    ops = {
+        'databaseURL' : 'https://{0}.firebaseio.com'.format(project_id),
+        'databaseAuthVariableOverride' : None
+    }
+    app = firebase_admin.initialize_app(cred, ops, 'db-none-override')
+    yield app
+    firebase_admin.delete_app(app)
+
+
+class TestAuthVariableOverride(object):
+    """Test cases for database auth variable overrides."""
+
+    def init_ref(self, path):
+        admin_ref = db.reference(path)
+        admin_ref.set('test')
+        assert admin_ref.get() == 'test'
+
+    def check_permission_error(self, excinfo):
+        assert isinstance(excinfo.value, db.ApiCallError)
+        assert 'Reason: Permission denied' in str(excinfo.value)
+
+    def test_no_access(self, override_app):
+        path = '_adminsdk/python/admin'
+        self.init_ref(path)
+        user_ref = db.reference(path, override_app)
+        with pytest.raises(db.ApiCallError) as excinfo:
+            assert user_ref.get()
+        self.check_permission_error(excinfo)
+
+        with pytest.raises(db.ApiCallError) as excinfo:
+            user_ref.set('test2')
+        self.check_permission_error(excinfo)
+
+    def test_read(self, override_app):
+        path = '_adminsdk/python/protected/user2'
+        self.init_ref(path)
+        user_ref = db.reference(path, override_app)
+        assert user_ref.get() == 'test'
+        with pytest.raises(db.ApiCallError) as excinfo:
+            user_ref.set('test2')
+        self.check_permission_error(excinfo)
+
+    def test_read_write(self, override_app):
+        path = '_adminsdk/python/protected/user1'
+        self.init_ref(path)
+        user_ref = db.reference(path, override_app)
+        assert user_ref.get() == 'test'
+        user_ref.set('test2')
+        assert user_ref.get() == 'test2'
+
+    def test_query(self, override_app):
+        user_ref = db.reference('_adminsdk/python/protected', override_app)
+        with pytest.raises(db.ApiCallError) as excinfo:
+            user_ref.order_by_key().limit_to_first(2).get()
+        self.check_permission_error(excinfo)
+
+    def test_none_auth_override(self, none_override_app):
+        path = '_adminsdk/python/public'
+        self.init_ref(path)
+        public_ref = db.reference(path, none_override_app)
+        assert public_ref.get() == 'test'
+
+        ref = db.reference('_adminsdk/python', none_override_app)
+        with pytest.raises(db.ApiCallError) as excinfo:
+            assert ref.child('protected/user1').get()
+        self.check_permission_error(excinfo)
+
+        with pytest.raises(db.ApiCallError) as excinfo:
+            assert ref.child('protected/user2').get()
+        self.check_permission_error(excinfo)
+
+        with pytest.raises(db.ApiCallError) as excinfo:
+            assert ref.child('admin').get()
+        self.check_permission_error(excinfo)

tests/data/dinosaurs_index.json

@@ -7,6 +7,19 @@
             "scores": {
                 ".indexOn": ".value"
             }
+        },
+        "protected": {
+            "$uid": {
+                ".read": "auth != null",
+                ".write": "$uid === auth.uid"
+            }
+        },
+        "admin": {
+            ".read": "false",
+            ".write": "false"
+        },
+        "public": {
+            ".read": "true"
         }
     }
 }