IBM Cloud Identity and Access Management

• 跨 IBM Cloud 集中管理访问管理。
• 允许用户或服务使用同一组凭证（例如，相同的用户名和密码或IAM API密钥）访问许多不同的资源。
• 可以授予 IAM API 密钥对帐户管理功能（例如，创建新数据库）的访问权。

IBM Cloudant 旧访问控制

• 对 IBM Cloudant 唯一。
• 对每个服务实例的访问都需要该服务自己的一组凭证。
• 将 HTTP 基本认证与未绑定到单个用户或服务的凭证配合使用。
• IBM Cloudant API密钥只能在数据库级别授予权限。

API 密钥说明

在本文档中，凡是提到 API 密钥的地方，都是指 IAM API 密钥。 IBM Cloudant 旧访问控制还具有 API 密钥概念，有关 IBM Cloudant 旧凭证或用户名和密码组合的任何讨论也包含 IBM Cloudant API 密钥。

IBM Cloudant API密钥，仅限于IAM用户使用

可以将 IBM Cloudant API 密钥与 IAM 一起使用，但建议不要这样做。 提出这一建议是因为 通过使用 IAM 策略接口，IBM Cloudant API 密钥和许可权不可见或不可管理，导致无法进行整体访问管理。

仅使用IAM 或同时使用旧凭据和IAM 会影响以下因素：

1. 旧 IBM Cloudant 帐户级凭证是否可用于管理数据库和其他帐户级别的操作。
2. 在服务凭证生成期间传递的凭证的样式。

尤其是，IBM Cloudant API 密钥仍可用于管理数据库访问。 必须使用 HTTP API 来生成和配置这些凭证。

使用命令行进行供应

当您从命令行配置新的 IBM Cloudant 实例时，请向 ibmcloud 工具提供一个选项，使用 -p 参数启用或禁用帐户的旧凭据。 该选项以 JSON 格式传递，名为 legacyCredentials。

要以仅使用 IAM（建议）方式供应实例，请运行以下命令：

ibmcloud resource service-instance-create  "Instance Name" \
    cloudantnosqldb Standard us-south \
    -p {"legacyCredentials": false}

使用 Manager 以外的 IAM 角色 (例如 Reader，Writer，Monitor 或 Checkpointer) 时，必须 使用 仅使用 IAM 以避免向用户提供包含更大访问许可权的旧凭证。

要以同时使用旧凭证和 IAM 方式供应实例，请运行以下命令：

ibmcloud resource service-instance-create  "Instance Name" \
    cloudantnosqldb Standard us-south \
    -p {"legacyCredentials": true}

每个选项的服务凭证 JSON 示例

仅使用IAM 和同时使用传统凭证和IAM 访问控制 之间的选择会影响您在绑定和生成 服务凭证时凭证如何传递到您的应用程序。 在主 IBM Cloud 中生成凭证时 IAM 接口，API 密钥在生成时显示在该接口中。

您还可以通过服务实例的“服务凭证”部分生成凭证。 通过此方法生成服务凭证将创建服务凭证 JSON BLOB，此 BLOB 可以连同访问服务所需的所有详细信息一起粘贴到应用程序中。

接下来，您可以看到服务证书JSON是什么样子，以及 每个值是什么意思。

当您选择仅使用IAM 时，生成的服务凭证仅包含IAM 值，如下例所示。

{
  "apikey": "MxVp86XHkU82Wc97tdvDF8qM8B0Xdit2RqR1mGfVXPWz",
  "iam_apikey_description": "Auto generated apikey during resource-key [...]",
  "iam_apikey_name": "auto-generated-apikey-050d21b5-5f[...]",
  "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Manager",
  "iam_serviceid_crn": "crn:v1:staging:public:iam-identity::[...]",
  "url": "https://76838001-b883-444d-90d0-46f89e942a15-bluemix.cloudant.com",
  "username": "76838001-b883-444d-90d0-46f89e942a15-bluemix"
}

必须使用以下定义来解释先前 JSON 示例中的每个值:

apikey

IAM API 密钥。

iam_apikey_description

IAM API密钥说明。

iam_apikey_name

IAM API密钥的ID。

iam_role_crn

IAM API 密钥具有的 IAM 角色。

iam_serviceid_crn

服务ID的CRN。

url

IBM Cloudant }} 服务URL。

username

内部 IBM Cloudant 帐户名称。

当您选择同时使用旧版凭证和IAM 时，生成的服务凭证将同时包含IAM和旧版凭证，其格式如下例所示。

