社会化登录

Yii2 官方扩展 yii2-authclient，为 Yii 框架 2.0 增加了 OpenID、OAuth、OAuth2 和 OpenId Connect 消费者。

安装

安装此扩展的首选方式是通过 composer，命令如下：

composer require yiisoft/yii2-authclient

或者在 composer.json 文件中的 require 部分增加以下内容：

"yiisoft/yii2-authclient": "~2.2.0"

然后执行 composer install 命令即可。

配置应用

扩展安装后，你需要设置认证客户端的收集应用程序组件：

return [
    'components' => [
        'authClientCollection' => [
            'class' => 'yii\authclient\Collection',
            'clients' => [
                'google' => [
                    'class' => 'yii\authclient\clients\Google',
                    'clientId' => 'google_client_id',
                    'clientSecret' => 'google_client_secret',
                ],
                'facebook' => [
                    'class' => 'yii\authclient\clients\Facebook',
                    'clientId' => 'facebook_client_id',
                    'clientSecret' => 'facebook_client_secret',
                ],
                // etc.
            ],
        ]
        // ...
    ],
    // ...
];

Yii2 提供了以下开箱即用的客户端：

• yii\authclient\clients\Facebook：Facebook
• yii\authclient\clients\GitHub：GitHub
• yii\authclient\clients\Google：Google OAuth
• yii\authclient\clients\GoogleHybrid：Google OAuth Hybrid
• yii\authclient\clients\LinkedIn：LinkedIn
• yii\authclient\clients\Live：Microsoft Live
• yii\authclient\clients\Twitter：Twitter
• yii\authclient\clients\VKontakte：VKontakte
• yii\authclient\clients\Yandex：Yandex

每个客户机的配置略有不同。对于 OAuth，它需要从你将要使用的服务中获取客户端 ID 和密钥。而对于 OpenID，它在大多数情况下都是开箱即用的。

存储授权数据

In order to recognize the user authenticated via external service we need to store ID provided on first authentication and then check against it on subsequent authentications. It’s not a good idea to limit login options to external services only since these may fail and there won’t be a way for the user to log in. Instead, it’s better to provide both external authentication and good old login and password.

If we’re storing user information in a database the corresponding migration code could be the following:

class m??????_??????_auth extends \yii\db\Migration
{
    public function up()
    {
        $this->createTable('user', [
            'id' => $this->primaryKey(),
            'username' => $this->string()->notNull(),
            'auth_key' => $this->string()->notNull(),
            'password_hash' => $this->string()->notNull(),
            'password_reset_token' => $this->string()->notNull(),
            'email' => $this->string()->notNull(),
            'github' => $this->string(),
            'status' => $this->smallInteger()->notNull()->defaultValue(10),
            'created_at' => $this->integer()->notNull(),
            'updated_at' => $this->integer()->notNull(),
        ]);

        $this->createTable('auth', [
            'id' => $this->primaryKey(),
            'user_id' => $this->integer()->notNull(),
            'source' => $this->string()->notNull(),
            'source_id' => $this->string()->notNull(),
        ]);

        $this->addForeignKey('fk-auth-user_id-user-id', 'auth', 'user_id', 'user', 'id', 'CASCADE', 'CASCADE');
    }

    public function down()
    {
        $this->dropTable('auth');
        $this->dropTable('user');
    }
}

In the above example user is a standard table that is used in advanced project template to store user info. Each user can authenticate using multiple external services therefore each user record can relate to multiple auth records. In the auth table source is the name of the auth provider used and source_id is unique user identifier that is provided by external service after successful login.

Using tables created above we can generate Auth model. No further adjustments needed.

向控制器添加动作

Next step is to add [[yii\authclient\AuthAction]] to a web controller and provide a successCallback implementation, which is suitable for your needs. Typically, final controller code may look like following:

use app\components\AuthHandler;

class SiteController extends Controller
{
    public function actions()
    {
        return [
            'auth' => [
                'class' => 'yii\authclient\AuthAction',
                'successCallback' => [$this, 'onAuthSuccess'],
            ],
        ];
    }

    public function onAuthSuccess($client)
    {
        (new AuthHandler($client))->handle();
    }
}

