文字
分享

授权认证

认证

和Web应用不同,RESTful APIs 通常是无状态的,也就意味着不应使用sessions 或 cookies, 因此每个请求应附带某种授权凭证,因为用户授权状态可能没通过sessions 或 cookies维护, 常用的做法是每个请求都发送一个秘密的access token来认证用户,由于access token可以唯一识别和认证用户, API 请求应通过HTTPS来防止man-in-the-middle (MitM) 中间人攻击.

下面有几种方式来发送access token:

  • HTTP 基本认证: access token 当作用户名发送,应用在access token可安全存在API使用端的场景,例如,API使用端是运行在一台服务器上的程序。
  • 请求参数: access token 当作API URL请求参数发送,例如 https://example.com/users?access-token=xxxxxxxx,由于大多数服务器都会保存请求参数到日志, 这种方式应主要用于JSONP 请求,因为它不能使用HTTP头来发送access token
  • OAuth 2: 使用者从认证服务器上获取基于OAuth2协议的access token,然后通过 HTTP Bearer Tokens 发送到API 服务器。

Yii 支持上述的认证方式,你也可很方便的创建新的认证方式。

为你的APIs启用认证,做以下步骤:

  1. 配置user 应用组件:
    • 设置 yii\web\User::enableSession 属性为 false.
    • 设置 yii\web\User::loginUrl 属性为null 显示一个HTTP 403 错误而不是跳转到登录界面.
  2. 在你的REST 控制器类中配置authenticator 行为来指定使用哪种认证方式
  3. 在你的yii\web\User::identityClass 类中实现 yii\web\IdentityInterface::findIdentityByAccessToken() 方法.

步骤1不是必要的,但是推荐配置,因为RESTful APIs应为无状态的,当yii\web\User::enableSession为false, 请求中的用户认证状态就不能通过session来保持,每个请求的认证通过步骤2和3来实现。

提示: 如果你将RESTful APIs作为应用开发,可以设置应用配置中 user 组件的yii\web\User::enableSession, 如果将RESTful APIs作为模块开发,可以在模块的 init() 方法中增加如下代码,如下所示:

1

2

3

4

5

<code style="box-sizing: border-box; font-family: Menlo, Monaco, Consolas, 'Courier New', monospace; font-size: inherit; padding: 0px; color: inherit; border-radius: 0px; white-space: pre-wrap; background-color: transparent;"><span style="box-sizing: border-box;">public</span> <span style="box-sizing: border-box;"><span style="box-sizing: border-box;">function</span> <span style="box-sizing: border-box;">init</span><span style="box-sizing: border-box;">()</span></span>{

    <span style="box-sizing: border-box;">parent</span>::init();

    \Yii::<span style="box-sizing: border-box;">$app</span>->user->enableSession = <span style="box-sizing: border-box;">false</span>;

}

</code>

例如,为使用HTTP Basic Auth,可配置authenticator 行为,如下所示:

1

2

3

4

5

6

7

8

9

10

<code style="box-sizing: border-box; font-family: Menlo, Monaco, Consolas, 'Courier New', monospace; font-size: inherit; padding: 0px; color: inherit; border-radius: 0px; white-space: pre-wrap; background-color: transparent;"><span style="box-sizing: border-box;">use</span> <span style="box-sizing: border-box;">yii</span>\<span style="box-sizing: border-box;">filters</span>\<span style="box-sizing: border-box;">auth</span>\<span style="box-sizing: border-box;">HttpBasicAuth</span>;

 

<span style="box-sizing: border-box;">public</span> <span style="box-sizing: border-box;"><span style="box-sizing: border-box;">function</span> <span style="box-sizing: border-box;">behaviors</span><span style="box-sizing: border-box;">()</span></span>{

    <span style="box-sizing: border-box;">$behaviors</span> = <span style="box-sizing: border-box;">parent</span>::behaviors();

    <span style="box-sizing: border-box;">$behaviors</span>[<span style="box-sizing: border-box;">'authenticator'</span>] = [

        <span style="box-sizing: border-box;">'class'</span> => HttpBasicAuth::className(),

    ];

    <span style="box-sizing: border-box;">return</span> <span style="box-sizing: border-box;">$behaviors</span>;

}

</code>

如果你系那个支持以上3个认证方式,可以使用CompositeAuth,如下所示:

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

<code style="box-sizing: border-box; font-family: Menlo, Monaco, Consolas, 'Courier New', monospace; font-size: inherit; padding: 0px; color: inherit; border-radius: 0px; white-space: pre-wrap; background-color: transparent;"><span style="box-sizing: border-box;">use</span> <span style="box-sizing: border-box;">yii</span>\<span style="box-sizing: border-box;">filters</span>\<span style="box-sizing: border-box;">auth</span>\<span style="box-sizing: border-box;">CompositeAuth</span>;

