From 660516371d042db6cfe38ed608759fe5b4d201ee Mon Sep 17 00:00:00 2001 From: Andrew Pendleton Date: Thu, 24 Jul 2014 17:06:29 -0400 Subject: [PATCH 1/2] Document locksmith.lightauth. --- README.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index 6211a90..8512ecc 100644 --- a/README.rst +++ b/README.rst @@ -76,7 +76,7 @@ They can be added to your urls.py with the following line: This adds an accounts/ path that contains user-facing urls and an analytics/ path that adds analytics views that are only accessible by staff members. -locksmith.auth and locksmith.mongoauth +locksmith.auth, locksmith.mongoauth, and locksmith.lightauth ====================================== locksmith.auth and locksmith.mongoauth serve the same purpose and are basically interchangable. @@ -85,11 +85,13 @@ Both apps provide URL endpoints and a management command that aim to make writin In most places below they are interchangable and are denoted as ``locksmith.(mongo)auth``, use ``locksmith.mongoauth`` if you prefer your keys/logs to be stored in MongoDB, and use ``locksmith.auth`` if you prefer to use standard Django models. +locksmith.lightauth is a lighter-weight alternative to locksmith.auth and locksmith.mongoauth that doesn't maintain any local data about the state of shared API keys; instead, it queries the hub every time it sees a new key, and caches valid keys for 24 hours (invalid keys aren't cached). This has the advantage that no pushing is involved and no consistent state has to be maintained, so deployment is simpler, but it has the disadvantage that performance is slightly worse the first time a new key is encountered during a given day, and that propagation of invalidation of a key might take as long as 24 hours. locksmith.lightauth also has no machinery for tracking or reporting API usage. + Installation ------------ -* add 'locksmith.(mongo)auth' to ``INSTALLED_APPS`` -* add a line like: (r'^api/', include('locksmith.(mongo)auth.urls')) to urls.py +* add 'locksmith.(mongo/light)auth' to ``INSTALLED_APPS`` +* for auth or mongoauth, add a line like: (r'^api/', include('locksmith.(mongo)auth.urls')) to urls.py Add the following settings to your settings.py: @@ -100,7 +102,7 @@ Add the following settings to your settings.py: ``LOCKSMITH_API_NAME`` name of this locksmith instance -You can optionally enable the ``APIKeyMiddleware`` by adding ``'locksmith.(mongo)auth.middleware.APIKeyMiddleware'`` to your ``MIDDLEWARE_CLASSES``. This middleware makes use of two more optional settings: +You can optionally enable the ``APIKeyMiddleware`` by adding ``'locksmith.(mongo/light)auth.middleware.APIKeyMiddleware'`` to your ``MIDDLEWARE_CLASSES``. This middleware makes use of two more optional settings: ``LOCKSMITH_QS_PARAM`` Query String parameter to check for API key (default: apikey) From e25657a3e0604ae8cc27f75bbb4f3a02e55dec69 Mon Sep 17 00:00:00 2001 From: Andrew Pendleton Date: Fri, 25 Jul 2014 12:39:57 -0400 Subject: [PATCH 2/2] A bit more detail on lightauth. --- README.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 8512ecc..813338d 100644 --- a/README.rst +++ b/README.rst @@ -77,7 +77,7 @@ This adds an accounts/ path that contains user-facing urls and an analytics/ pat locksmith.auth, locksmith.mongoauth, and locksmith.lightauth -====================================== +============================================================ locksmith.auth and locksmith.mongoauth serve the same purpose and are basically interchangable. @@ -145,7 +145,9 @@ If using ``locksmith.auth`` the ``locksmith.auth.models.ApiKey`` model is used t If using ``locksmith.mongoauth`` a collection named ``locksmith.keys`` will be created with '_id', 'status', and 'email' fields. -When a user passes a key to your API you should check if such an ``ApiKey`` object exists and if it is active (ie. status='A') before serving the request. This check is handled automatically if you are using the provided ``APIKeyMiddleware``. +If using either of these apps, when a user passes a key to your API you should check if such an ``ApiKey`` object exists and if it is active (ie. status='A') before serving the request. This check is handled automatically if you are using the provided ``APIKeyMiddleware``. + +``locksmith.lightauth`` has no models or collections, but does require that a Django cache backend be configured if using the supplied middleware. To manually check whether a key is valid, a ``check_key`` function is supplied in ``locksmith.lightauth.common``. Note that its results aren't automatically cached, so you may want to cache them if you anticipate checking the same key repeatedly. Reporting Statistics --------------------