Note that it’s important for auth action to be public accessible, so make sure it’s not denied by access control filter.

Where AuthHandler implementation could be like this:

<?php
namespace app\components;

use app\models\Auth;
use app\models\User;
use Yii;
use yii\authclient\ClientInterface;
use yii\helpers\ArrayHelper;

/**
 * AuthHandler handles successful authentication via Yii auth component
 */
class AuthHandler
{
    /**
     * @var ClientInterface
     */
    private $client;

    public function __construct(ClientInterface $client)
    {
        $this->client = $client;
    }

    public function handle()
    {
        $attributes = $this->client->getUserAttributes();
        $email = ArrayHelper::getValue($attributes, 'email');
        $id = ArrayHelper::getValue($attributes, 'id');
        $nickname = ArrayHelper::getValue($attributes, 'login');

        /* @var Auth $auth */
        $auth = Auth::find()->where([
            'source' => $this->client->getId(),
            'source_id' => $id,
        ])->one();

        if (Yii::$app->user->isGuest) {
            if ($auth) { // login
                /* @var User $user */
                $user = $auth->user;
                $this->updateUserInfo($user);
                Yii::$app->user->login($user, Yii::$app->params['user.rememberMeDuration']);
            } else { // signup
                if ($email !== null && User::find()->where(['email' => $email])->exists()) {
                    Yii::$app->getSession()->setFlash('error', [
                        Yii::t('app', "User with the same email as in {client} account already exists but isn't linked to it. Login using email first to link it.", ['client' => $this->client->getTitle()]),
                    ]);
                } else {
                    $password = Yii::$app->security->generateRandomString(6);
                    $user = new User([
                        'username' => $nickname,
                        'github' => $nickname,
                        'email' => $email,
                        'password' => $password,
                        // 'status' => User::STATUS_ACTIVE // make sure you set status properly
                    ]);
                    $user->generateAuthKey();
                    $user->generatePasswordResetToken();

                    $transaction = User::getDb()->beginTransaction();

                    if ($user->save()) {
                        $auth = new Auth([
                            'user_id' => $user->id,
                            'source' => $this->client->getId(),
                            'source_id' => (string)$id,
                        ]);
                        if ($auth->save()) {
                            $transaction->commit();
                            Yii::$app->user->login($user, Yii::$app->params['user.rememberMeDuration']);
                        } else {
                            Yii::$app->getSession()->setFlash('error', [
                                Yii::t('app', 'Unable to save {client} account: {errors}', [
                                    'client' => $this->client->getTitle(),
                                    'errors' => json_encode($auth->getErrors()),
                                ]),
                            ]);
                        }
                    } else {
                        Yii::$app->getSession()->setFlash('error', [
                            Yii::t('app', 'Unable to save user: {errors}', [
                                'client' => $this->client->getTitle(),
                                'errors' => json_encode($user->getErrors()),
                            ]),
                        ]);
                    }
                }
            }
        } else { // user already logged in
            if (!$auth) { // add auth provider
                $auth = new Auth([
                    'user_id' => Yii::$app->user->id,
                    'source' => $this->client->getId(),
                    'source_id' => (string)$attributes['id'],
                ]);
                if ($auth->save()) {
                    /** @var User $user */
                    $user = $auth->user;
                    $this->updateUserInfo($user);
                    Yii::$app->getSession()->setFlash('success', [
                        Yii::t('app', 'Linked {client} account.', [
                            'client' => $this->client->getTitle()
                        ]),
                    ]);
                } else {
                    Yii::$app->getSession()->setFlash('error', [
                        Yii::t('app', 'Unable to link {client} account: {errors}', [
                            'client' => $this->client->getTitle(),
                            'errors' => json_encode($auth->getErrors()),
                        ]),
                    ]);
                }
            } else { // there's existing auth
                Yii::$app->getSession()->setFlash('error', [
                    Yii::t('app',
                        'Unable to link {client} account. There is another user using it.',
                        ['client' => $this->client->getTitle()]),
                ]);
            }
        }
    }

    /**
     * @param User $user
     */
    private function updateUserInfo(User $user)
    {
        $attributes = $this->client->getUserAttributes();
        $github = ArrayHelper::getValue($attributes, 'login');
        if ($user->github === null && $github) {
            $user->github = $github;
            $user->save();
        }
    }
}