<span style="box-sizing: border-box;">use</span> <span style="box-sizing: border-box;">yii</span>\<span style="box-sizing: border-box;">filters</span>\<span style="box-sizing: border-box;">auth</span>\<span style="box-sizing: border-box;">HttpBasicAuth</span>;

<span style="box-sizing: border-box;">use</span> <span style="box-sizing: border-box;">yii</span>\<span style="box-sizing: border-box;">filters</span>\<span style="box-sizing: border-box;">auth</span>\<span style="box-sizing: border-box;">HttpBearerAuth</span>;

<span style="box-sizing: border-box;">use</span> <span style="box-sizing: border-box;">yii</span>\<span style="box-sizing: border-box;">filters</span>\<span style="box-sizing: border-box;">auth</span>\<span style="box-sizing: border-box;">QueryParamAuth</span>;

 

<span style="box-sizing: border-box;">public</span> <span style="box-sizing: border-box;"><span style="box-sizing: border-box;">function</span> <span style="box-sizing: border-box;">behaviors</span><span style="box-sizing: border-box;">()</span></span>{

    <span style="box-sizing: border-box;">$behaviors</span> = <span style="box-sizing: border-box;">parent</span>::behaviors();

    <span style="box-sizing: border-box;">$behaviors</span>[<span style="box-sizing: border-box;">'authenticator'</span>] = [

        <span style="box-sizing: border-box;">'class'</span> => CompositeAuth::className(),

        <span style="box-sizing: border-box;">'authMethods'</span> => [

            HttpBasicAuth::className(),

            HttpBearerAuth::className(),

            QueryParamAuth::className(),

        ],

    ];

    <span style="box-sizing: border-box;">return</span> <span style="box-sizing: border-box;">$behaviors</span>;

}

</code>

authMethods 中每个单元应为一个认证方法名或配置数组。

findIdentityByAccessToken()方法的实现是系统定义的, 例如,一个简单的场景,当每个用户只有一个access token, 可存储access token 到user表的access_token列中, 方法可在User类中简单实现,如下所示:

1

2

3

4

5

6

7

8

9

10

<code style="box-sizing: border-box; font-family: Menlo, Monaco, Consolas, 'Courier New', monospace; font-size: inherit; padding: 0px; color: inherit; border-radius: 0px; white-space: pre-wrap; background-color: transparent;"><span style="box-sizing: border-box;">use</span> <span style="box-sizing: border-box;">yii</span>\<span style="box-sizing: border-box;">db</span>\<span style="box-sizing: border-box;">ActiveRecord</span>;

<span style="box-sizing: border-box;">use</span> <span style="box-sizing: border-box;">yii</span>\<span style="box-sizing: border-box;">web</span>\<span style="box-sizing: border-box;">IdentityInterface</span>;

 

<span style="box-sizing: border-box;"><span style="box-sizing: border-box;">class</span> <span style="box-sizing: border-box;">User</span> <span style="box-sizing: border-box;">extends</span> <span style="box-sizing: border-box;">ActiveRecord</span> <span style="box-sizing: border-box;">implements</span> <span style="box-sizing: border-box;">IdentityInterface</span></span>{

    <span style="box-sizing: border-box;">public</span> <span style="box-sizing: border-box;">static</span> <span style="box-sizing: border-box;"><span style="box-sizing: border-box;">function</span> <span style="box-sizing: border-box;">findIdentityByAccessToken</span><span style="box-sizing: border-box;">(<span style="box-sizing: border-box;">$token</span>, <span style="box-sizing: border-box;">$type</span> = null)</span>

    </span>{

        <span style="box-sizing: border-box;">return</span> <span style="box-sizing: border-box;">static</span>::findOne([<span style="box-sizing: border-box;">'access_token'</span> => <span style="box-sizing: border-box;">$token</span>]);

    }

}

</code>

在上述认证启用后,对于每个API请求,请求控制器都会在它的beforeAction()步骤中对用户进行认证。

如果认证成功,控制器再执行其他检查(如频率限制,操作权限),然后再执行操作, 授权用户信息可使用Yii::$app->user->identity获取.

如果认证失败,会发送一个HTTP状态码为401的响应,并带有其他相关信息头(如HTTP 基本认证会有WWW-Authenticate 头信息).

授权

在用户认证成功后,你可能想要检查他是否有权限执行对应的操作来获取资源,这个过程称为 authorization , 详情请参考 Authorization section.

如果你的控制器从yii\rest\ActiveController类继承,可覆盖 yii\rest\Controller::checkAccess() 方法 来执行授权检查,该方法会被yii\rest\ActiveController内置的操作调用。