Gentics Portal.Node PHP API
 All Classes Namespaces Functions Variables Pages
common/extensions/eauth/README.md
1 Yii EAuth extension
2 ===================
3 
4 EAuth extension allows to authenticate users with accounts on other websites.
5 Supported protocols: OpenID, OAuth 1.0 and OAuth 2.0.
6 
7 EAuth is a extension for provide a unified (does not depend on the selected service) method to authenticate the user. So, the extension itself does not perform login, does not register the user and does not bind the user accounts from different providers.
8 
9 
10 ### Why own extension and not a third-party service?
11 The implementation of the authorization on your own server has several advantages:
12 
13 * Full control over the process: what will be written in the authorization window, what data we get, etc.
14 * Ability to change the appearance of the widget.
15 * When logging via OAuth is possible to invoke methods on API.
16 * Fewer dependencies on third-party services - more reliable application.
17 
18 
19 ### The extension allows you to:
20 
21 * Ignore the nuances of authorization through the different types of services, use the class based adapters for each service.
22 * Get a unique user ID that can be used to register user in your application.
23 * Extend the standard authorization classes to obtain additional data about the user.
24 * Work with the API of social networks by extending the authorization classes.
25 * Set up a list of supported services, customize the appearance of the widget, use the popup window without closing your application.
26 
27 
28 ### Extension includes:
29 
30 * The component that contains utility functions.
31 * A widget that displays a list of services in the form of icons and allowing authorization in the popup window.
32 * Base classes to create your own services.
33 * Ready for authenticate via Google, Twitter, Facebook and other providers.
34 
35 
36 ### Supported providers "out of box":
37 
38 * OpenID: Google, Yandex(ru)
39 * OAuth: Twitter
40 * OAuth 2.0: Google, Facebook, VKontake(ru), Mail.ru(ru), Moi Krug(ru), Odnoklassniki(ru)
41 
42 
43 ### Resources
44 
45 * [Yii EAuth](https://github.com/Nodge/yii-eauth)
46 * [Yii Framework](http://yiiframework.com/)
47 * [OpenID](http://openid.net/)
48 * [OAuth](http://oauth.net/)
49 * [OAuth 2.0](http://oauth.net/2/)
50 * [loid extension](http://www.yiiframework.com/extension/loid)
51 * [EOAuth extension](http://www.yiiframework.com/extension/eoauth)
52 
53 
54 ### Requirements
55 
56 * Yii 1.1 or above
57 * PHP curl extension
58 * [loid extension](http://www.yiiframework.com/extension/loid)
59 * [EOAuth extension](http://www.yiiframework.com/extension/eoauth)
60 
61 
62 ## Installation
63 
64 * Install loid and EOAuth extensions
65 * Extract the release file under `protected/extensions`
66 * In your `protected/config/main.php`, add the following:
67 
68 ```php
69 <?php
70 ...
71  'import'=>array(
72  'ext.eoauth.*',
73  'ext.eoauth.lib.*',
74  'ext.lightopenid.*',
75  'ext.eauth.*',
76  'ext.eauth.services.*',
77  ),
78 ...
79  'components'=>array(
80  'loid' => array(
81  'class' => 'ext.lightopenid.loid',
82  ),
83  'eauth' => array(
84  'class' => 'ext.eauth.EAuth',
85  'popup' => true, // Use the popup window instead of redirecting.
86  'services' => array( // You can change the providers and their classes.
87  'google' => array(
88  'class' => 'GoogleOpenIDService',
89  ),
90  'yandex' => array(
91  'class' => 'YandexOpenIDService',
92  ),
93  'twitter' => array(
94  // register your app here: https://dev.twitter.com/apps/new
95  'class' => 'TwitterOAuthService',
96  'key' => '...',
97  'secret' => '...',
98  ),
99  'google_oauth' => array(
100  // register your app here: https://code.google.com/apis/console/
101  'class' => 'GoogleOAuthService',
102  'client_id' => '...',
103  'client_secret' => '...',
104  'title' => 'Google (OAuth)',
105  ),
106  'facebook' => array(
107  // register your app here: https://developers.facebook.com/apps/
108  'class' => 'FacebookOAuthService',
109  'client_id' => '...',
110  'client_secret' => '...',
111  ),
112  'vkontakte' => array(
113  // register your app here: http://vkontakte.ru/editapp?act=create&site=1
114  'class' => 'VKontakteOAuthService',
115  'client_id' => '...',
116  'client_secret' => '...',
117  ),
118  'mailru' => array(
119  // register your app here: http://api.mail.ru/sites/my/add
120  'class' => 'MailruOAuthService',
121  'client_id' => '...',
122  'client_secret' => '...',
123  ),
124  'moikrug' => array(
125  // register your app here: https://oauth.yandex.ru/client/my
126  'class' => 'MoikrugOAuthService',
127  'client_id' => '...',
128  'client_secret' => '...',
129  ),
130  'odnoklassniki' => array(
131  // register your app here: http://www.odnoklassniki.ru/dk?st.cmd=appsInfoMyDevList&st._aid=Apps_Info_MyDev
132  'class' => 'OdnoklassnikiOAuthService',
133  'client_id' => '...',
134  'client_public' => '...',
135  'client_secret' => '...',
136  'title' => 'Odnokl.',
137  ),
138  ),
139  ),
140  ...
141  ),
142 ...
143 ```
144 
145 
146 ## Usage
147 
148 #### The action
149 
150 ```php
151 <?php
152 ...
153  public function actionLogin() {
154  $service = Yii::app()->request->getQuery('service');
155  if (isset($service)) {
156  $authIdentity = Yii::app()->eauth->getIdentity($service);
157  $authIdentity->redirectUrl = Yii::app()->user->returnUrl;
158  $authIdentity->cancelUrl = $this->createAbsoluteUrl('site/login');
159 
160  if ($authIdentity->authenticate()) {
161  $identity = new EAuthUserIdentity($authIdentity);
162 
163  // successful authentication
164  if ($identity->authenticate()) {
165  Yii::app()->user->login($identity);
166 
167  // special redirect with closing popup window
168  $authIdentity->redirect();
169  }
170  else {
171  // close popup window and redirect to cancelUrl
172  $authIdentity->cancel();
173  }
174  }
175 
176  // Something went wrong, redirect to login page
177  $this->redirect(array('site/login'));
178  }
179 
180  // default authorization code through login/password ..
181  }
182 ```
183 
184 #### The view
185 
186 ```php
187 <h2>Do you already have an account on one of these sites? Click the logo to log in with it here:</h2>
188 <?php
189  $this->widget('ext.eauth.EAuthWidget', array('action' => 'site/login'));
190 ?>
191 ```
192 
193 #### Getting more user data (optional)
194 
195 To receive all the necessary data to your application, you can override the base class of any provider.
196 Base classes are stored in `protected/extensions/eauth/services/`.
197 Examples of extended classes can be found in `protected/extensions/eauth/custom_services/`.
198 
199 After overriding the base class, you need to modify your configuration file to set new name of the class.
200 Also you may need to override the `EAuthUserIdentity` class to store additional data.
201 
202 #### Translations (optional)
203 
204 * Copy the file `/protected/extensions/eauth/messages/[lang]/eauth.php` to `/protected/messages/[lang]/eauth.php` to translate the EAuth extension into other languages.
205 * To add a new language, you can use the blank file `/protected/extensions/eauth/messages/blank/eauth.php`.
206 
207 ## License
208 
209 Some time ago I developed this extension for [LiStick.ru](http://listick.ru) and I still support the extension.
210 
211 The extension was released under the [New BSD License](http://www.opensource.org/licenses/bsd-license.php), so you'll find the latest version on [GitHub](https://github.com/Nodge/yii-eauth).