本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# General/Custom 连接器开发者的授权要求
<a name="concepts-general-authorization-dev"></a>

通用授权允许您的连接器使用证书（例如 API 密钥、令牌或 username/password 组合），而不是 OAuth 2.0 用户令牌。与通过账户关联提供用户级授权的 OAuth 2.0 不同，通用授权允许一组凭据控制多个最终用户的设备。

**注意**  
在本文档中，自定义授权被称为通用授权。这两个术语描述了相同的授权机制。在以下各节中，为了保持一致性，我们使用 “一般授权”。

本节介绍如何在连接器 AWS Lambda 函数中实现通用授权支持。如果您是为现有连接器配置通用授权的客户，请参阅[General/Custom 授权要求](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)
+ [适用于 Lambda 的权限 GeneralAuthorization](#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 日志数据保护策略来屏蔽日志中的令牌。有关更多信息，请参阅 [Help protect sensitive log data with masking](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/mask-sensitive-log-data.html)。

## 通用授权请求格式
<a name="general-auth-request-format"></a>

当托管集成为通用授权账户关联调用您的连接器时，请求标头包含 AWS Secrets Manager 引用而不是 OAuth 令牌。所有连接器操作（`AWS.ActivateUser`、`AWS.DiscoverDevices``AWS.SendCommand`、和`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 参考文献**-从对象中提取 AWS Secrets Manager ARN 和版本 ID `auth.secretsManager`
+ **检索密钥**-使用提供的 ARN 和版本 ID 调用 AWS Secrets Manager `GetSecretValue` API
+ **解析凭证**-解析密值以提取授权凭证（格式取决于您的第三方平台的要求）
+ **生成令牌（如果需要）**-如果需要，使用凭证生成访问令牌或执行第三方平台要求的其他授权步骤
+ **授权 API 调**用-使用凭证或生成的令牌授权对第三方平台的 API 调用
+ **进程操作**-使用授权连接处理连接器操作（`AWS.DiscoverDevices``AWS.SendCommand`、等）

**注意**  
您的连接器负责所有凭据管理，包括令牌生成、刷新和错误处理。托管集成仅提供对密钥的引用；它不管理凭证本身。

## 适用于 Lambda 的权限 GeneralAuthorization
<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 通过密钥的资源策略访问其特定密钥的权限。