From 445e4a44ee46f0d7dd94aa388981110b36bef880 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Mat=C3=ADas=20Aguirre?= <matiasaguirre@gmail.com>
Date: Fri, 14 Jan 2011 03:13:24 -0200
Subject: [PATCH] Update doc about Google OAuth support

---
 README.rst | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 57 insertions(+), 4 deletions(-)

diff --git a/README.rst b/README.rst
index cc57ad7..8256f0c 100644
--- a/README.rst
+++ b/README.rst
@@ -2,7 +2,7 @@
 Django Social Auth
 ==================
 
-Django Social Auth is an easy to setup social authentication/registration
+Django Social Auth is an easy to setup social authentication/authorization
 mechanism for Django projects.
 
 Crafted using base code from django-twitter-oauth_ and django-openid-auth_,
@@ -27,6 +27,7 @@ credentials, some features are:
   at the moment:
 
     * `Google OpenID`_
+    * `Google OAuth`_
     * `Yahoo OpenID`_
     * OpenId_ like myOpenID_
     * `Twitter OAuth`_
@@ -53,6 +54,7 @@ Dependencies that must be meet to use the app:
 - Twitter and Facebook support demands an application registration
   on their corresponding sites.
 
+
 ------------
 Installation
 ------------
@@ -95,13 +97,15 @@ Configuration
         'social_auth.backends.TwitterBackend',
         'social_auth.backends.FacebookBackend',
         'social_auth.backends.OrkutBackend',
+        'social_auth.backends.GoogleOAuthBackend',
         'social_auth.backends.GoogleBackend',
         'social_auth.backends.YahooBackend',
         'social_auth.backends.OpenIDBackend',
         'django.contrib.auth.backends.ModelBackend',
     )
 
-- Setup Twitter and Facebook keys (see OAuth_ section for details)::
+- Setup Twitter, Facebook, Orkut and Google OAuth keys (see OAuth_ section
+  for details)::
 
     TWITTER_CONSUMER_KEY    = ''
     TWITTER_CONSUMER_SECRET = ''
@@ -109,6 +113,8 @@ Configuration
     FACEBOOK_API_SECRET     = ''
     ORKUT_CONSUMER_KEY      = ''
     ORKUT_CONSUMER_SECRET   = ''
+    GOOGLE_CONSUMER_KEY      = ''
+    GOOGLE_CONSUMER_SECRET   = ''
 
 - Setup login URLs::
 
@@ -210,8 +216,10 @@ OAuth
 -----
 OAuth_ communication demands a set of keys exchange to validate the client
 authenticity prior to user approbation. Twitter, Facebook and Orkut
-facilitates these keys by application registration, see next sections for
-details.
+facilitates these keys by application registration, Google works the same,
+but provides the option for unregisterd applications.
+
+Check next sections for details.
 
 
 -------
@@ -262,6 +270,48 @@ your consumer_key and consumer_secret keys.
       ORKUT_CONSUMER_KEY
       ORKUT_CONSUMER_SECRET
 
+- add any needed extra data to::
+
+      ORKUT_EXTRA_DATA = ''
+
+- configure extra scopes in::
+
+      ORKUT_EXTRA_SCOPES = [...]
+
+
+------------
+Google OAuth
+------------
+Google provides "Consumer Key" and "Consumer Secret" keys to
+registered applications, but also allows unregistered application to
+use their authorization system with, but beware that this method
+will display a security banner to the user telling that the application
+is not trusted.
+
+Check `Google OAuth`_ and make your choice.
+
+- fill "Consumer Key" and "Consumer Secret" values::
+
+      GOOGLE_CONSUMER_KEY
+      GOOGLE_CONSUMER_SECRET
+
+anonymous values will be used if not configured as described in their
+`OAuth reference`_
+
+
+- configure the display name to be used in the "grant permissions" dialog
+  that Google will display to users in::
+
+      GOOGLE_DISPLAY_NAME = ''
+
+  shows 'Social Auth' by default, but that might not suite your application.
+
+- setup any needed extra scope in::
+
+      GOOGLE_OAUTH_EXTRA_SCOPE = [...]
+
+check which Apps are included in their `Google Data Protocol Directory`_
+
 
 ----
 Bugs
@@ -325,6 +375,9 @@ Base work is copyrighted by:
 .. _Google support: http://www.google.com/support/a/bin/answer.py?hl=en&answer=162105
 .. _Orkut API:  http://code.google.com/apis/orkut/docs/rest/developers_guide_protocol.html#Authenticating
 .. _Google OpenID: http://code.google.com/apis/accounts/docs/OpenID.html
+.. _Google OAuth: http://code.google.com/apis/accounts/docs/OAuth.html
+.. _Google Data Protocol Directory: http://code.google.com/apis/gdata/docs/directory.html
+.. _OAuth reference: http://code.google.com/apis/accounts/docs/OAuth_ref.html#SigningOAuth
 .. _Yahoo OpenID: http://openid.yahoo.com/
 .. _Twitter OAuth: http://dev.twitter.com/pages/oauth_faq
 .. _Facebook OAuth: http://developers.facebook.com/docs/authentication/
-- 
2.39.5