successCallback method is called when user was successfully authenticated via external service. Via $client instance we can retrieve information received. In our case we’d like to:

• If user is guest and record found in auth then log this user in.
• If user is guest and record not found in auth then create new user and make a record in auth table. Then log in.
• If user is logged in and record not found in auth then try connecting additional account (save its data into auth table).

Note: different Auth clients may require different approaches while handling authentication success. For example: Twitter does not allow returning of the user email, so you have to deal with this somehow.

认证客户端基本结构

Although, all clients are different they share same basic interface [[yii\authclient\ClientInterface]], which governs 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 and Google Hybrid have same named “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. Note that for each provider fields available may vary in both existence and names.

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.

Tip: If you are using several clients, you can unify the structure of the attributes, which they return, using [[yii\authclient\BaseClient::$normalizeUserAttributeMap]].

添加小部件到登录视图

There’s ready to use [[yii\authclient\widgets\AuthChoice]] widget to use in views:

<?= yii\authclient\widgets\AuthChoice::widget([
     'baseAuthUrl' => ['site/auth'],
     'popupMode' => false,
]) ?>

GitHub 客户端的注意事项

Recently due to potential changes in GitHub callback handling, ensure that authclient=github is present in URL query param in Authorization Callback URL to avoid 404 error thrown when GitHub redirects user back to our app.

Example: Let’s say my app is at https://example.com. In order to implement “Login with GitHub” feature into my app, I will create a new Oauth app for my example.com at github.com/settings/applications/n.... In input field “Authorization callback URL” if I put https://example.com/site/auth, then I will get 404 error thrown by run() method. In order to fix this issue, above query param is required. So putting the “Authorization callback URL” value to https://example.com/site/auth?authclient=github is required.

通过额外 API 调用获得附加数据

Both [[\yii\authclient\OAuth1]] and [[\yii\authclient\OAuth2]] provide method api(), which can be used to access external auth provider REST API.

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');

Method [[\yii\authclient\BaseOAuth::api()]] is very basic and does not provide enough flexibility required for some API commands. You may use [[\yii\authclient\BaseOAuth::createApiRequest()]] instead - it will create an instance of [[\yii\httpclient\Request]], which allows much more control over HTTP request composition. For example:

/* @var $client \yii\authclient\OAuth2 */
$client = Yii::$app->authClientCollection->getClient('someOAuth2');

// find user to add to external service:
$user = User::find()->andWhere(['email' => 'johndoe@domain.com'])->one();

$response = $client->createApiRequest()
    ->setMethod('GET')
    ->setUrl('users')
    ->setData([
        'id' => $user->id,
    ])
    ->send();

if ($response->statusCode != 404) {
    throw new \Exception('User "johndoe@domain.com" already exist');
}

$response = $client->createApiRequest()
    ->setMethod('PUT')
    ->setUrl('users')
    ->setData($user->attributes)
    ->addHeaders([
        'MyHeader' => 'my-value'
    ])
    ->send();

if (!$response->isOk) {
    // failure
}
echo $response->data['id'];

Please refer to yii2-httpclient documentation for details about HTTP request sending.

Request created via [[\yii\authclient\BaseOAuth::createApiRequest()]] will be automatically signed up (in case of OAuth 1.0 usage) and have access token applied before being sent. If you wish to gain full control over these processes, you should use [[\yii\authclient\BaseClient::createRequest()]] instead. You may use [[\yii\authclient\BaseOAuth::applyAccessTokenToRequest()]] and [[yii\authclient\OAuth1::signRequest()]] method to perform missing actions for the API request. For example:

/* @var $client \yii\authclient\OAuth1 */
$client = Yii::$app->authClientCollection->getClient('someOAuth1');

$request = $client->createRequest()
    ->setMethod('GET')
    ->setUrl('users');

$client->applyAccessTokenToRequest($request, $myAccessToken); // use custom access token for API
$client->signRequest($request, $myAccessToken); // sign request with custom access token

$response = $request->send();

