security-authentication.md 3.03 KB
Newer Older
1 2 3
Authentication
==============

4
> Note: This section is under development.
Qiang Xue committed
5

Larry Ullman committed
6
Authentication is the act of verifying who a user is, and is the basis of the login process. Typically, authentication uses the combination of an identifier--a username or email address--and a password. The user submits these values  through a form, and the application then compares the submitted information against that previously stored (e.g., upon registration).
7

8
In Yii, this entire process is performed semi-automatically, leaving the developer to merely implement [[yii\web\IdentityInterface]], the most important class in the authentication system. Typically, implementation of `IdentityInterface` is accomplished using the `User` model.
Larry Ullman committed
9

Qiang Xue committed
10
You can find a fully featured example of authentication in the
Alexander Makarov committed
11
[advanced application template](tutorial-advanced-app.md). Below, only the interface methods are listed:
12 13 14 15

```php
class User extends ActiveRecord implements IdentityInterface
{
16
    // ...
17

18 19 20 21 22 23 24 25
    /**
     * Finds an identity by the given ID.
     *
     * @param string|integer $id the ID to be looked for
     * @return IdentityInterface|null the identity object that matches the given ID.
     */
    public static function findIdentity($id)
    {
Alexander Makarov committed
26
        return static::findOne($id);
27
    }
28

29 30 31 32 33 34
    /**
     * Finds an identity by the given token.
     *
     * @param string $token the token to be looked for
     * @return IdentityInterface|null the identity object that matches the given token.
     */
35
    public static function findIdentityByAccessToken($token, $type = null)
36
    {
Alexander Makarov committed
37
        return static::findOne(['access_token' => $token]);
38
    }
Qiang Xue committed
39

40 41 42 43 44 45 46
    /**
     * @return int|string current user ID
     */
    public function getId()
    {
        return $this->id;
    }
47

48 49 50 51 52 53 54
    /**
     * @return string current user auth key
     */
    public function getAuthKey()
    {
        return $this->auth_key;
    }
55

56 57 58 59 60 61 62 63
    /**
     * @param string $authKey
     * @return boolean if auth key is valid for current user
     */
    public function validateAuthKey($authKey)
    {
        return $this->getAuthKey() === $authKey;
    }
64 65 66
}
```

67 68 69 70 71
Two of the outlined methods are simple: `findIdentity` is provided with an  ID value and returns a model instance
associated with that ID. The `getId` method returns the ID itself. Two of the other methods – `getAuthKey` and
`validateAuthKey` – are used to provide extra security to the "remember me" cookie. The `getAuthKey` method should
return a string that is unique for each user. You can reliably create a unique string using
`Yii::$app->getSecurity()->generateRandomString()`. It's a good idea to also save this as part of the user's record:
72 73 74 75

```php
public function beforeSave($insert)
{
76 77
    if (parent::beforeSave($insert)) {
        if ($this->isNewRecord) {
78
            $this->auth_key = Yii::$app->getSecurity()->generateRandomString();
79 80 81 82
        }
        return true;
    }
    return false;
83 84 85
}
```

86
The `validateAuthKey` method just needs to compare the `$authKey` variable, passed as a parameter (itself retrieved from a cookie), with the value fetched from the database.