README.md 9.39 KB
Newer Older
1 2 3
AuthClient Extension for Yii 2
==============================

4
This extension adds [OpenID](http://openid.net/), [OAuth](http://oauth.net/) and [OAuth2](http://oauth.net/2/) consumers for the Yii framework 2.0.
5 6 7 8 9 10 11 12 13 14


Installation
------------

The preferred way to install this extension is through [composer](http://getcomposer.org/download/).

Either run

```
15
php composer.phar require --prefer-dist yiisoft/yii2-authclient "*"
16 17 18 19 20 21 22 23
```

or add

```json
"yiisoft/yii2-authclient": "*"
```

Qiang Xue committed
24
to the `require` section of your composer.json.
25 26


27 28
Quick start
-----------
29

30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
This extension provides the ability of the authentication via external credentials providers.
It covers OpenID, OAuth1 and OAuth2 protocols.

You need to setup auth client collection application component:

```
'components' => [
    'authClientCollection' => [
        'class' => 'yii\authclient\Collection',
        'clients' => [
            'google' => [
                'class' => 'yii\authclient\clients\GoogleOpenId'
            ],
            'facebook' => [
                'class' => 'yii\authclient\clients\Facebook',
                'clientId' => 'facebook_client_id',
                'clientSecret' => 'facebook_client_secret',
            ],
        ],
    ]
    ...
]
```

Qiang Xue committed
54
Then you need to add [[yii\authclient\AuthAction]] to some of your web controllers:
55 56 57 58 59 60 61 62 63 64 65

```
class SiteController extends Controller
{
    public function actions()
    {
        return [
            'auth' => [
                'class' => 'yii\authclient\AuthAction',
                'successCallback' => [$this, 'successCallback'],
            ],
Arthur Khachaturov committed
66
        ];
67 68 69 70
    }

    public function successCallback($client)
    {
Qiang Xue committed
71
        $attributes = $client->getUserAttributes();
72 73 74 75 76
        // user login or signup comes here
    }
}
```

77
You may use [[yii\authclient\widgets\AuthChoice]] to compose auth client selection:
78 79

```
80
<?= yii\authclient\widgets\AuthChoice::widget([
81
     'baseAuthUrl' => ['site/auth']
Qiang Xue committed
82 83
]) ?>
```
84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121


Base auth clients overview
--------------------------

This extension provides the base client class for each supported auth protocols:
 - [[yii\authclient\OpenId]] supports [OpenID](http://openid.net/)
 - [[yii\authclient\OAuth1]] supports [OAuth 1/1.0a](http://oauth.net/)
 - [[yii\authclient\OAuth2]] supports [OAuth 2](http://oauth.net/2/)

You may use these classes as they are to use external auth provider, or extend them
in order to create some particular provider oriented client.

Please, refer to the particular base client class documentation for its actual usage.

Although, all clients are different they shares same basic interface [[yii\authclient\ClientInterface]],
which governs some common API.

Each client has some descriptive data, which can be used for different purposes:
 - id - unique client id, which separates it from other clients, it could be used in URLs, logs etc.
 - name - external auth provider name, which this client is match too. Different auth clients
 can share the same name, if they refer to the same external auth provider.
 For example: clients for Google OpenID and Google OAuth have same name "google".
 This attribute can be used inside the database, CSS styles and so on.
 - title - user friendly name for the external auth provider, it is used to present auth client
 at the view layer.

Each auth client has different auth flow, but all of them supports "getUserAttributes()" method,
which can be invoked if authentication was successful.
This method allows you to get information about external user account, such as id, email address,
full name, preferred language etc.
Defining list of attributes, which external auth provider should return, depends on client type:
 - [[yii\authclient\OpenId]]: combination of "requiredAttributes" and "optionalAttributes"
 - [[yii\authclient\OAuth1]] and [[yii\authclient\OAuth2]]: field "scope", note that different
 providers use different formats for the scope.

Each auth client has "viewOptions" attribute. It is an array, which stores name-value pairs,
which serve to compose client representation in the view.
122
For example widget [[yii\authclient\widgets\AuthChoice]] uses keys "popupWidth" and "popupHeight" to
123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
determine the size of authentication popup window.


External API usage
------------------

Both [[yii\authclient\OAuth1]] and [[yii\authclient\OAuth2]] provide method "api()", which
can be used to access external auth provider REST API. However this method is very basic and
it may be not enough to access full external API functionality. This method is mainly used to
fetch the external user account data.
To use API calls, you need to setup [[yii\authclient\BaseOAuth::apiBaseUrl]] according to the
API specification. Then you can call [[yii\authclient\BaseOAuth::api()]] method:
```
use yii\authclient\OAuth2;

$client = new OAuth2;
...
$client->apiBaseUrl = 'https://www.googleapis.com/oauth2/v1';
$userInfo = $client->api('userinfo', 'GET');
```


Predefined auth clients
-----------------------

This extension provides the list of ready to use auth clients, which covers most
popular external authentication providers. These clients are located under "yii\authclient\clients"
namespace.

Following predefined auth clients are available:
 - [[yii\authclient\clients\Facebook]] - [Facebook](https://www.facebook.com/) OAuth2 client
 - [[yii\authclient\clients\GitHub]] - [GitHub](https://github.com/) OAuth2 client
 - [[yii\authclient\clients\GoogleOAuth]] - [Google](https://www.google.com/) OAuth2 client
 - [[yii\authclient\clients\GoogleOpenId]] - [Google](https://www.google.com/) OpenID client
 - [[yii\authclient\clients\LinkedIn]] - [LinkedIn](http://www.linkedin.com/) OAuth2 client
 - [[yii\authclient\clients\LinkedIn]] - [LinkedIn](http://www.linkedin.com/) OAuth2 client
159
 - [[yii\authclient\clients\Live]] - [Microsoft Live](http://live.com/) OAuth2 client
160
 - [[yii\authclient\clients\Twitter]] - [Twitter](https://twitter.com/) OAuth1 client
161
 - [[yii\authclient\clients\VKontakte]] - [VKontakte](http://vk.com/) OAuth2 client
162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186
 - [[yii\authclient\clients\YandexOAuth]] - [Yandex](http://www.yandex.ru/) OAuth2 client
 - [[yii\authclient\clients\YandexOpenId]] - [Yandex](http://www.yandex.ru/) OpenID client

Please, refer to the particular client class documentation for its actual usage.


Creating your own auth clients
------------------------------

You may create your own auth client for any external auth provider, which supports
OpenId or OAuth protocol. To do so, first of all, you need to find out which protocol is
supported by the external auth provider, this will give you the name of the base class
for your extension:
 - for OAuth 2 use [[yii\authclient\OAuth2]]
 - for OAuth 1/1.0a use [[yii\authclient\OAuth1]]
 - for OpenID use [[yii\authclient\OpenId]]

At this stage you can determine auth client default name, title and view options, declaring
corresponding methods:

```
use yii\authclient\OAuth2;

class MyAuthClient extends OAuth2
{
187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
    protected function defaultName()
    {
        return 'my_auth_client';
    }

    protected function defaultTitle()
    {
        return 'My Auth Client';
    }

    protected function defaultViewOptions()
    {
        return [
            'popupWidth' => 800,
            'popupHeight' => 500,
        ];
    }
204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219
}
```

Depending on actual base class, you will need to redeclare different fields and methods.

1) [[yii\authclient\OpenId]]

All you need is specify auth URL, by redeclaring "authUrl" field.
You may also setup default required and/or optional attributes.
For example:

```
use yii\authclient\OpenId;

class MyAuthClient extends OpenId
{
220
    public $authUrl = 'https://www.my.com/openid/';
221

222 223 224
    public $requiredAttributes = [
        'contact/email',
    ];
225

226 227 228 229
    public $optionalAttributes = [
        'namePerson/first',
        'namePerson/last',
    ];
230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247
}
```

2) [[yii\authclient\OAuth2]]

You will need to specify:
- authorize URL - redeclare "authUrl" field
- token request URL - redeclare "tokenUrl" field
- API base URL - redeclare "apiBaseUrl" field
- User attribute fetching strategy - redeclare "initUserAttributes" method

For example:

```
use yii\authclient\OAuth2;

class MyAuthClient extends OAuth2
{
248
    public $authUrl = 'https://www.my.com/oauth2/auth';
249

250
    public $tokenUrl = 'https://www.my.com/oauth2/token';
251

252
    public $apiBaseUrl = 'https://www.my.com/apis/oauth2/v1';
253

254 255 256 257
    protected function initUserAttributes()
    {
        return $this->api('userinfo', 'GET');
    }
258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281
}
```

You may also specify default auth scopes.

Note: some OAuth providers may not follow OAuth standards clearly, introducing
some differences, which may require additional efforts to apply.

3) [[yii\authclient\OAuth1]]

You will need to specify:
- authorize URL - redeclare "authUrl" field
- request token URL - redeclare "requestTokenUrl" field
- access token URL - redeclare "accessTokenUrl" field
- API base URL - redeclare "apiBaseUrl" field
- User attribute fetching strategy - redeclare "initUserAttributes" method

For example:

```
use yii\authclient\OAuth1;

class MyAuthClient extends OAuth1
{
282
    public $authUrl = 'https://www.my.com/oauth/auth';
283

284
    public $requestTokenUrl = 'https://www.my.com/oauth/request_token';
285

286
    public $accessTokenUrl = 'https://www.my.com/oauth/access_token';
287

288
    public $apiBaseUrl = 'https://www.my.com/apis/oauth/v1';
289

290 291 292 293
    protected function initUserAttributes()
    {
        return $this->api('userinfo', 'GET');
    }
294 295 296 297 298 299
}
```

You may also specify default auth scopes.

Note: some OAuth providers may not follow OAuth standards clearly, introducing
300
some differences, which may require additional efforts to apply.