本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 CloudFront 進行相互 TLS 身分驗證 （檢視器 mTLS)
相互 TLS 身分驗證 （相互傳輸層安全身分驗證 — mTLS) 是一種安全通訊協定，透過要求雙向憑證型身分驗證來延伸標準 TLS 身分驗證，其中用戶端和伺服器都必須證明其身分，才能建立安全連線。使用交互 TLS，您可以確保只有提供信任 TLS 憑證的用戶端才能存取您的 CloudFront 分佈。
## 運作方式
在標準 TLS 交握中，只有伺服器會呈現憑證，向用戶端證明其身分。使用交互 TLS，身分驗證程序會變成雙向。當用戶端嘗試連線至 CloudFront 分佈時，CloudFront 會在 TLS 交握期間請求用戶端憑證。在建立安全連線之前，用戶端必須呈現 CloudFront 針對您設定的信任存放區驗證的有效 X.509 憑證。
CloudFront 會在 AWS 節點執行此憑證驗證，從原始伺服器卸載身分驗證複雜性，同時維護 CloudFront 的全域效能優勢。您可以將 mTLS 設定為兩種模式：驗證模式 （需要所有用戶端呈現有效的憑證） 或選用模式 （在呈現時驗證憑證，但也允許沒有憑證的連線）。
## 使用案例
使用 CloudFront 的相互 TLS 身分驗證可解決傳統身分驗證方法不足的幾個關鍵安全案例：
+ **裝置身分驗證與內容快取** - 您可以在允許存取韌體更新、遊戲下載或內部資源之前，對遊戲主控台、IoT 裝置或公司硬體進行身分驗證。每個裝置都包含唯一憑證，可證明其真實性，同時受益於 CloudFront 的快取功能。
+ **API-to-API 身分驗證** - 您可以保護信任的業務合作夥伴、付款系統或微型服務之間的machine-to-machine通訊。憑證型身分驗證不需要共用秘密或 API 金鑰，同時為自動化資料交換提供強大的身分驗證。
**Topics**
+ [運作方式](#how-mtls-works)
+ [使用案例](#mtls-use-cases)
+ [信任存放區和憑證管理](trust-stores-certificate-management.md)
+ [為 CloudFront 分佈啟用交互 TLS](enable-mtls-distributions.md)
+ [關聯 CloudFront 連線函數](connection-functions.md)
+ [設定其他設定](configuring-additional-settings.md)
+ [快取政策並轉送至原始伺服器的檢視器 mTLS 標頭](viewer-mtls-headers.md)
+ [使用 CloudFront Connection Function 和 KVS 撤銷](revocation-connection-function-kvs.md)
+ [使用連線日誌的可觀測性](connection-logs.md)
# 信任存放區和憑證管理
建立和設定信任存放區是使用 CloudFront 實作交互 TLS 身分驗證的必要要求。信任存放區包含 CloudFront 在身分驗證程序期間用來驗證用戶端憑證的憑證授權機構 (CA) 憑證。
## 什麼是信任存放區？
信任存放區是 CA 憑證的儲存庫，CloudFront 會使用此儲存庫在交互 TLS 身分驗證期間驗證用戶端憑證。信任存放區包含根 CA 憑證和中繼 CA 憑證，這些憑證構成用於驗證用戶端憑證的信任鏈。
當您使用 CloudFront 實作交互 TLS 時，信任存放區會定義您信任哪些憑證授權機構來發行有效的用戶端憑證。CloudFront 會在 TLS 交握期間，針對您的信任存放區驗證每個用戶端憑證。只有呈現連結至信任存放區中其中一個 CAs 的憑證的用戶端才會成功驗證。
CloudFront 中的信任存放區是可與多個分佈建立關聯的帳戶層級資源。這可讓您在整個 CloudFront 部署中維持一致的憑證驗證政策，同時簡化 CA 憑證管理。
## 憑證授權單位支援
CloudFront 支援 AWS 私有憑證授權單位和第三方私有憑證授權單位發行的憑證。此彈性可讓您根據您的組織需求，使用現有的憑證基礎設施或利用 AWS 受管憑證服務。
+ **AWS 私有憑證授權機構：**您可以使用 AWS Private CA 發行的憑證，該憑證提供受管私有憑證授權機構服務。此整合可簡化憑證生命週期管理，並提供與其他 AWS 服務的無縫整合。
+ **第三方私有憑證授權機構：**您也可以使用現有私有憑證授權機構基礎設施的憑證，包括企業 CAs 或其他第三方憑證提供者。這可讓您維護目前的憑證管理程序，同時新增 CloudFront 的 mTLS 功能。
## 憑證需求和規格
信任存放區對其包含的 CA 憑證有特定要求：
### CA 憑證格式要求
+ **格式：**PEM （隱私權增強郵件） 格式
+ **內容界限：**憑證必須括在 -----BEGIN CERTIFICATE----- 和 -----END CERTIFICATE----- 邊界內
+ **註解：**必須以 \$1 字元開頭，且不能包含任何 - 字元
+ **換行：**憑證之間不允許空白行
### 支援的憑證規格
+ **憑證類型：**X.509v3
+ **公有金鑰類型：**
+ RSA 2048、RSA 3072、RSA 4096
+ ECDSA：secp256r1、secp384r1
+ **簽章演算法：**
+ SHA256, SHA384, SHA512搭配 RSA
+ SHA256, SHA384, SHA512搭配 EC
+ SHA256, SHA384, SHA512搭配 RSASSA-PSS 搭配 MGF1
### 憑證套件格式範例
多個憑證 (PEM 編碼）：
```
# Root CA Certificate
-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAKoK/OvD/XqiMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
BAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVQQKDBhJbnRlcm5ldCBX
aWRnaXRzIFB0eSBMdGQwHhcNMTcwNzEyMTU0NzQ4WhcNMjcwNzEwMTU0NzQ4WjBF
MQswCQYDVQQGEwJBVTETMBEGA1UECAwKU29tZS1TdGF0ZTEhMB8GA1UECgwYSW50
ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB
CgKCAQEAuuExKvY1xzHFylsHiuowqpmzs7rEcuuylOuEszpFp+BtXh0ZuEtts9LP
-----END CERTIFICATE-----
# Intermediate CA Certificate
-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAKoK/OvD/XqjMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
BAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVQQKDBhJbnRlcm5ldCBX
aWRnaXRzIFB0eSBMdGQwHhcNMTcwNzEyMTU0NzQ4WhcNMjcwNzEwMTU0NzQ4WjBF
MQswCQYDVQQGEwJBVTETMBEGA1UECAwKU29tZS1TdGF0ZTEhMB8GA1UECgwYSW50
ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB
CgKCAQEAuuExKvY1xzHFylsHiuowqpmzs7rEcuuylOuEszpFp+BtXh0ZuEtts9LP
-----END CERTIFICATE-----
```
## 建立信任存放區
建立信任存放區之前，您必須將 PEM 格式的 CA 憑證套件上傳至 Amazon S3 儲存貯體。憑證套件應包含驗證用戶端憑證所需的所有信任根憑證和中繼 CA 憑證。
建立信任存放區時，CA 憑證套件只會從 S3 讀取一次。如果未來變更 CA 憑證套件，則必須手動更新信任存放區。信任存放區和 S3 CA 憑證套件之間不會保留同步。
### 先決條件
+ 從您的憑證授權機構 (CA) 上傳到 Amazon S3 儲存貯體的憑證套件
+ 建立 CloudFront 資源的必要許可
### 建立信任存放區 （主控台）
1. 登入 AWS 管理主控台 並開啟位於 的 CloudFront 主控台[https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home)。
1. 在導覽窗格中，選擇**信任存放**區。
1. 選擇**建立信任存放區**。
1. 針對**信任存放區名稱**，輸入信任存放區的名稱。
1. 針對**憑證授權機構 (CA) 套件**，輸入 PEM 格式 CA 憑證套件的 Amazon S3 路徑。
1. 選擇**建立信任存放區**。
### 建立信任存放區 (AWS CLI)
```
aws cloudfront create-trust-store \
--name MyTrustStore \
--ca-certificates-bundle-source '{"CaCertificatesBundleS3Location":{"Bucket":"my-bucket","Key":"ca-bundle.pem","Region":"bucket-region"}}' \
--tags Items=[{Key=Environment,Value=Production}]
```
## 將信任存放區與分佈建立關聯
建立信任存放區之後，您必須將其與 CloudFront 分佈建立關聯，才能啟用交互 TLS 身分驗證。
### 先決條件
+ 已啟用僅 HTTPS 檢視器通訊協定政策且 HTTP3 支援已停用的現有 CloudFront 分佈。
### 建立信任存放區的關聯 （主控台）
CloudFront 主控台中的信任存放區有兩種關聯方式：透過信任存放區詳細資訊頁面或透過分佈設定頁面。
**透過信任存放區詳細資訊頁面關聯信任存放區：**
1. 登入 AWS 管理主控台 並開啟位於 的 CloudFront 主控台[https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home)。
1. 在導覽窗格中，選擇**信任存放**區。
1. 選擇您要關聯的信任存放區名稱。
1. 選擇**關聯以分佈**。
1. 設定可用的檢視器 mTLS 選項：
+ **用戶端憑證驗證模式：**選擇必要和選用模式。在必要模式下，所有用戶端都需要呈現憑證。在選用模式中，會驗證呈現憑證的用戶端，而未呈現憑證的用戶端則允許存取。
+ **公告信任存放區 CA 名稱：**選擇是否要在 TLS 交握期間將信任存放區中的 CA 名稱公告給用戶端。
+ **忽略憑證過期日期：**選擇是否允許憑證過期的連線 （其他驗證條件仍適用）。
+ **連線函數：**選用的連線函數可以建立關聯，以根據其他自訂條件允許/拒絕連線。
1. 選取要與信任存放區建立關聯的一或多個分佈。只有停用 HTTP3 且具有僅限 HTTPS 快取行為的分佈，才能支援檢視器 mTLS。
1. 選擇**關聯**。
**透過分佈設定頁面關聯信任存放區：**
1. 登入 AWS 管理主控台 並開啟位於 的 CloudFront 主控台[https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home)。
1. 選取您要關聯的分佈
1. 在**一般**索引標籤下方的**設定**容器中，選擇右上角的**編輯**
1. 向下捲動至頁面底部，在**連線**容器中切換**檢視器 mTLS** 開啟
1. 設定可用的檢視器 mTLS 選項：
+ **用戶端憑證驗證模式：**選擇必要和選用模式。在必要模式下，所有用戶端都需要呈現憑證。在選用模式中，會驗證呈現憑證的用戶端，而未呈現憑證的用戶端則允許存取。
+ **公告信任存放區 CA 名稱：**選擇是否要在 TLS 交握期間將信任存放區中的 CA 名稱公告給用戶端。
+ **忽略憑證過期日期：**選擇是否允許憑證過期的連線 （其他驗證條件仍適用）。
+ **連線函數：**選用的連線函數可以建立關聯，以根據其他自訂條件允許/拒絕連線。
1. 選擇右下角的**儲存變更**。
### 建立信任存放區 (AWS CLI) 的關聯
信任存放區可以透過 DistributionConfig.ViewerMtlsConfig 屬性與分佈建立關聯。這表示我們首先需要擷取分佈組態，然後在後續的 UpdateDistribution 請求中提供 ViewerMtlsConfig。
```
// First fetch the distribution
aws cloudfront get-distribution {DISTRIBUTION_ID}
// Update the distribution config, for example:
Distribution config, file://distConf.json:
{
...other fields,
ViewerMtlsConfig: {
Mode: 'required',
TrustStoreConfig: {
AdvertiseTrustStoreCaNames: false,
IgnoreCertificateExpiry: true,
TrustStoreId: {TRUST_STORE_ID}
}
}
}
aws cloudfront update-distribution \
--id {DISTRIBUTION_ID} \
--if-match {ETAG} \
--distribution-config file://distConf.json
```
## 管理信任存放區
### 檢視信任存放區詳細資訊
1. 登入 AWS 管理主控台 ，並在 開啟 CloudFront 主控台[https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home)。
1. 在導覽窗格中，選擇**信任存放**區。
1. 選擇信任存放區的名稱以檢視其詳細資訊頁面。
詳細資訊頁面顯示：
+ 信任存放區名稱和 ID
+ CA 憑證數量
+ 建立日期和上次修改日期
+ 關聯的分佈
+ Tags (標籤)
### 修改信任存放區
若要取代 CA 憑證套件：
1. 登入 AWS 管理主控台 ，並在 開啟 CloudFront 主控台[https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home)。
1. 在導覽窗格中，選擇**信任存放**區。
1. 選擇信任存放區的名稱。
1. 選擇**動作**，然後選擇**編輯**。
1. 針對**憑證授權單位 (CA) 套件**，輸入更新後的 CA 套件 PEM 檔案的 Amazon S3 位置。
1. 選擇**更新信任存放區**。
### 刪除信任存放區
**先決條件：**您必須先取消信任存放區與所有 CloudFront 分佈的關聯。
1. 登入 AWS 管理主控台 ，並在 開啟 CloudFront 主控台[https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home)。
1. 在導覽窗格中，選擇**信任存放**區。
1. 選擇信任存放區的名稱。
1. 選擇**刪除信任存放區**。
1. 選擇**刪除**以確認刪除。
### 後續步驟
在建立信任存放區並將其與 CloudFront 分發建立關聯之後，您可以繼續在分發上啟用交互 TLS 身分驗證，並設定其他設定，例如將憑證標頭轉送至原始伺服器。如需在 分佈上啟用 mTLS 的詳細說明，請參閱 [為 CloudFront 分佈啟用交互 TLS](enable-mtls-distributions.md)。
# 為 CloudFront 分佈啟用交互 TLS
## 先決條件和要求
CloudFront 的交互 TLS 驗證模式要求所有用戶端在 TLS 交握期間呈現有效的憑證，並拒絕沒有有效憑證的連線。在 CloudFront 分佈上啟用交互 TLS 之前，請確定您有：
+ 使用憑證授權單位憑證建立信任存放區
+ 將信任存放區與您的 CloudFront 分佈建立關聯
+ 確保所有分佈快取行為都使用僅限 HTTPS 的檢視器通訊協定政策
+ 確保您的分佈使用 HTTP/2 （預設設定，HTTP/3 不支援檢視器 mTLS)
**注意**
相互 TLS 身分驗證需要檢視器和 CloudFront 之間的 HTTPS 連線。您無法在具有支援 HTTP 連線之任何快取行為的分佈上啟用 mTLS。
## 啟用交互 TLS （主控台）
### 對於新分佈
在 CloudFront 主控台中建立新分佈的過程中，無法設定檢視器 mTLS。首先透過任何方式 （主控台、CLI、API) 建立分佈，然後編輯分佈設定，以根據下列現有的分佈說明啟用檢視器 mTLS。
### 對於現有的分佈
1. 登入 AWS 管理主控台 ，並在 開啟 CloudFront 主控台[https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home)。
1. 從分佈清單中，選取您要修改的分佈。
1. 確定針對所有快取行為，檢視器通訊協定政策設定為將 **HTTP 重新導向至 HTTPS** 或**僅限 HTTPS**。（您可以選擇**快取行為**索引標籤，以使用 HTTP 通訊協定政策檢視和更新任何快取行為。)
1. 選擇**一般**索引標籤。
1. 在 **Settings** (設定) 區段中，選擇 **Edit** (編輯)。
1. 在**連線**區段中，尋找**檢視器交互身分驗證 (mTLS)**。
1. 將**啟用交互身分驗證**切換為開啟。
1. 對於**用戶端憑證驗證模式**，選取**必要** （所有用戶端都必須顯示憑證） 或**選用** （用戶端可以選擇性顯示憑證）。
1. 針對**信任存放區**，選取您先前建立的信任存放區。
1. （選用） 如果您希望 CloudFront 在 TLS 交握期間將 **CA 名稱傳送給用戶端，請切換公告信任存放**區 CA 名稱。
1. （選用） 如果您想要允許憑證過期的連線，請切換**忽略憑證過期日期**。
1. 選擇**儲存變更**。
## 啟用交互 TLS (AWS CLI)
### 對於新分佈
下列範例示範如何建立包含 mTLS 設定的分佈組態檔案 (distribution-config.json)：
```
{
"CallerReference": "cli-example-1",
"Origins": {
"Quantity": 1,
"Items": [
{
"Id": "my-origin",
"DomainName": "example.com",
"CustomOriginConfig": {
"HTTPPort": 80,
"HTTPSPort": 443,
"OriginProtocolPolicy": "https-only"
}
}
]
},
"DefaultCacheBehavior": {
"TargetOriginId": "my-origin",
"ViewerProtocolPolicy": "https-only",
"MinTTL": 0,
"ForwardedValues": {
"QueryString": false,
"Cookies": {
"Forward": "none"
}
}
},
"ViewerCertificate": {
"CloudFrontDefaultCertificate": true
},
"ViewerMtlsConfig": {
"Mode": "required",
"TrustStoreConfig": {
"TrustStoreId": {TRUST_STORE_ID},
"AdvertiseTrustStoreCaNames": true,
"IgnoreCertificateExpiry": true
}
},
"Enabled": true
}
```
使用下列範例命令建立已啟用 mTLS 的分佈：
```
aws cloudfront create-distribution --distribution-config file://distribution-config.json
```
### 對於現有的分佈
使用下列範例命令取得目前的分佈組態：
```
aws cloudfront get-distribution-config --id E1A2B3C4D5E6F7 --output json > dist-config.json
```
編輯 檔案以新增 mTLS 設定。將下列範例區段新增至您的分佈組態：
```
"ViewerMtlsConfig": {
"Mode": "required",
"TrustStoreConfig": {
"TrustStoreId": {TRUST_STORE_ID},
"AdvertiseTrustStoreCaNames": true,
"IgnoreCertificateExpiry": true
}
}
```
從檔案移除 ETag 欄位，但分別儲存其值。
使用下列範例命令，使用新組態更新分佈：
```
aws cloudfront update-distribution \
--id E1A2B3C4D5E6F7 \
--if-match YOUR-ETAG-VALUE \
--distribution-config file://dist-config.json
```
## 檢視器通訊協定政策
使用交互 TLS 時，所有分佈快取行為都必須使用僅限 HTTPS 的檢視器通訊協定政策進行設定：
+ 將 **HTTP 重新導向至 HTTPS** - 在執行憑證驗證之前將 HTTP 請求重新導向至 HTTPS。
+ **僅限 HTTPS** - 僅接受 HTTPS 請求並執行憑證驗證。
**注意**
交互 TLS 不支援 HTTP 和 HTTPS 檢視器通訊協定政策，因為 HTTP 連線無法執行憑證驗證。
## 後續步驟
在 CloudFront 分佈上啟用檢視器 TLS 之後，您可以關聯連線函數來實作自訂憑證驗證邏輯。Connection Functions 可讓您使用自訂驗證規則、憑證撤銷檢查和記錄來擴展內建 mTLS 身分驗證功能。如需建立和關聯連線函數的詳細資訊，請參閱 [關聯 CloudFront 連線函數](connection-functions.md)。
# 關聯 CloudFront 連線函數
CloudFront Connection Functions 可讓您在 TLS 交握期間實作自訂憑證驗證邏輯，提供內建 mTLS 身分驗證功能的延伸。
## 什麼是連線函數？
連線函數是在用戶端憑證經過驗證後，在 TLS 交握期間執行的 JavaScript 函數。已驗證的用戶端憑證會傳遞至 Connection Function，連線函數可以在此時對是否授予存取權進行額外判斷。如需連線函數的詳細資訊，請參閱 [使用 CloudFront Functions 在邊緣進行自訂](cloudfront-functions.md)。
## Connection Functions 如何使用 mTLS
當用戶端嘗試建立與 CloudFront 分佈的 mTLS 連線時，會發生下列順序：
1. 用戶端使用 CloudFront 節點啟動 TLS 交握。
1. CloudFront 請求和接收用戶端憑證。
1. CloudFront 會對信任存放區執行標準憑證驗證。
1. 如果憑證通過標準驗證，CloudFront 會叫用您的連線函數。如果在 **ViewerMtlsConfig** 中啟用了 **IgnoreCertificateExpiry**，則您的過期但有效憑證也會傳遞至連線函數。如果用戶端憑證無效，將不會叫用連線函數。
1. 您的 Connection Function 會收到剖析的憑證資訊和連線詳細資訊。
1. 您的函數會根據自訂邏輯做出允許/拒絕決策。
1. CloudFront 會根據您的決定完成或終止 TLS 連線。
驗證模式和選用模式 （當用戶端呈現憑證時） 都會叫用連線函數。
## 建立連線函數
您可以使用 CloudFront 主控台或 CLI AWS 建立連線函數。
### 建立連線函數 （主控台）
1. 登入 AWS 管理主控台 ，並在 開啟 CloudFront 主控台[https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home)。
1. 在導覽視窗中，選擇**函數**。
1. 選擇**連線函數**索引標籤，然後選擇**建立連線函數**。
1. 輸入您 AWS 帳戶中唯一的函數名稱。
1. 選擇**繼續**。
1. 在函數編輯器中，撰寫要驗證憑證的 JavaScript 程式碼。函數處理常式必須呼叫允許或拒絕。
1. 選用：KeyValue 存放區可以與 Connection Function 建立關聯，以實作撤銷控制。
1. 選擇**儲存變更**。
### 建立連線函數 (AWS CLI)
下列範例示範如何建立連線函數：
將函數程式碼寫入不同的檔案中，例如 code.js：
```
function connectionHandler(connection) {
connection.allow();
}
```
```
aws cloudfront create-connection-function \
--name "certificate-validator" \
--connection-function-config '{
"Comment": "Client certificate validation function",
"Runtime": "cloudfront-js-2.0"
}' \
--connection-function-code fileb://code.js
```
## Connection Function 程式碼結構
Connection Functions 實作 connectionHandler 函數，該函數會接收包含憑證和連線資訊的連線物件。您的函數必須使用 `connection.allow()`或 `connection.deny()`來決定連線。
### 基本連線函數範例
下列範例顯示簡單的連線函數，可驗證用戶端憑證的主旨欄位：
```
function connectionHandler(connection) {
// Only process if a certificate was presented
if (!connection.clientCertificate) {
console.log("No certificate presented");
connection.deny();
}
// Check the subject field for specific organization
const subject = connection.clientCertificate.certificates.leaf.subject;
if (!subject.includes("O=ExampleCorp")) {
console.log("Certificate not from authorized organization");
connection.deny();
} else {
// All checks passed
console.log("Certificate validation passed");
connection.allow();
}
}
```
連線物件上可用的用戶端憑證屬性完整規格可在此處取得：
```
{
"connectionId": "Fdb-Eb7L9gVn2cFakz7wWyBJIDAD4-oNO6g8r3vXDV132BtnIVtqDA==", // Unique identifier for this TLS connection
"clientIp": "203.0.113.42", // IP address of the connecting client (IPv4 or IPv6)
"clientCertificate": {
"certificates": {
"leaf": {
"subject": "CN=client.example.com,O=Example Corp,C=US", // Distinguished Name (DN) of the certificate holder
"issuer": "CN=Example Corp Intermediate CA,O=Example Corp,C=US", // Distinguished Name (DN) of the certificate authority that issued this certificate
"serialNumber": "4a:3f:5c:92:d1:e8:7b:6c", // Unique serial number assigned by the issuing CA (hexadecimal)
"validity": {
"notBefore": "2024-01-15T00:00:00Z", // Certificate validity start date (ISO 8601 format)
"notAfter": "2025-01-14T23:59:59Z" // Certificate expiration date (ISO 8601 format)
},
"sha256Fingerprint": "a1b2c3d4e5f6...abc123def456", // SHA-256 hash of the certificate (64 hex characters)
},
},
},
}
```
## 關聯連線函數
建立連線函數之後，您必須將其發佈至 LIVE 階段，並將其與您的分佈建立關聯。
### 發佈和關聯連線函數 （主控台）
1. 登入 AWS 管理主控台 ，並在 開啟 CloudFront 主控台[https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home)。
1. 在導覽窗格中，選擇**函數**
1. 選擇**連線函數**索引標籤，然後選取您的連線函數。
1. 選擇**發佈**以將其移至 LIVE 階段。
1. 在發佈區段下方的關聯分佈表格中，選擇**新增關聯**。
1. 選取已啟用檢視器 mTLS 的分佈，以便與之建立關聯。
或者，也可以從分佈詳細資訊頁面關聯已發佈的連線函數。
1. 導覽至列出所有分發的主控台首頁。
1. 選取您要關聯的分佈。
1. 選擇**一般**索引標籤。
1. 在 **Settings** (設定) 區段中，選擇 **Edit** (編輯)。
1. 在**連線**區段中，尋找**檢視器交互身分驗證 (mTLS)**。
1. 針對**連線函數**，選取您的函數。
1. 選擇**儲存變更**。
### 建立連線函數 (AWS CLI) 的關聯
下列範例示範如何將 Connection Function 與分佈建立關聯：
```
// DistributionConfig:
{
...other settings,
"ConnectionFunctionAssociation": {
"Id": "cf_30c2CV2elHwCoInb3LtcaUJkZeD"
}
}
```
## Connection Functions 的使用案例
Connection Functions 啟用數個進階 mTLS 使用案例：
+ **憑證屬性驗證** - 驗證用戶端憑證中的特定欄位，例如組織單位要求或主體替代名稱模式。
+ **憑證撤銷檢查** - 使用 KeyValueStore 實作自訂憑證撤銷檢查，以存放已撤銷的憑證序號。
+ **以 IP 為基礎的憑證政策** - 根據用戶端 IP 地址或地理限制套用不同的憑證政策。
+ **多租戶驗證** - 實作租戶特定的驗證規則，其中根據主機名稱或憑證屬性套用不同的憑證要求。
**注意**
在 TLS 交握期間，連線函數每個用戶端連線執行一次。
Connection Functions 只能允許或拒絕連線，不能修改 HTTP 請求/回應。
只有 LIVE 階段函數 （已發佈） 可以與分佈建立關聯。
每個分佈最多可以有一個連線函數。
## 後續步驟
將連線函數與 CloudFront 分佈建立關聯後，您可以設定選用設定來自訂 mTLS 實作的行為。如需設定其他設定的詳細指示，例如選用的用戶端憑證驗證模式，請參閱 [設定其他設定](configuring-additional-settings.md)。
# 設定其他設定
啟用基本交互 TLS 身分驗證之後，您可以設定其他設定，以針對特定使用案例和需求自訂身分驗證行為。
## 用戶端憑證驗證選用模式
CloudFront 提供替代的選用用戶端憑證驗證模式，可驗證呈現的用戶端憑證，但允許存取不存在憑證的用戶端。
### 選用模式行為
+ 授予具有有效憑證的用戶端連線 （拒絕無效的憑證）。
+ 允許在沒有憑證的情況下連線至用戶端
+ 允許透過單一分佈的混合用戶端身分驗證案例。
選用模式非常適合逐步遷移至 mTLS 身分驗證、支援具有憑證的用戶端和沒有憑證的用戶端，或與舊版用戶端保持回溯相容性。
**注意**
在選用模式中，即使用戶端不存在憑證，連線函數仍會被叫用。這可讓您實作自訂邏輯，例如記錄用戶端 IP 地址，或根據是否顯示憑證套用不同的政策。
### 設定選用模式 （主控台）
1. 在您的分佈設定中，導覽至**一般**索引標籤，選擇**編輯**。
1. 捲動至**連線**容器中的**檢視器交互身分驗證 (mTLS)** 區段。
1. 針對**用戶端憑證驗證模式**，選取**選用**。
1. 儲存變更。
### 設定選用模式 (AWS CLI)
下列範例示範如何設定選用模式：
```
"ViewerMtlsConfig": {
"Mode": "optional",
...other settings
}
```
## 憑證授權單位公告
AdvertiseTrustStoreCaNames 欄位控制 CloudFront 在 TLS 交握期間是否將信任的 CA 名稱清單傳送給用戶端，協助用戶端選取適當的憑證。
### 設定 CA 公告 （主控台）
1. 在您的分佈設定中，導覽至**一般**索引標籤，選擇**編輯**。
1. 捲動至**連線**容器中的**檢視器交互身分驗證 (mTLS)** 區段。
1. 選取或取消選取**公告信任存放區 CA 名稱**核取方塊。
1. 選擇**儲存變更**。
### 設定 CA 公告 (AWS CLI)
下列範例示範如何啟用 CA 公告：
```
"ViewerMtlsConfig": {
"Mode": "required", // or "optional"
"TrustStoreConfig": {
"AdvertiseTrustStoreCaNames": true,
...other settings
}
}
```
## 憑證過期處理
IgnoreCertificateExpiry 屬性會決定 CloudFront 如何回應過期的用戶端憑證。根據預設，CloudFront 會拒絕過期的用戶端憑證，但您可以視需要將其設定為接受憑證。對於憑證過期且無法立即更新的裝置，通常會啟用此功能。
### 設定憑證過期處理 （主控台）
1. 在您的分佈設定中，導覽至**一般**索引標籤，選擇**編輯**。
1. 捲動至**連線**容器的**檢視器交互身分驗證 (mTLS)** 區段。
1. 選取或取消選取**忽略憑證過期日期**核取方塊。
1. 選擇**儲存變更**。
### 設定憑證過期處理 (AWS CLI)
下列範例示範如何忽略憑證過期：
```
"ViewerMtlsConfig": {
"Mode": "required", // or "optional"
"TrustStoreConfig": {
"IgnoreCertificateExpiry": false,
...other settings
}
}
```
**注意**
**IgnoreCertificateExpiry** 僅適用於憑證有效期限。所有其他憑證驗證檢查仍然適用 （信任鏈、簽章驗證）。
## 後續步驟
設定其他設定後，您可以設定標頭轉送，將憑證資訊傳遞至原始伺服器、使用 Connection Functions 和 KeyValueStore 實作憑證撤銷，以及啟用連線日誌以進行監控。如需轉送憑證資訊至原始伺服器的詳細資訊，請參閱[轉送標頭至原始伺服器](viewer-mtls-headers.md)。
# 快取政策並轉送至原始伺服器的檢視器 mTLS 標頭
使用交互 TLS 身分驗證時，CloudFront 可以從用戶端憑證擷取資訊，並將其作為 HTTP 標頭轉送到您的原始伺服器。這可讓您的原始伺服器存取憑證詳細資訊，而無需實作憑證驗證邏輯。
下列標頭可供 用來建立快取行為：
| 標頭名稱 | Description | 範例值 |
| --- | --- | --- |
| CloudFront-Viewer-Cert-Serial-Number | 憑證序號的十六進位表示 | 4a：3f：5c：92：d1：e8：7b：6c |
| CloudFront-Viewer-Cert-Issuer | RFC2253 發行者辨別名稱 (DN) 的字串表示 | CN=rootcamtls.com，OU=rootCA，O=mTLS，L=Seattle，ST=Washington，C=US |
| CloudFront-Viewer-Cert-Subject | 主旨辨別名稱 (DN) 的 RFC2253 字串表示 | CN=client\$1.com，OU=client-3，O=mTLS，ST=Washington，C=US |
| CloudFront-Viewer-Cert-Present | 1 （存在） 或 0 （不存在） 表示憑證是否存在。在必要模式下，此值一律為 1。 | 1 |
| CloudFront-Viewer-Cert-Sha256 | 用戶端憑證的 SHA256 雜湊 | 01fbf94fef5569753420c349f49adbfd80af5275377816e3ab1fb371b29cb586 |
對於原始伺服器請求，除了上述可用於快取行為的標頭之外，還提供兩個額外的標頭。由於可能的標頭大小，CloudFront-Viewer-Cert-Pem 標頭不會公開至邊緣函數 (Lambda@Edge 或 CloudFront Functions)，而且只會轉送至原始伺服器。
| 標頭名稱 | Description | 範例值 |
| --- | --- | --- |
| CloudFront-Viewer-Cert-Validity | notBefore和 notAfter date 的 ISO8601 格式 | CloudFront-Viewer-Cert-Validity：NotBefore=2023-09-21T01：50：17Z；NotAfter=2024-09-20T01：50：17Z |
| CloudFront-Viewer-Cert-Pem | 分葉憑證的 URL 編碼 PEM 格式 | CloudFront-Viewer-Cert-Pem：-----BEGIN%20CERTIFICATE-----%0AMIIG<...reduced...>NmrUlw%0A-----END%20CERTIFICATE-----%0A |
## 設定標頭轉送
### 主控台
在驗證模式中，CloudFront 會自動將 CloudFront-Viewer-Cert-\$1 標頭新增至所有檢視器請求。若要將這些標頭轉送到您的原始伺服器：
1. 在主清單分佈頁面中，選取已啟用檢視器 mTLS 的分佈，然後前往**行為**索引標籤
1. 選取快取行為，然後選擇**編輯**
1. 在**原始伺服器請求政策**區段中，選擇**建立政策**或選取現有政策
1. 確保原始伺服器請求政策中包含下列標頭：
+ CloudFront-Viewer-Cert-Serial-Number
+ CloudFront-Viewer-Cert-Issuer
+ CloudFront-Viewer-Cert-Subject
+ CloudFront-Viewer-Cert-Present
+ Cloudfront-Viewer-Cert-Sha256
+ CloudFront-Viewer-Cert-Validity
+ CloudFront-Viewer-Cert-Pem
1. 選擇**建立** （適用於新政策） 或**儲存變更** （適用於現有政策）
1. 在快取行為中選取政策並儲存變更
### 使用 AWS CLI
下列範例示範如何建立原始伺服器請求政策，其中包含用於驗證模式的 mTLS 標頭：
```
aws cloudfront create-origin-request-policy \
--origin-request-policy-config '{
"Name": "MTLSHeadersPolicy",
"HeadersConfig": {
"HeaderBehavior": "whitelist",
"Headers": {
"Quantity": 5,
"Items": [
"CloudFront-Viewer-Cert-Serial-Number",
"CloudFront-Viewer-Cert-Issuer",
"CloudFront-Viewer-Cert-Subject",
"CloudFront-Viewer-Cert-Validity",
"CloudFront-Viewer-Cert-Pem"
]
}
},
"CookiesConfig": {
"CookieBehavior": "none"
},
"QueryStringsConfig": {
"QueryStringBehavior": "none"
}
}'
```
## 標頭處理考量
使用憑證標頭時，請考慮下列最佳實務：
+ **標頭驗證：**驗證原始伺服器的憑證標頭值作為額外的安全措施
+ **標頭大小限制：**PEM 憑證標頭可以很大，確保您的原始伺服器可以處理它們
+ **快取考量：**在快取金鑰中使用憑證標頭會增加快取分段
+ **跨來源請求：**如果您的應用程式使用 CORS，則您可能需要將其設定為允許憑證標頭
## 後續步驟
設定標頭轉送之後，您可以使用 CloudFront Connection Functions 和 KeyValueStore 實作憑證撤銷檢查。如需實作撤銷檢查的詳細資訊，請參閱 [使用 CloudFront Connection Function 和 KVS 撤銷](revocation-connection-function-kvs.md)。
# 使用 CloudFront Connection Function 和 KVS 撤銷
您可以結合 CloudFront Connection Functions 與 KeyValueStore，實作交互 TLS 身分驗證的憑證撤銷檢查。此方法提供可擴展的即時憑證撤銷機制，可補充 CloudFront 的內建憑證驗證。
Connection Functions 是在 CloudFront 節點建立 TLS 連線期間執行的 JavaScript 函數，可讓您實作 mTLS 身分驗證的自訂憑證驗證邏輯。如需連線函數的詳細資訊，請參閱 [關聯 CloudFront 連線函數](connection-functions.md)。
## 憑證撤銷如何與 Connection Functions 搭配使用
CloudFront 的標準憑證驗證會驗證憑證鏈、簽章和過期，但不包含內建憑證撤銷檢查。透過使用連線函數，您可以在 TLS 交握期間實作自訂撤銷檢查。
憑證撤銷程序的運作方式如下：
1. 將撤銷的憑證序號儲存在 CloudFront KeyValueStore 中。
1. 當用戶端提供憑證時，會叫用您的連線函數。
1. 函數會根據 KeyValueStore 檢查憑證的序號。
1. 如果在存放區中找到序號，則會撤銷憑證。
1. 您的函數拒絕已撤銷憑證的連線。
此方法提供跨 CloudFront 全球邊緣網路near-real-time的撤銷檢查。
## 設定已撤銷憑證的 KeyValueStore
首先，建立 KeyValueStore 以存放已撤銷憑證的序號：
### 建立 KeyValueStore （主控台）
1. 登入 AWS 管理主控台 並開啟位於 的 CloudFront 主控台[https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home)。
1. 在導覽窗格中，選擇**鍵值存放**區。
1. 選擇**建立索引鍵值存放區**。
1. 輸入金鑰值存放區的名稱 （例如，已撤銷憑證）。
1. (選用) 新增描述。
1. 選擇**建立索引鍵值存放區**。
### 建立 KeyValueStore (AWS CLI)
下列範例示範如何建立 KeyValueStore：
```
aws cloudfront create-key-value-store \
--name "revoked-certificates" \
--comment "Store for revoked certificate serial numbers"
```
## 匯入已撤銷的憑證序號
建立 KeyValueStore 之後，您需要匯入已撤銷憑證的序號：
### 準備撤銷資料
使用您撤銷的憑證序號建立 JSON 檔案：
```
{
"data": [
{
"key": "ABC123DEF456",
"value": ""
},
{
"key": "789XYZ012GHI",
"value": ""
}
]
}
```
### 從 S3 匯入
1. 將 JSON 檔案上傳至 S3 儲存貯體
1. 將檔案匯入至 KeyValueStore：
```
aws cloudfront create-key-value-store \
--name "revoked-certificates" \
--import-source '{
"SourceType": "S3",
"SourceARN": "arn:aws:s3:::amzn-s3-demo-bucket1/revoked-serials.json"
}'
```
## 建立用於撤銷檢查的連線函數
建立連線函數，以檢查憑證序號與 KeyValueStore：
### Connection Function 程式碼範例
下列範例顯示執行憑證撤銷檢查的連線函數：
```
import cf from 'cloudfront';
async function connectionHandler(connection) {
const kvsHandle = cf.kvs();
// Get client certificate serial number
const clientSerialNumber = connection.clientCertificate.certificates.leaf.serialNumber;
// Check if the serial number exists in the KeyValueStore
const isRevoked = await kvsHandle.exists(clientSerialNumber.replaceAll(':', ''));
if (isRevoked) {
console.log(`Certificate ${clientSerialNumber} is revoked. Denying connection.`);
connection.logCustomData(`REVOKED:${clientSerialNumber}`);
connection.deny();
} else {
console.log(`Certificate ${clientSerialNumber} is valid. Allowing connection.`);
connection.allow();
}
}
```
### 建立連線函數 (AWS CLI)
下列範例示範如何建立與 KeyValueStore 關聯的連線函數：
```
aws cloudfront create-connection-function \
--name "revocation-checker" \
--connection-function-config '{
"Comment": "Certificate revocation checking function",
"Runtime": "cloudfront-js-2.0",
"KeyValueStoreAssociations": {
"Quantity": 1,
"Items": [
{
"KeyValueStoreARN": "arn:aws:cloudfront::123456789012:key-value-store/revoked-certificates"
}
]
}
}' \
--connection-function-code fileb://revocation-checker.js
```
## 將函數與您的分佈建立關聯
建立和發佈連線函數之後，請將其與啟用 mTLS 的 CloudFront 分佈建立關聯，如 [關聯 CloudFront 連線函數](connection-functions.md)一節中所述。
# 使用連線日誌的可觀測性
CloudFront 連線日誌提供交互 TLS 身分驗證事件的詳細可見性，可讓您監控憑證驗證、追蹤連線嘗試，以及疑難排解身分驗證問題。
## 什麼是連線日誌？
連線日誌會擷取有關啟用交互 TLS 分佈的 TLS 交握和憑證驗證的詳細資訊。與記錄 HTTP 請求資訊的標準存取日誌不同，連線日誌特別著重於 TLS 連線建立階段，包括：
+ 連線狀態 （成功/失敗）
+ 用戶端憑證詳細資訊
+ TLS 通訊協定和密碼資訊
+ 連線時間指標
+ 來自 Connection Functions 的自訂資料
這些日誌提供憑證型身分驗證事件的全方位可見性，協助您監控安全性、疑難排解問題，並符合合規要求。
## 啟用連線日誌
連線日誌僅適用於已啟用交互 TLS 身分驗證的分佈。您可以將連線日誌傳送至多個目的地，包括 CloudWatch Logs、Amazon Data Firehose 和 Amazon S3。
### 先決條件
啟用連線日誌之前：
+ 為您的 CloudFront 分佈設定交互 TLS
+ 為您的 CloudFront 分佈啟用連線日誌
+ 確定您擁有所選記錄目的地的必要許可
+ 對於跨帳戶交付，請設定適當的 IAM 政策
### 啟用連線日誌 （主控台）
1. 登入 AWS 管理主控台 並開啟位於 的 CloudFront 主控台[https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home)。
1. 從分發清單中，選取已啟用 mTLS 的分發。
1. 選擇 **Logging** (日誌記錄) 索引標籤。
1. 選擇**新增**。
1. 選取要接收日誌的服務：
+ **CloudWatch Logs**
+ **Firehose**
+ **Amazon S3**
1. 針對**目的地**，選取所選服務的資源：
+ 針對 CloudWatch Logs，輸入**日誌群組名稱**
+ 對於 Firehose，選取 **Firehose 交付串流**
+ 對於 Amazon S3，輸入**儲存貯體名稱** （選擇性使用字首）
1. (選用) 設定其他設定：
+ **欄位選擇：**選取要包含的特定日誌欄位。
+ **輸出格式：**從 JSON、Plain、w3c、Raw 或 Parquet （僅限 S3) 中選擇。
+ **欄位分隔符號：**指定如何分隔日誌欄位。
1. 選擇 **Save changes (儲存變更)**
### 啟用連線日誌 (AWS CLI)
下列範例示範如何使用 CloudWatch API 啟用連線日誌：
```
# Step 1: Create a delivery source
aws logs put-delivery-source \
--name "cf-mtls-connection-logs" \
--resource-arn "arn:aws:cloudfront::123456789012:distribution/E1A2B3C4D5E6F7" \
--log-type CONNECTION_LOGS
# Step 2: Create a delivery destination
aws logs put-delivery-destination \
--name "s3-destination" \
--delivery-destination-configuration \
"destinationResourceArn=arn:aws:s3:::amzn-s3-demo-bucket1"
# Step 3: Create the delivery
aws logs create-delivery \
--delivery-source-name "cf-mtls-connection-logs" \
--delivery-destination-arn "arn:aws:logs:us-east-1:123456789012:delivery-destination:s3-destination"
```
**注意**
使用 CloudWatch API 時，即使將日誌交付至其他區域，您也必須指定美國東部 （維吉尼亞北部） 區域 (us-east-1)。
## 連線日誌欄位
連線日誌包含每次 TLS 連線嘗試的詳細資訊：
| 欄位 | Description | 範例 |
| --- | --- | --- |
| eventTimestamp | 建立連線或失敗時的 ISO 8601 時間戳記 | 1731620046814 |
| connectionId | TLS 連線的唯一識別符 | oLHiEKbQSn8lkvJfA3D4gFowK3\$1iZ0g4i5nMUjE1Akod8TuAzn5nzg== |
| connectionStatus | mTLS 連線嘗試的狀態。 | Success 或 Failed |
| clientIp | 連線用戶端的 IP 地址 | 2001:0db8:85a3:0000:0000:8a2e:0370:7334 |
| clientPort | 用戶端使用的連接埠 | 12137 |
| serverIp | CloudFront 邊緣伺服器的 IP 地址 | 99.84.71.136 |
| distributionId | CloudFront 分佈 ID | E2DX1SLDPK0123 |
| distributionTenantId | CloudFront 分佈租用戶 ID （如適用） | dt\$12te1Ura9X3R2iCGNjW123 |
| tlsProtocol | 使用的 TLS 通訊協定版本 | TLSv1.3 |
| tlsCipher | 用於連線的 TLS 密碼套件 | TLS\$1AES\$1128\$1GCM\$1SHA256 |
| tlsHandshakeDuration | TLS 交握的持續時間，以毫秒為單位 | 153 |
| tlsSni | 來自 TLS 交握的伺服器名稱指示值 | d111111abcdef8.cloudfront.net |
| clientLeafCertSerialNumber | 用戶端憑證的序號 | 00:b1:43:ed:93:d2:d8:f3:9d |
| clientLeafCertSubject | 用戶端憑證的主旨欄位 | C=US, ST=WA, L=Seattle, O=Amazon.com, OU=CloudFront, CN=client.test.mtls.net |
| clientLeafCertIssuer | 用戶端憑證的發行者欄位 | C=US, ST=WA, L=Seattle, O=Amazon.com, OU=CloudFront, CN=test.mtls.net |
| clientLeafCertValidity | 用戶端憑證的有效期 | NotBefore=2025-06-05T23:28:21Z;NotAfter=2125-05-12T23:28:21Z |
| connectionLogCustomData | 透過 Connection Functions 新增的自訂資料 | REVOKED:00:b1:43:ed:93:d2:d8:f3:9d |
## 連線錯誤代碼
```
Failed:ClientCertMaxChainDepthExceeded
Failed:ClientCertMaxSizeExceeded
Failed:ClientCertUntrusted
Failed:ClientCertNotYetValid
Failed:ClientCertExpired
Failed:ClientCertTypeUnsupported
Failed:ClientCertInvalid
Failed:ClientCertIntentInvalid
Failed:ClientCertRejected
Failed:ClientCertMissing
Failed:TcpError
Failed:TcpTimeout
Failed:ConnectionFunctionError
Failed:ConnectionFunctionDenied
Failed:Internal
Failed:UnmappedConnectionError
```
當連線失敗時，CloudFront 會記錄特定原因代碼：
| Code | Description |
| --- | --- |
| ClientCertMaxChainDepthExceeded | 超過憑證鏈深度上限 |
| ClientCertMaxSizeExceeded | 超過憑證大小上限 |
| ClientCertUntrusted | 憑證不受信任 |
| ClientCertNotYetValid | 憑證尚無效 |
| ClientCertExpired | 憑證已過期 |
| ClientCertTypeUnsupported | 不支援憑證類型 |
| ClientCertInvalid | 憑證無效 |
| ClientCertIntentInvalid | 憑證意圖無效 |
| ClientCertRejected | 自訂驗證拒絕的憑證 |
| ClientCertMissing | 憑證遺失 |
| TcpError | 嘗試建立連線時發生錯誤 |
| TcpTimeout | 無法在逾時期間內建立連線 |
| ConnectionFunctionError | 在 Connection Function 執行期間擲回未攔截的例外狀況 |
| 內部 (Internal) | 發生內部服務錯誤 |
| UnmappedConnectionError | 發生錯誤，該錯誤不屬於任何其他類別 |