控制访问

通过 IBM Cloud® App ID，您可以定义哪些用户和应用程序可以访问特定功能或在应用程序中执行特定操作。要控制访问权，您可以创建作用域并将其分组为角色。然后，将角色分配给一个或多个应用程序用户和应用程序。

作用域是您向 App ID 注册以创建访问许可权的应用程序中的运行时操作。角色是作用域的集合，用于向不同类型的应用程序用户和应用程序分配不同的许可权。例如，如果您的公司雇佣了开发者，那么他们可能会创建一个允许他们读写代码的角色。如果使用审计员，那么您可能仅具有视图角色，如下图所示。

App ID 访问控制工作流程四步图：将运行时操作注册为作用域、将作用域编译为角色、将角色分配给用户或应用程序、在运行时验证访问令牌中的作用域访问控制的工作原理 — App ID

向 App ID注册可在应用程序中执行的运行时操作。
将作用域编译为组以形成角色。
通过向用户或应用程序分配角色来控制访问许可权。
配置应用程序以验证用户在运行时访问令牌 (或者在应用程序令牌 (如果客户机凭证流)) 中返回的作用域。

有关应用程序的更多信息，请参阅应用程序身份和授权。

准备工作

您必须提出申请。
确保您了解每种类型的角色和作用域如何影响应用程序。因为您授予访问权，所以您希望确保仅向需要访问权的人员授予访问权。
请注意已实施的限制。

在控制台中创建作用域

作用域是应用程序中的运行时操作，被授予完成这些操作所需的许可权的用户可以执行此操作。当您向 App ID注册应用程序时，将创建作用域。如果您的应用程序已注册，那么可以对其进行编辑以包含作用域。

作用域名称的值必须满足以下要求:

为字母数字
小写
不是以 appid 或 openid 开头
不包含除句点 (.) 或下划线 (_) 以外的特殊字符
少于 50 个字符。

要创建作用域，可以使用 App ID UI。

转至 App ID 仪表板中的 应用程序。
单击 添加应用程序 以打开配置屏幕。如果您已有要使用的凭证，请从要更新的行中的“操作”菜单单击编辑。
为应用程序提供名称，然后选择您拥有的应用程序类型。
输入定制作用域的值，然后单击加号 (+)。示例作用域值可以是 read 或 write。
重复上一步，直到将所有作用域添加到应用程序。
单击保存。

使用应用程序接口创建作用域

作用域名称的值必须满足以下要求:

为字母数字
小写
不是以 appid 或 openid 开头
不包含除句点 (.) 或下划线 (_) 以外的特殊字符
少于 50 个字符。

要创建作用域，可以使用 App ID UI。

通过向 /scopes 端点发出以下请求来创建作用域。

curl -X PUT "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/applications/<clientID>/scopes"
-H "accept: application/json"
-H "Content-Type: application/json"
-d "{\ "scopes":\ [\ <scopesObject>}" ]}"

变量	描述
`region`	供应 App ID 实例的区域。了解有关可用区域的更多信息。
`tenantID`	App ID 实例的唯一标识。您可以在服务仪表板的应用程序选项卡中列出的应用程序凭证中找到此值。
`clientID`	应用程序的唯一标识符。您可以在应用程序的凭证中找到此值，因为这些凭证在服务仪表板的应用程序中列出。
`scopesObject`	要为应用程序创建的所有作用域的 JSON 对象。
{: caption="调用 `/scopes` 端点所需的变量" caption-side="top"}

可选: 确认已创建作用域。

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/applications/<clientID>/scopes"
-H "accept: application/json"
-H "Content-Type: application/json"

在控制台中创建角色

角色是应用于同一类型用户的作用域组。例如，如果创建管理员角色，那么作用域部分可能允许该角色执行读，写或创建操作。但是，如果您创建另一个名为 viewer 的角色，那么分配有该角色的用户将具有只读访问权。要创建角色，可以使用 App ID UI。

转至 App ID 仪表板中的 个人档案和角色> 角色。
单击 创建角色 以打开配置屏幕。
为角色提供名称和描述。
通过使用您在先前部分中创建的作用域，使用以下格式将作用域分配给角色。单击 + 以添加作用域。
```
<appName>/<scope>
```
如果只有一个应用程序，那么不需要指定应用程序名称。您可以单独添加作用域。
重复上一步以添加更多作用域。
单击保存。

使用应用程序接口创建角色

