View a markdown version of this page

連接器開發人員的一般/自訂授權要求 - 的受管整合 AWS IoT Device Management
什麼是一般授權？一般授權如何使用 AWS Secrets Manager一般授權請求格式一般授權工作流程GeneralAuthorization 的 Lambda 許可

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

連接器開發人員的一般/自訂授權要求

一般授權可讓連接器使用登入資料 （例如 API 金鑰、字符或使用者名稱/密碼組合），而非 OAuth 2.0 使用者字符。與透過帳戶連結提供使用者層級授權的 OAuth 2.0 不同，一般授權允許單一登入資料集跨多個最終使用者控制裝置。

注意

在本文件中，自訂授權稱為一般授權。這兩個術語都描述了相同的授權機制。在下列各節中，我們使用「一般授權」來保持一致性。

本節說明如何在連接器 AWS Lambda 函數中實作一般授權支援。如果您是為現有連接器設定一般授權的客戶，請參閱 一般/自訂授權要求。

什麼是一般授權？

一般授權是任何非 OAuth 授權機制，可讓您的連接器使用客戶憑證授權第三方平台。使用一般授權，受管整合會將登入資料管理委派給您的連接器，而一組登入資料可以控制多個最終使用者的裝置。

這適用於您與裝置廠商有商業關係，且需要大規模管理裝置而無需個別使用者授權流程的情況。

何時使用一般授權

在下列情況下，請考慮在您的連接器中實作一般授權支援：

  • 第三方平台不支援 OAuth 2.0

  • 第三方平台提供自訂授權資料，例如 API 金鑰或可駐留在 中的登入資料 AWS Secrets Manager

  • 您需要大規模管理裝置，無需個別使用者授權流程

注意

連接器可以平行實作這兩種授權類型，提供與各種授權架構的相容性。

一般授權如何使用 AWS Secrets Manager

AWS Secrets Manager 是一種秘密儲存服務，可保護敏感登入資料，例如 API 金鑰和字符。秘密會使用 AWS Key Management Service 金鑰加密。如需詳細資訊，請參閱「AWS Secrets Manager 使用者指南」。

對於一般授權，客戶會將授權憑證存放在 Secrets Manager 中，並授予 C2C 連接器存取這些秘密的許可。當受管整合調用您的連接器時，它會在請求標頭中提供 Secrets Manager ARN 和版本 ID。連接器會擷取秘密值，並使用它來授權第三方平台。

此方法可確保受管整合永遠不會直接處理長期憑證。您的連接器可完全控制登入資料管理和字符產生，使解決方案可擴展到第三方平台支援的任何授權機制。

重要

受管整合不會存取或管理存放在客戶 中的登入資料 AWS Secrets Manager。您的連接器可完全控制登入資料擷取、剖析和用量。

重要

建議您不要在任何日誌中記錄敏感登入資料或字符。不過，如果它們存放在日誌中，我們建議您使用 CloudWatch Logs 資料保護政策來遮罩日誌中的字符。如需詳細資訊，請參閱使用遮罩功能協助保護敏感日誌資料。

一般授權請求格式

當 Managed Integrations 調用您的連接器以取得一般授權帳戶關聯時，請求標頭會包含 AWS Secrets Manager 參考而非 OAuth 權杖。請求結構在所有連接器操作 (AWS.ActivateUser、AWS.SendCommand、 AWS.DiscoverDevices和 ) 之間保持一致AWS.DeactivateUser。

範例範例：一般授權請求
{
  "header": {
    "auth": {
      "secretsManager": {
        "arn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-api-key-AbCdEf",
        "versionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
      },
      "type": "GeneralAuthorization"
    }
  },
  "payload": {
    "operationName": "AWS.DiscoverDevices",
    "operationVersion": "1.0",
    "connectorId": "Your-Connector-Id",
    ...
  }
}
範例範例：OAuth 2.0 請求 （用於比較）
{
  "header": {
    "auth": {
      "token": "ashriu32yr97feqy7afsaf",
      "type": "OAuth2.0"
    }
  },
  "payload": {
    "operationName": "AWS.DiscoverDevices",
    "operationVersion": "1.0",
    "connectorId": "Your-Connector-Id",
    ...
  }
}
注意

連接器必須處理這兩種請求格式。檢查 auth.type 欄位，以決定每個請求要使用的授權方法。

一般授權工作流程

當連接器收到一般授權請求時，請遵循此工作流程：

  • 檢查授權類型 - 檢查請求標頭中的 auth.type 欄位，以判斷請求是否使用一般授權

  • 擷取 Secrets Manager 參考 - 從auth.secretsManager物件擷取 AWS Secrets Manager ARN 和版本 ID

  • 擷取秘密 - 使用提供的 ARN 和版本 ID 呼叫 AWS Secrets Manager GetSecretValue API

  • 剖析登入資料 - 剖析秘密值以擷取授權登入資料 （格式取決於第三方平台的需求）

  • 產生權杖 （如有需要） - 如有需要，請使用登入資料來產生存取權杖，或執行第三方平台所需的其他授權步驟

  • 授權 API 呼叫 - 使用登入資料或產生的權杖來授權對第三方平台的 API 呼叫

  • 程序操作 - AWS.DiscoverDevices使用授權的連線來處理連接器操作 (AWS.SendCommand、 等）

注意

連接器負責所有登入資料管理，包括權杖產生、重新整理和錯誤處理。受管整合僅提供秘密的參考，不會自行管理登入資料。

GeneralAuthorization 的 Lambda 許可

您的連接器 Lambda 執行角色必須具有從客戶的 擷取秘密的許可 AWS Secrets Manager。將下列許可新增至 Lambda 執行角色政策：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue"
      ],
      "Resource": "arn:aws:secretsmanager:*:*:secret:*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "secretsmanager.*.amazonaws.com"
        }
      }
    }
  ]
}

許可說明

  • secretsmanager:GetSecretValue - 允許 Lambda 擷取秘密值

  • kms:Decrypt - 必要，因為秘密是使用 AWS Key Management Service 金鑰加密

注意

範例政策允許存取任何秘密。在生產環境中，您應該將 Resource 欄位限制為僅連接器所需的秘密。不過，由於客戶建立自己的秘密，您可能需要使用萬用字元或記錄客戶應遵循的命名慣例。

客戶也會授予您的 Lambda 許可，以透過秘密的資源政策存取其特定秘密。