自訂記號

使用 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>"

取得服務實例的承租戶 ID。可以在服務或應用程式認證中尋找該值。

使用您的記號配置，對 /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`	此陣列包含的物件是在對映與存取記號相關的宣告時建立的。您可能想要包括使用者選擇的身分提供者所傳回角色或特定屬性的相關資訊。附註: 如果您已使用身分提供者中標題為「角色」的自訂聲明，請務必使用目的地聲明來查看這兩個值。
`idTokenClaims`	包含將要求對映至身分記號時在記號中呈現的資訊的陣列。視您的配置而定，您也可以選擇在身分記號中呈現「角色」。

您必須在發出的每個要求中設定記號生命期限。如果未設定值，系統將使用預設值。每個自訂要求都會改寫先前配置的內容。請注意，API 中的生命期限配置規格與服務儀表板中的生命期限配置規格不同。

在傳回記號並解碼記號之後，您會看到類似下列範例的結果:

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