角色是应用于同一类型用户的作用域组。例如，如果创建管理员角色，那么作用域部分可能允许该角色执行读，写或创建操作。但是，如果创建另一个名为 viewer 的角色，那么被分配该角色的用户将具有只读访问权。要创建角色，可以使用 App ID API。

向 /roles 端点发出请求以创建角色。

curl -X POST "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles"
-H "accept: application/json"
-H "Content-Type: application/json"
-d { \"name\": \"<roleName>\", \"description\": \"<roleDescription>\", \"access\": [ { \"application_id\": \"<applicationID>\", \"scopes\": [ \"<scopes>" ] } ]}"

变量	描述
`region`	供应 App ID 实例的区域。了解有关可用区域的更多信息。
`tenantID`	App ID 实例的唯一标识。您可以在服务仪表板的应用程序选项卡中列出的应用程序凭证中找到此值。
`clientID`	应用程序的唯一标识符。您可以在应用程序中列出的应用程序凭证中找到此值。
`roleName`	要分配给角色的名称。
`roleDescription`	描述您的角色要执行的操作的简短短语。
`applicationID`	应用程序的唯一标识符。您可以在应用程序中列出的应用程序凭证中找到此值。
`scopes`	要应用于角色的所有作用域的 JSON 对象。
{: caption="调用 `/scopes` 端点所需的变量" caption-side="top"}

可选: 确认已创建角色。

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles -H "accept: application/json"

回复与下面的示例相似：

{
   "roles": [
   {
      "id": "12345678-1234-1234-1234-123456789012",
      "name": "admin",
      "description": "Can perform administrative tasks.",
      "access": [
         {
         "application_id": "de33d272-f8a7-4406-8fe8-ab28fd457be5",
         "scopes": [
            "create",
            "update",
            "write",
            "read"
         ]
         }
      ]
   }
   {
      "id": "123454231-1234-1234-3334-12345687012",
      "name": "developer",
      "description": "Can perform administrative tasks.",
      "access": [
         {
         "application_id": "de33d272-f8a7-4406-8fe8-ab28fd457be5",
         "scopes": [
            "write",
            "read"
         ]
         }
      ]
   }
   ]
}

在控制台中为用户分配角色

创建角色后，可以将其分配给用户的概要文件。您还可以在创建未来用户时分配角色。

转至 App ID 仪表板中的 个人档案和角色> 用户个人档案。
从要向其分配角色的特定用户的行中的“操作”菜单，单击 分配角色。
从可用角色列表中选择要添加的一个或多个角色。
可选: 如果未看到要查找的角色，请单击 创建角色 并提供信息以添加另一个选项。
单击保存。

使用 API 向用户分配角色

创建角色后，可以将其分配给用户的概要文件。您还可以在创建未来用户时分配角色。

通过使用标识查询 (例如电子邮件地址) 搜索 App ID 用户来获取用户标识。

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/Users?query=<identifyingSearchQuery>" \
-H "accept: application/json" \
-H "authorization: Bearer <token>"

示例：

curl -X GET https://us-south.appid.cloud.ibm.com/management/v4/e19a2778-3262-4986-8875-8khjafsdkhjsdafkjh/cloud_directory/Users?query=example@domain.com
-H "accept: application/json"
-H "authorization: Bearer eyJraWQiOiIyMDE3MTEyOSIsImFsZ...."

可选: 获取角色标识或角色名称。如果您已知道自己的角色标识或名称，请跳至下一步。

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles" \
-H "accept: application/json" \
-H "authorization: Bearer <token>"

向包含要分配的角色的 JSON 对象的 /roles 端点发出请求。

curl -X PUT "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/users/<userID>/roles"
-H "accept: application/json"
-H "Content-Type: application/json"
-d "{ \"roles\": { \"ids\": [ \"<roleIDs>\" ] }}"
-H "authorization: Bearer <token>"

要从用户中除去角色，请再次发出 PUT 请求，但除去角色标识。

向令牌添加用户角色

缺省情况下，不会在用户令牌中返回角色。建议根据作用域配置运行时决策。但是，如果要使用角色，可以使用定制声明映射将其映射到令牌。

认证时，请确保将 username : client ID 和 password : secret 用于您为其配置了控件的应用程序和用户。

向应用程序分配角色

创建角色后，可以使用 App ID API 将其分配给应用程序。

应用程序角色仅在客户机凭证流中有效。

通过查询应用程序列表来获取应用程序客户机标识。您还可以从 App ID UI 的 应用程序 选项卡获取此值。

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/applications" \
-H "accept: application/json" \
-H "authorization: Bearer <token>"

