翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# コネクタ開発者向けの一般/カスタム認可要件
<a name="concepts-general-authorization-dev"></a>

一般的な認可により、コネクタは OAuth 2.0 ユーザートークンの代わりに認証情報 (API キー、トークン、ユーザー名/パスワードの組み合わせなど) を使用できます。アカウントリンクを通じてユーザーレベルの認可を提供する OAuth 2.0 とは異なり、一般認可では、単一の認証情報セットで複数のエンドユーザー間でデバイスを制御できます。

**注記**  
このドキュメント全体で、カスタム認可は一般認可と呼ばれます。どちらの用語も同じ認可メカニズムを記述します。以下のセクションでは、一貫性を保つために「一般的な認可」を使用します。

このセクションでは、コネクタ AWS Lambda 関数に一般的な認可サポートを実装する方法について説明します。既存のコネクタの一般認可を設定しているお客様は、「」を参照してください[一般/カスタム認可要件](concepts-general-authorization.md)。

**Topics**
+ [一般認可とは](#what-is-general-auth-dev)
+ [General Authorization が を使用する方法 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 以外の認可メカニズムです。全般認可では、 Managed Integrations は認証情報管理をコネクタに委任し、単一の認証情報セットで複数のエンドユーザーのデバイスを制御できます。

これは、デバイスベンダーとビジネス関係があり、個々のユーザー認可フローなしでデバイスを大規模に管理する必要があるシナリオに役立ちます。

### 一般認可を使用するタイミング
<a name="when-to-use-general-auth"></a>

次の場合は、コネクタに一般的な認可サポートを実装することを検討してください。
+ サードパーティープラットフォームは OAuth 2.0 をサポートしていません
+ サードパーティープラットフォームは、 に存在する API キーや認証情報などのカスタム認可マテリアルを提供します。 AWS Secrets Manager
+ 個々のユーザー認可フローなしで、デバイスを大規模に管理する必要がある

**注記**  
コネクタは両方の認可タイプを並行して実装でき、さまざまな認可フレームワークとの互換性を提供します。

## General Authorization が を使用する方法 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 データ保護ポリシーを使用してログ内のトークンをマスクすることをお勧めします。詳細については、「[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>

Managed Integrations が一般認可アカウントの関連付けのためにコネクタを呼び出すと、リクエストヘッダーには OAuth トークンではなく AWS Secrets Manager リファレンスが含まれます。リクエスト構造は、すべてのコネクタオペレーション (`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 リファレンスの抽出** - `auth.secretsManager` オブジェクトから AWS Secrets Manager ARN とバージョン ID を抽出します。
+ **シークレットの取得** - 指定された ARN とバージョン ID を使用して API を呼び出し AWS Secrets Manager `GetSecretValue`ます。
+ **認証情報の解析** - シークレット値を解析して認可認証情報を抽出します (形式はサードパーティープラットフォームの要件によって異なります）。
+ **トークンの生成 (必要な場合)** - 必要に応じて、認証情報を使用してアクセストークンを生成するか、サードパーティープラットフォームに必要な追加の認可ステップを実行します。
+ **API コールの承認** - 認証情報または生成されたトークンを使用して、サードパーティープラットフォームへの API コールを承認します。
+ **プロセスオペレーション** - 認可された接続を使用してコネクタオペレーション (`AWS.SendCommand`、 など) `AWS.DiscoverDevices`を処理します。

**注記**  
コネクタは、トークンの生成、更新、エラー処理など、すべての認証情報管理を担当します。マネージド統合はシークレットへの参照のみを提供し、認証情報自体は管理しません。

## 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 に付与します。