{
  "apikey": "MxVp86XHkU82Wc97tdvDF8qM8B0Xdit2RqR1mGfVXPWz",
  "host": "76838001-b883-444d-90d0-46f89e942a15-bluemix.cloudant.com",
  "iam_apikey_description": "Auto generated apikey during resource-key [...]",
  "iam_apikey_name": "auto-generated-apikey-050d21b5-5f[...]",
  "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Manager",
  "iam_serviceid_crn": "crn:v1:staging:public:iam-identity::[...]",
  "password": "8fb6a16b48903e87b769e7f4968521e85c2394ed8f0e69b2769e56dcb27d2e76",
  "port": 443,
  "url": "https://<username>:<password>@76838001-b883-444d-90d0-46f89e942a15-bluemix.cloudant.com",
  "username": "apikey-v2-58B528DF5397465BB6673E1B79482A8C"
}

必须使用以下定义来解释先前 JSON 示例中的每个值:

apikey

IAM API 密钥。

host

IBM Cloudant 服务主机名。

iam_apikey_description

IAM API密钥说明。

iam_apikey_name

IAM API密钥的ID。

iam_role_crn

IAM API 密钥具有的 IAM 角色。

iam_serviceid_crn

服务ID的CRN。

password

IBM Cloudant 旧凭证密码。

port

IBM Cloudant 服务端口。

url

IBM Cloudant 服务，包括嵌入的 旧版证书。URL IBM Cloudant

username

IBM Cloudant 旧凭证用户名。

请注意，包含的 username 和 password 始终等同于 IAM 的“管理者”凭证。 因此，与 Reader，Writer，Monitor 或 Checkpointer IAM 角色配合使用时，使用 同时使用旧凭证和 IAM 是不安全的。

两种访问控制机制的优缺点

总体而言，IBM Cloud IAM 是建议的认证模型。 然而，这种方法的主要缺点是，如果您有现有的应用程序 或无法使用 IBM Cloudant 支持的客户端库。

示例

为“源”和“目标”生成 IAM API 密钥，为 IBM Cloudant API 访问权生成一个 IAM API 密钥

在本练习中，将创建前两个 API 密钥，以便这两个实例可以在复制过程中相互交谈。 第三个 API 密钥供用户访问 IBM Cloudant API，创建 _replicator 数据库，然后向其添加复制文档。

遵循以下步骤为 IBM Cloudant生成 IAM API 密钥和 API 访问权。 您必须记下以下步骤中请求的凭证，才能继续执行此示例。

请确保选择指定的实例，即“源”或“目标”。

1. 登录到 cloud.ibm.com。

2. 从“资源”列表中，选择 服务 和源实例。

   1. 点击“服务凭证”，然后点击“新建凭证”。

   2. 将新凭证命名为 replicator-source，然后选择“管理者”角色。

   3. 单击 添加，并记录其 apikey，该位于“操作”列中的“查看凭证”下。

3. 对目标实例重复步骤 2 到 2.c。

   1. 创建具有“管理者”角色的名为 replicator-target 的凭证。

   2. 记下其 IAM API 密钥，该密钥位于“操作”列中的“查看凭证”下。

4. 选择源实例，然后单击 服务凭证 和 新建凭证。

   1. 将新凭证命名为 apiaccess，然后选择“管理者”角色。

   2. 记下“操作”列中“查看凭证”下的实际 IAM API 密钥。

5. 记录源和目标实例 URL。

根据工作流程，您可以使用个人 IAM API 密钥，而不是创建服务级别凭证 (步骤 4)，如 创建 API 密钥中所述。

您还可以使用 IBM Cloud CLI 工具链在命令行上完成这些步骤。

生成不记名令牌以针对 IBM Cloudant API 进行认证

在步骤 4.b中，您写下了 apiaccess 键。 立即使用该密钥:

curl -k -X POST \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "Accept: application/json" \
  --data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
  --data-urlencode "apikey=aSCsx4...2lN97h_2Ts" \
  "https://iam.cloud.ibm.com/identity/token"

apiaccess 键返回以下信息 (缩写):

{
   "access_token": "eyJraWQiOiIyMDE5MD...tIwkCO9A",
   "refresh_token": "ReVbNrHo3UA38...mq67g",
   "token_type": "Bearer",
   "expires_in": 3600,
   "expiration": 1566313064,
   "scope": "ibm openid"
}

创建环境变量以通过在响应数据中使用 access_token 键下的值来保存某些类型:

export TOK="Bearer eyJraWQiOiIyMDE5MD...tIwkCO9A"

在源端创建 _replicator 数据库

URL 是您之前在4.b中记录的URL。

curl -k -X PUT \
     -H"Content-type: application/json" \
     -H'Authorization: '"$TOK"'' \
     'https://d43caf1b-e2c8-4d3e-9b85-1d04839fa68f-bluemix.cloudant.com/_replicator'

请参阅以下示例中的结果:

{"ok": "true"}

创建复制作业

创建包含以下信息的名为 data.json 的文件。 这两个键是在开头创建的“源”和“目标”API 键，以及添加了数据库名称的“源”和“目标”实例 URL。