示例：

curl -X GET https://us-south.appid.cloud.ibm.com/management/v4/e19a2778-3262-4986-8875-8khjafsdkhjsdafkjh/applications
-H "accept: application/json"
-H "authorization: Bearer eyJraWQiOiIyMDE3MTEyOSIsImFsZ...."

获取角色标识。

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles" \
-H "accept: application/json" \
-H "authorization: Bearer <token>"

向包含要分配的角色的 JSON 对象的 /roles 端点发出请求。此请求将当前角色替换为提供的角色标识。请确保分配正确的角色。

curl -X PUT "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/applications/<clientID>/roles"
-H "accept: application/json"
-H "Content-Type: application/json"
-d "{ \"roles\": { \"ids\": [ \"<roleIDs>\" ] }}"
-H "authorization: Bearer <token>"

要从用户中除去角色，请再次发出 PUT 请求，但除去角色标识。

在运行时控制访问权

当用户或应用程序尝试访问其中一个受保护资源时，App ID将创建并返回令牌。将在访问令牌中返回分配给用户或应用程序的任何作用域。您可以使用访问令牌在运行时进行决策。根据您用于保护应用程序的策略，如何验证作用域可能有所不同。

使用 Web 应用程序策略时

您可以使用 Web 应用程序策略通过使用 hasScope 方法来检查请求是否包含任何作用域。当具有已分配角色的用户登录时，将通过包含角色中定义的所有作用域的 App ID 令牌授予他们访问权。例如，如果您正在使用 Node.js SDK，那么代码片段将类似于以下内容:

app.get("/protected", passport.authenticate(WebAppStrategy.STRATEGY_NAME), function(req, res){
    if(WebAppStrategy.hasScope(req, "read write")){
              res.json(req.user);
    }
    else {
        res.send("insufficient scopes");
    }
});

使用 API 策略时

您可以通过向 API 策略代码添加作用域变量来定义访问特定端点所需的作用域。例如，如果您有一个使用 Node.js 编写的应用程序，并且您正在使用 Node.js SDK，那么代码片段可能类似于以下内容。

app.get("/api/protected",
        passport.authenticate(APIStrategy.STRATEGY_NAME, {
                audience: "myApp",
                scope: "read write update"
        }),
        function(req, res) {
                res.send("Hello from protected resource");
        }
);

了解 API 策略中使用的变量
变量	描述
`scope`	必需的作用域，以空格分隔。
`audience`	应用程序客户机标识。

除去访问权

您可以删除不再需要的任何作用域或角色。

在控制台中删除作用域

如果不再需要作用域，那么可以使用 App ID UI 将其删除。

删除作用域时，将从与其关联的所有角色中除去该作用域。

您可以使用 App ID 服务仪表板来删除作用域。

转至 App ID 仪表板中的 应用程序。
从要编辑其作用域的应用程序行中的“操作”菜单，单击编辑。
单击要除去的作用域的框中的 X。
单击保存。

使用应用程序接口删除作用域

如果不再需要作用域，可以使用 App ID API 将其删除。要删除作用域，请将其从 JSON 对象中除去，并向 /scopes 端点发出新的 PUT 请求。

删除作用域时，将从与其关联的所有角色中除去该作用域。

通过对 /scopes 端点的以下请求来更改或删除作用域。请确保更新作用域 JSON 对象以仅包含要允许的作用域。

curl -X PUT "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/applications/<clientID>/scopes"
-H "accept: application/json"
-H "Content-Type: application/json"
-d "{\ "scopes":\ [\ <scopesObject>" ]}"

在控制台中删除角色

如果不再需要特定角色，可以使用 App ID UI 将其删除。

删除角色将从当前正在使用该角色的所有用户和应用程序中除去访问权。

转至服务仪表板中的 个人档案和角色> 角色。
在要删除的角色所在的行中，从“操作”菜单中选择删除。
确认您了解删除角色会影响当前正在使用该角色的所有用户和应用程序。
单击删除。

使用应用程序接口删除角色

如果不再需要特定角色，那么可以使用 App ID API 将其删除。

删除角色将从当前正在使用该角色的所有用户和应用程序中除去访问权。

获取角色标识或角色名称。如果您已知道自己的角色标识或名称，请跳至下一步。

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles"
-H "accept: application/json"

向包含要分配的角色的 JSON 对象的 /roles 端点发出请求。

curl -X DELETE "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles/<roleID>"
-H "accept: application/json"