定制令牌

使用 App ID 时，令牌用于识别用户并保护资源。您可以选择定制服务注入到令牌中的信息。通过将信息注入令牌，应用程序在运行时就可以使用这些信息，而无需配置额外的网络调用。有关令牌以及如何在 App ID 中使用令牌的更多信息，请参阅了解令牌。

通过定制令牌配置，可以确保满足安全性和用户体验需求。但是，如果某个令牌遭到泄露，那么恶意用户可能会使用更多信息或有更多时间来影响应用程序。在进行定制之前，请确保您已了解要进行的定制的安全影响。

了解定制声明映射

声明是实体发出的关于自身或代表其他人的声明。例如，如果您使用身份提供者登录到应用程序，那么提供者将向应用程序发送有关您的一组声明或陈述，以便应用程序可以将其已知的有关您的信息分组在一起。这样，当您登录时，会根据您对信息的配置方式，使用这些信息设置应用程序。

可以定义哪些类型的声明？

App ID 提供的声明分为多个类别，根据其定制级别进行区分。

规范化声明: 在每个身份令牌中，都有一组声明，这些声明由 App ID 识别为规范化声明。这些声明可用时，缺省情况下会直接将其从身份提供者映射到令牌。这些声明不能显式省略，但可在您的令牌中被定制声明覆盖。索赔包括 name, email, picture，和 locale。
受限声明: 受限声明是指其定制可能性有限并且无法被定制映射覆盖的声明。对于访问令牌，scope 是唯一的受限声明。此声明不能被覆盖，但可使用您自己的作用域进行扩展。当作用域映射到访问令牌时，其值必须是字符串，并且不能以 appid_ 作为前缀，否则会被忽略。在身份令牌中，权利要求 identities 和 oauth_clients 不能被修改或覆盖。
注册声明: 注册声明在访问令牌和身份令牌中提供，并由 App ID 进行定义。它们不能被自定义映射覆盖。这些索赔被服务部门忽略，包括 iss, aud, sub, iat, exp, amr，和 tenant。

定义令牌的声明不会更改或消除属性。但会更改在运行时令牌中提供的信息。

如何将声明映射到令牌？

每个映射都由一个数据源对象和一个用于检索声明的键来定义。如果最大有效内容保持小于 100 KB，那么最多可以向每个令牌注入 100 个声明。如果要使用嵌套声明，那么可以使用点分语法包含这些声明。例如，nested.attribute。

这些声明分别针对每个令牌进行设置，并按顺序应用，如以下示例所示。

{
  "accessTokenClaims": [
    {
      "source": "saml",
      "sourceClaim": "moderator"
    },
    {
      "source": "saml",
      "sourceClaim": "viewer",
      "destinationClaim": "reader"
    }
  ],
  "idTokenClaims": [
    {
      "source": "saml",
      "sourceClaim": "attributes.uid"
    },
    {
      "source": "saml",
      "sourceClaim": "Name",
      "destinationClaim": "firstName"
    },
    {
      "source": "saml",
      "sourceClaim": "Country"
    }
  ]
}

索赔映射变量解释
对象	描述
`source`	定义声明的源。选项包括 `saml`, `cloud_directory`, `facebook`, `google`, `appid_custom`，和 `attributes`。
`sourceClaim`	根据源提供的内容来定义声明。此项可以引用身份提供者的用户信息或用户的 App ID 定制属性。
`destinationClaim`	可选: 定义可覆盖令牌中当前声明的定制属性。

配置令牌

使用该 API，可以定制在 App ID 令牌中返回的信息。

如果要配置令牌的生存期，可以通过服务仪表板来快速进行更改。有关更多信息，请参阅管理认证。

在终端中，运行以下命令以获取 API 密钥。

ibmcloud iam api-key-create NAME [-d DESCRIPTION] [-f, --file FILE]

了解创建 API 密钥命令选项
选项	描述
`NAME`	您想给密钥起的名字。例如，`myKey`。
`DESCRIPTION`	密钥或其使用的描述。例如，`"This is my App ID API key"`。
`FILE`	要存储密钥的位置。例如，`key_file`。

使用上一步中获取的 API 密钥获取 IAM 令牌。

curl -k -X POST "https://iam.cloud.ibm.com/identity/token" \
--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=<apiKey>"

获取服务实例的租户标识。可以在服务或应用程序凭证中查找该值。

使用令牌配置对 /config/tokens 端点发出 PUT 请求。

curl -X PUT "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/tokens" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer <IAMToken>" \
-d '{
   "access": {
         "expires_in": 3600
   },
   "refresh": {
         "enabled": true,
         "expires_in": 2592001
   },
   "anonymousAccess": {
         "enabled": false
   },
   "accessTokenClaims": [
         {
         "source": "roles"
         },
         {
         "source": "saml",
         "sourceClaim": "name_id",
         "destinationClaim": "id"
         }
   ],
   "idTokenClaims": [
         {
         "source": "saml",
         "sourceClaim": "attributes.uid"
         }
   ]
}'

了解令牌配置
变量	描述
`access: expires_in`	访问令牌有效的时间长度。该值越小，防止令牌被盗的保护力度越大。该值以秒为单位，可以是 `300` 和 `86400` 范围内的任意整数。缺省值为 `3600`。
`refresh: expires_in`	刷新令牌有效的时间长度。该值越小，防止令牌被盗的保护力度越大。该值以秒为单位，可以是 `86400` 和 `7776000` 范围内的任意整数。默认值为 `2592000` （30 天）。
`anonymousAccess`	匿名令牌有效的时间长度。在用户开始与应用程序进行交互时，就会为用户分配匿名令牌。用户登录后，匿名令牌中的信息随即会传输到与该用户关联的令牌。该值以秒为单位，可以是 `86400` 和 `7776000` 范围内的任意整数。默认值为 `2592000` （30 天）。
`accessTokenClaims`	一个数组，包含在映射与访问令牌相关的声明时创建的对象。您可能希望包含有关用户的所选身份提供者所返回的角色或特定属性的信息。注: 如果您已经在使用来自身份提供者的标题为 "roles" 的定制声明，请确保使用目标声明来查看这两个值。
`idTokenClaims`	一个数组，其中包含将声明映射到身份令牌时令牌中存在的信息。根据您的配置，您还可以选择在身份令牌中提供“角色”。

您必须在发出的每个请求中设置令牌生存期。如果未设置值，系统将使用缺省值。每个定制请求都会覆盖先前配置的内容。请注意，API 中的生存期配置规范与服务仪表板中的生存期配置规范不同。

返回令牌并对其进行解码后，您会看到类似于以下示例的结果:

{
   "sub" : "1234567890",
   "name" : "John Doe",
   "exp" : 1564566,
   "roles" : ["admin", "manager"],
   "id": "<nameIDFromSaml>",
   "attributes.uid": "<uidFromSaml>"
   ...
}