{
  "source": {
    "url": "https://d43caf1b-e2c8-4d3e-9b85-1d04839fa68f-bluemix.cloudant.com/source",
    "auth": {
      "iam": {
        "api_key": "xju1...TxuS"
      }
    }
  },
  "target": {
    "url": "https://dbc68dd8-f69f-4083-97dd-bf0a3e1a467a-bluemix.cloudant.com/target",
    "auth": {
      "iam": {
        "api_key": "UElc7...QIaL01Bjn"
      }
    }
  },
  "create_target": true,
  "continuous": true
}

现在，将名为 source_dest 的复制文档写入源实例上的 _replicator 数据库。

curl -k -X PUT \
     -H"Content-type: application/json" \
     -H'Authorization: '"$TOK"'' \
     'https://d43caf1b-e2c8-4d3e-9b85-1d04839fa68f-bluemix.cloudant.com/_replicator/source_dest' -d@data.json

请参阅以下示例中的结果:

{"ok":true,"id":"source_dest","rev":"1-89b01e42968acd5944ed657b87c49f0c"}

必需的客户机库版本

IAM 连接在所有受支持客户机库的最新发行版中可用。 有关更多信息，请参阅 客户机库。

使用 HTTP 客户机进行访问

在对资源或服务发出请求之前，IBM Cloud IAM 需要用 IAM API 密钥交换有时间限制的访问令牌。 然后，该访问令牌会包含在服务的 Authorization HTTP 头中。 访问令牌到期后，客户机必须负责从 IAM 令牌服务获取新的令牌。

如前所述，如果使用 IBM Cloud IAM，那么它要求您首先将 IBM API 密钥交换为限时访问令牌。 之后，使用该令牌向 IBM Cloudant API 进行认证。

在 Python 中，示例可能类似于以下内容：

import time

import requests

API_KEY = "MxVp86XHkU82Wc97tdvDF8qM8B0Xdit2RqR1mGfVXPWz"
ACCOUNT = "76838001-b883-444d-90d0-46f89e942a15-bluemix"

def get_access_token(api_key):
    """Retrieve an access token from the IAM token service."""
    token_response = requests.post(
        "https://iam.cloud.ibm.com/identity/token",
        data={
            "grant_type": "urn:ibm:params:oauth:grant-type:apikey",
            "response_type": "cloud_iam",
            "apikey": api_key
        },
        headers={
            "Accept": "application/json"
        }
    )
    if token_response.status_code == 200:
        print "Got access token from IAM"
        return token_response.json()['access_token']
    else:
        print token_response.status_code, token_response.json()
        return None

def main(api_key, account):
    access_token = None
    while True:
        if not access_token:
            access_token = get_access_token(api_key)

        if access_token:
            response = requests.get(
                "https://{0}.cloudant.com/_all_dbs".format(account),
                headers={
                    "Accept": "application/json",
                    "Authorization": "Bearer {0}".format(access_token)
                }
            )
            print "Got Cloudant response, status code", response.status_code
            if response.status_code == 401:
                print "Token has expired."
                access_token = None

        time.sleep(1)

if __name__ == "__main__":
    main(API_KEY, ACCOUNT)

创建网络区域

要将 IBM Cloudant 添加到 IAM 访问列表，必须首先创建包含 IBM Cloudant 服务的 网络区域。

要创建网络区域，请完成以下步骤。

1. 在 IBM Cloud 控制台中，单击 管理 > 基于上下文的限制，然后选择 网络区域。
2. 单击创建。
3. 输入唯一名称 (例如 cloudant-network) 和 (可选) 描述。
4. 在 Reference a service 下，选择服务类型 IAM Services 和服务 IBM Cloudant。 单击 添加 以将 IBM Cloudant IP 地址与网络区域相关联。
5. 单击 下一步 以查看网络区域。
6. 单击创建。

在 IAM IP 允许列表中引用网络区域

以上创建的 网络区域 (称为 cloudant-network) 现在可以在 IAM IP 允许列表中使用。

1. 在 IBM Cloud 控制台中，单击 管理 > 访问权 (IAM)，然后选择 设置。
2. 从“帐户”部分中，启用 IP 地址访问 设置。
3. 在 Allowed IP addresses 字段中，添加您在上面创建的网络区域的名称 (例如 cloudant-network)。
4. 单击保存。

IBM Cloudant 角色

下表列出了 IBM Cloudant 的可用 IAM 服务角色以及每个角色的简要描述。

Manager 包含 Reader 和 Writer 的所有操作，Writer 包含 Reader 的所有操作。

IBM Cloudant 操作

下表描述了可用的IAM操作和角色。 对于细颗粒度授权，可以使用 Manager，Reader，Writer，Monitor 或 Checkpointer 的角色。

使用 Manager 以外的 IAM 角色 (例如 Reader，Writer，Monitor 或 Checkpointer) 时，必须 使用 仅使用 IAM 以避免向用户提供包含更大访问许可权的旧凭证。

确保您的帐户已启用IAM

在 IBM Cloudant 仪表板的“概览”部分，部署详情下列出了“认证方法”。 此处列出了可用的认证方法。