rest-authentication.md 5.47 KB
Newer Older
Qiang Xue committed
1
Authentication
Qiang Xue committed
2
==============
Qiang Xue committed
3

4
Unlike Web applications, RESTful APIs are usually stateless, which means sessions or cookies should not
Qiang Xue committed
5 6 7
be used. Therefore, each request should come with some sort of authentication credentials because
the user authentication status may not be maintained by sessions or cookies. A common practice is
to send a secret access token with each request to authenticate the user. Since an access token
8
can be used to uniquely identify and authenticate a user, **API requests should always be sent
Qiang Xue committed
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
via HTTPS to prevent from man-in-the-middle (MitM) attacks**.

There are different ways to send an access token:

* [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication): the access token
  is sent as the username. This is should only be used when an access token can be safely stored
  on the API consumer side. For example, the API consumer is a program running on a server.
* Query parameter: the access token is sent as a query parameter in the API URL, e.g.,
  `https://example.com/users?access-token=xxxxxxxx`. Because most Web servers will keep query
  parameters in server logs, this approach should be mainly used to serve `JSONP` requests which
  cannot use HTTP headers to send access tokens.
* [OAuth 2](http://oauth.net/2/): the access token is obtained by the consumer from an authorization
  server and sent to the API server via [HTTP Bearer Tokens](http://tools.ietf.org/html/rfc6750),
  according to the OAuth2 protocol.

Yii supports all of the above authentication methods. You can also easily create new authentication methods.

26
To enable authentication for your APIs, do the following steps:
Qiang Xue committed
27

28 29
1. Configure the [[yii\web\User::enableSession|enableSession]] property of the `user` application component to be false.
2. Specify which authentication methods you plan to use by configuring the `authenticator` behavior
Qiang Xue committed
30
   in your REST controller classes.
31
3. Implement [[yii\web\IdentityInterface::findIdentityByAccessToken()]] in your [[yii\web\User::identityClass|user identity class]].
Qiang Xue committed
32

33 34 35 36 37 38 39 40 41 42 43 44 45 46
Step 1 is not required but is recommended for RESTful APIs which should be stateless. When [[yii\web\User::enableSession|enableSession]]
is false, the user authentication status will NOT be persisted across requests using sessions. Instead, authentication
will be performed for every request, which is accomplished by Step 2 and 3.

> Tip: You may configure [[yii\web\User::enableSession|enableSession]] of the `user` application component
  in application configurations if you are developing RESTful APIs in terms of an application. If you develop
  RESTful APIs as a module, you may put the following line in the module's `init()` method, like the following:
> ```php
public function init()
{
    parent::init();
    \Yii::$app->user->enableSession = false;
}
```
Qiang Xue committed
47 48 49 50 51 52 53 54

For example, to use HTTP Basic Auth, you may configure `authenticator` as follows,

```php
use yii\filters\auth\HttpBasicAuth;

public function behaviors()
{
Qiang Xue committed
55 56 57 58 59
    $behaviors = parent::behaviors();
    $behaviors['authenticator'] = [
        'class' => HttpBasicAuth::className(),
    ];
    return $behaviors;
Qiang Xue committed
60 61 62 63 64 65 66 67 68 69 70 71 72
}
```

If you want to support all three authentication methods explained above, you can use `CompositeAuth` like the following,

```php
use yii\filters\auth\CompositeAuth;
use yii\filters\auth\HttpBasicAuth;
use yii\filters\auth\HttpBearerAuth;
use yii\filters\auth\QueryParamAuth;

public function behaviors()
{
Qiang Xue committed
73 74 75 76 77 78 79
    $behaviors = parent::behaviors();
    $behaviors['authenticator'] = [
        'class' => CompositeAuth::className(),
        'authMethods' => [
            HttpBasicAuth::className(),
            HttpBearerAuth::className(),
            QueryParamAuth::className(),
Qiang Xue committed
80
        ],
Qiang Xue committed
81 82
    ];
    return $behaviors;
Qiang Xue committed
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
}
```

Each element in `authMethods` should be an auth method class name or a configuration array.


Implementation of `findIdentityByAccessToken()` is application specific. For example, in simple scenarios
when each user can only have one access token, you may store the access token in an `access_token` column
in the user table. The method can then be readily implemented in the `User` class as follows,

```php
use yii\db\ActiveRecord;
use yii\web\IdentityInterface;

class User extends ActiveRecord implements IdentityInterface
{
    public static function findIdentityByAccessToken($token, $type = null)
    {
        return static::findOne(['access_token' => $token]);
    }
}
```

After authentication is enabled as described above, for every API request, the requested controller
will try to authenticate the user in its `beforeAction()` step.

If authentication succeeds, the controller will perform other checks (such as rate limiting, authorization)
and then run the action. The authenticated user identity information can be retrieved via `Yii::$app->user->identity`.

If authentication fails, a response with HTTP status 401 will be sent back together with other appropriate headers
(such as a `WWW-Authenticate` header for HTTP Basic Auth).


Qiang Xue committed
116
## Authorization <a name="authorization"></a>
Qiang Xue committed
117

Qiang Xue committed
118
After a user is authenticated, you probably want to check if he or she has the permission to perform the requested
Qiang Xue committed
119
action for the requested resource. This process is called *authorization* which is covered in detail in
120
the [Authorization section](security-authorization.md).
Qiang Xue committed
121

Qiang Xue committed
122 123 124
If your controllers extend from [[yii\rest\ActiveController]], you may override
the [[yii\rest\Controller::checkAccess()|checkAccess()]] method to perform authorization check. The method
will be called by the built-in actions provided by [[yii\rest\ActiveController]].