關聯 CloudFront 連線函數

CloudFront Connection Functions 可讓您在 TLS 交握期間實作自訂憑證驗證邏輯，提供內建 mTLS 身分驗證功能的延伸。

什麼是連線函數？

Connection Functions 是在用戶端憑證經過驗證後，在 TLS 交握期間執行的 JavaScript 函數。已驗證的用戶端憑證會傳遞至 Connection Function，此時 Connection Function 可以對是否授予存取權進行額外判斷。如需連線函數的詳細資訊，請參閱 使用 CloudFront Functions 在邊緣進行自訂。

Connection Functions 如何使用 mTLS

當用戶端嘗試建立與 CloudFront 分佈的 mTLS 連線時，會發生下列順序：

1. 用戶端使用 CloudFront 節點啟動 TLS 交握。

2. CloudFront 請求和接收用戶端憑證。

3. CloudFront 會對信任存放區執行標準憑證驗證。

4. 如果憑證通過標準驗證，CloudFront 會叫用您的連線函數。如果在 ViewerMtlsConfig 中啟用了 IgnoreCertificateExpiry，則您的過期但無效憑證也會傳遞至 Connection Function。如果用戶端憑證無效，將不會叫用連線函數。

5. 您的 Connection Function 會收到剖析的憑證資訊和連線詳細資訊。

6. 您的函數會根據自訂邏輯做出允許/拒絕決策。

7. CloudFront 會根據您的決定完成或終止 TLS 連線。

驗證模式和選用模式 （當用戶端呈現憑證時） 都會叫用連線函數。

請求提高連線函數配額

請求提高 的連線函數配額 AWS 帳戶。

請求增加連線函數配額

1. 登入 AWS 管理主控台 並開啟位於 的 CloudFront 主控台https://console.aws.amazon.com/cloudfront/v4/home。

2. 在導覽視窗中，選擇函數。

3. 選擇連線函數索引標籤

4. 針對請求，請選擇連結以聯絡 CloudFront 支援工程。

5. CloudFront 支援工程審查您的請求。審核程序最多可能需要兩天的時間。

請求獲得核准後，您可以在帳戶中建立連線函數，並在使用交互 TLS 時將其與一或多個分佈建立關聯。

建立連線函數

您可以使用 CloudFront 主控台或 CLI AWS 建立連線函數。

建立連線函數 （主控台）

1. 登入 AWS 管理主控台 並開啟位於 的 CloudFront 主控台https://console.aws.amazon.com/cloudfront/v4/home。

2. 在導覽視窗中，選擇函數。

3. 選擇連線函數索引標籤，然後選擇建立連線函數。

4. 輸入您 AWS 帳戶中唯一的函數名稱。

5. 選擇繼續。

6. 在函數編輯器中，撰寫您的 JavaScript 程式碼以進行憑證驗證。函數處理常式必須呼叫允許或拒絕。

7. 選用：KeyValue 存放區可以與連線函數建立關聯，以實作撤銷控制。

8. 選擇儲存變更。

建立連線函數 (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。

2. 在導覽窗格中，選擇函數

3. 選擇連線函數索引標籤，然後選取您的連線函數。

4. 選擇發佈以將其移至 LIVE 階段。

5. 在發佈區段下方的關聯分佈表格中，選擇新增關聯。

6. 選取已啟用檢視器 mTLS 的分佈，以便與之建立關聯。

或者，也可以從分佈詳細資訊頁面關聯已發佈的連線函數。

1. 導覽至列出所有分發的主控台首頁。

2. 選取您要關聯的分佈。

3. 選擇一般索引標籤。

4. 在 Settings (設定) 區段中，選擇 Edit (編輯)。

5. 在連線區段中，尋找檢視器交互身分驗證 (mTLS)。

6. 針對連線函數，選取您的函數。

7. 選擇儲存變更。

建立連線函數 (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 實作的行為。如需設定其他設定的詳細指示，例如選用的用戶端憑證驗證模式，請參閱 設定其他設定。