自定义认证客户端

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
{
    protected function defaultName()
    {
        return 'my_auth_client';
    }

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

    protected function defaultViewOptions()
    {
        return [
            'popupWidth' => 800,
            'popupHeight' => 500,
        ];
    }
}

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

OpenId

All you need is to specify auth URL, by redeclaring [[yii\authclient\OpenId::authUrl|authUrl]] field. You may also setup default required and/or optional attributes. For example:

use yii\authclient\OpenId;

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

    public $requiredAttributes = [
        'contact/email',
    ];

    public $optionalAttributes = [
        'namePerson/first',
        'namePerson/last',
    ];
}

OAuth2

You will need to specify:

• Auth URL by redeclaring [[yii\authclient\OAuth2::authUrl|authUrl]] field.
• Token request URL by redeclaring [[yii\authclient\OAuth2::tokenUrl|tokenUrl]] field.
• API base URL by redeclaring [[yii\authclient\OAuth2::apiBaseUrl|apiBaseUrl]] field.
• User attribute fetching strategy by redeclaring [[yii\authclient\OAuth2::initUserAttributes()|initUserAttributes()]] method.

For example:

use yii\authclient\OAuth2;

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

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

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

    protected function initUserAttributes()
    {
        return $this->api('userinfo', 'GET');
    }
}

You may also specify default auth scopes.

Note: Some OAuth providers may not follow OAuth standards clearly, introducing differences, and may require additional efforts to implement clients for.

OAuth1

You will need to specify:

• Auth URL by redeclaring [[yii\authclient\OAuth1::authUrl|authUrl]] field.
• Request token URL by redeclaring [[yii\authclient\OAuth1::requestTokenUrl|requestTokenUrl]] field.
• Access token URL by redeclaring [[yii\authclient\OAuth1::accessTokenUrl|accessTokenUrl]] field.
• API base URL by redeclaring [[yii\authclient\OAuth1::apiBaseUrl|apiBaseUrl]] field.
• User attribute fetching strategy by redeclaring [[yii\authclient\OAuth1::initUserAttributes()|initUserAttributes()]] method.

For example:

use yii\authclient\OAuth1;

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

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

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

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

    protected function initUserAttributes()
    {
        return $this->api('userinfo', 'GET');
    }
}

You may also specify default auth scopes.

Note: Some OAuth providers may not follow OAuth standards clearly, introducing differences, and may require additional efforts to implement clients for.

OAuth 2.0 直接认证

OAuth’s protocol of 2.0 version allows several additional work flows, which allows direct authentication without visiting OAuth provider website.

Note: the authentication work flows, described in this section, usually are not supported by OAuth provider, because they are less secure than regular one. Make sure your provider does support particular work flow before attempt to use it.

资源所有者密码凭据授予

Resource Owner Password Credentials Grant work flow allows direct user authentication by username/password pair without redirect to OAuth provider website.

You may authenticate user via this work flow using [[\yii\authclient\OAuth2::authenticateUser()]]. For example:

$loginForm = new LoginForm();

if ($loginForm->load(Yii::$app->request->post()) && $loginForm->validate()) {
    /* @var $client \yii\authclient\OAuth2 */
    $client = Yii::$app->authClientCollection->getClient('someOAuth2');

    try {
        // direct authentication via username and password:
        $accessToken = $client->authenticateUser($loginForm->username, $loginForm->password);
    } catch (\Exception $e) {
        // authentication failed, use `$e->getMessage()` for details
    }
    // ...
}

客户端证书授予

Client Credentials Grant work flow authenticates only OAuth client (your application) without any third party (actual user) being involved. It is used, if you need to access only some general API, which is not related to the user.

You may authenticate client only via this work flow using [[\yii\authclient\OAuth2::authenticateClient()]]. For example:

/* @var $client \yii\authclient\OAuth2 */
$client = Yii::$app->authClientCollection->getClient('someOAuth2');

// direct authentication of client only:
$accessToken = $client->authenticateClient();

JWT

JSON Web Token (JWT) work flow allows authentication of the particular account using JSON Web Signature (JWS). The following example allows authentication of Google Service Account:

use yii\authclient\clients\Google;
use yii\authclient\signature\RsaSha;

$oauthClient = new Google();

