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

# 連接器開發人員的一般/自訂授權要求
<a name="concepts-general-authorization-dev"></a>

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

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

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

**Topics**
+ [什麼是一般授權？](#what-is-general-auth-dev)
+ [一般授權如何使用 AWS Secrets Manager](#general-auth-secrets-manager-dev)
+ [一般授權請求格式](#general-auth-request-format)
+ [一般授權工作流程](#general-auth-workflow-dev)
+ [GeneralAuthorization 的 Lambda 許可](#general-auth-lambda-permissions-dev)

## 什麼是一般授權？
<a name="what-is-general-auth-dev"></a>

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

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

### 何時使用一般授權
<a name="when-to-use-general-auth"></a>

在下列情況下，請考慮在您的連接器中實作一般授權支援：
+ 第三方平台不支援 OAuth 2.0
+ 第三方平台提供自訂授權資料，例如 API 金鑰或可駐留在 中的登入資料 AWS Secrets Manager
+ 您需要大規模管理裝置，無需個別使用者授權流程

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

## 一般授權如何使用 AWS Secrets Manager
<a name="general-auth-secrets-manager-dev"></a>

AWS Secrets Manager 是一種秘密儲存服務，可保護敏感登入資料，例如 API 金鑰和字符。秘密會使用 AWS Key Management Service 金鑰加密。如需詳細資訊，請參閱[「AWS Secrets Manager 使用者指南」](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。

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

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

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

**重要**  
建議您不要在任何日誌中記錄敏感登入資料或字符。不過，如果它們存放在日誌中，我們建議您使用 CloudWatch Logs 資料保護政策來遮罩日誌中的字符。如需詳細資訊，請參閱[使用遮罩功能協助保護敏感日誌資料](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/mask-sensitive-log-data.html)。

## 一般授權請求格式
<a name="general-auth-request-format"></a>

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

**Example 範例：一般授權請求**  

```
{
  "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",
    ...
  }
}
```

**Example 範例：OAuth 2.0 請求 （用於比較）**  

```
{
  "header": {
    "auth": {
      "token": "ashriu32yr97feqy7afsaf",
      "type": "OAuth2.0"
    }
  },
  "payload": {
    "operationName": "AWS.DiscoverDevices",
    "operationVersion": "1.0",
    "connectorId": "Your-Connector-Id",
    ...
  }
}
```

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

## 一般授權工作流程
<a name="general-auth-workflow-dev"></a>

當連接器收到一般授權請求時，請遵循此工作流程：
+ **檢查授權類型** - 檢查請求標頭中的 `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 許可
<a name="general-auth-lambda-permissions-dev"></a>

您的連接器 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 許可，以透過秘密的資源政策存取其特定秘密。