$accessToken = $oauthClient->authenticateUserJwt(
    'your-service-account-id@developer.gserviceaccount.com',
    [
        'class' => RsaSha::className(),
        'algorithm' => OPENSSL_ALGO_SHA256,
        'privateCertificate' => "-----BEGIN PRIVATE KEY-----   ...   -----END PRIVATE KEY-----\n"
    ]
);

OpenID 连接

This extension provides support for OpenId Connect authentication protocol via [[\yii\authclient\OpenIdConnect]] class.

Application configuration example:

'components' => [
    'authClientCollection' => [
        'class' => 'yii\authclient\Collection',
        'clients' => [
            'google' => [
                'class' => 'yii\authclient\OpenIdConnect',
                'issuerUrl' => 'https://accounts.google.com',
                'clientId' => 'google_client_id',
                'clientSecret' => 'google_client_secret',
                'name' => 'google',
                'title' => 'Google OpenID Connect',
            ],
        ],
    ]
    // ...
]

Authentication workflow is exactly the same as for OAuth2.

Heads up! ‘OpenID Connect’ protocol uses JWS verification for the authentication process securing. You will need to install web-token/jwt-checker, web-token/jwt-key-mgmt, web-token/jwt-signature, web-token/jwt-signature-algorithm-hmac, web-token/jwt-signature-algorithm-ecdsa and web-token/jwt-signature-algorithm-rsa libraries in order to use such verification. These libraries are not required by this extension by default. It can be done via composer:

composer require --prefer-dist "web-token/jwt-checker:>=1.0 <3.0" "web-token/jwt-key-mgmt:>=1.0 <3.0" "web-token/jwt-signature:>=1.0 <3.0" "web-token/jwt-signature-algorithm-hmac:>=1.0 <3.0" "web-token/jwt-signature-algorithm-ecdsa:>=1.0 <3.0" "web-token/jwt-signature-algorithm-rsa:>=1.0 <3.0"

or add

"web-token/jwt-checker": ">=1.0 <3.0",
"web-token/jwt-key-mgmt": ">=1.0  <3.0",
"web-token/jwt-signature": "~1.0 <3.0",
"web-token/jwt-signature-algorithm-hmac": "~1.0  <3.0",
"web-token/jwt-signature-algorithm-ecdsa": "~1.0  <3.0",
"web-token/jwt-signature-algorithm-rsa": "~1.0  <3.0"

to the require section of your composer.json.

Note: if you are using well-trusted ‘OpenID Connect’ provider, you may disable [[\yii\authclient\OpenIdConnect::$validateJws]], making installation of web-token library redundant, however it is not recommended as it violates the protocol specification.

设置 HTTP 客户端

This extension uses yii2-httpclient for HTTP requests. You may need to adjust default HTTP client configuration to be used, for example, in case you need to use special request transport.

Each Auth client has a property httpClient, which can be used to setup HTTP client used by Auth client. For example:

use yii\authclient\Google;

$authClient = new Google([
    'httpClient' => [
        'transport' => 'yii\httpclient\CurlTransport',
    ],
]);

In case you are using [[\yii\authclient\Collection]] component, you can use its property httpClient to setup HTTP client configuration to all internal Auth clients at once. Application configuration example:

return [
    'components' => [
        'authClientCollection' => [
            'class' => 'yii\authclient\Collection',
            // all Auth clients will use this configuration for HTTP client:
            'httpClient' => [
                'transport' => 'yii\httpclient\CurlTransport',
            ],
            'clients' => [
                'google' => [
                    'class' => 'yii\authclient\clients\Google',
                    'clientId' => 'google_client_id',
                    'clientSecret' => 'google_client_secret',
                ],
                'facebook' => [
                    'class' => 'yii\authclient\clients\Facebook',
                    'clientId' => 'facebook_client_id',
                    'clientSecret' => 'facebook_client_secret',
                ],
                // etc.
            ],
        ]
        //...
    ],
    // ...
];

第三方认证客户端

There are more implementations for various clients:

• Instagram
• Weibo, QQ, Wechat
• GitLab
• Spotify
• OIDC

💖喜欢本文档的，欢迎点赞、收藏、留言或转发，谢谢支持！
作者邮箱：zhuzixian520@126.com，github地址：github.com/zhuzixian520