Azure Service Fabric 中的中央秘密服務

中央密碼服務 (CSS) (也稱為中央密碼存放區)是一種 Service Fabric 系統服務,其目的是要保護叢集中的秘密。 CSS 可簡化 SF 應用程式的秘密管理,而不需要依賴加密的參數。

集中式秘密服務是持久、複寫的叢集中秘密快取;儲存在 CSS 中的秘密會待用加密至客戶提供的加密憑證。 CSS 提供用戶端 Api 來管理密碼,可供實體驗證為叢集或叢集系統管理使用者存取。 Service Fabric 執行時間應用程式模型會與 css 整合,讓應用程式參數的宣告成為 css 秘密參考。

CSS 也有助於布建宣告為KeyVault 秘密 uri的應用程式秘密,並結合Azure 部署 Service Fabric 應用程式的受控識別

集中式秘密服務並非用來取代專用的外部秘密管理服務,例如 Azure Key Vault。

注意

在執行早于7.1 之版本的 SF 叢集上啟用 CSS 時。CU3,如果叢集設定為 Windows 驗證或未正確宣告, EncryptionCertificateThumbprint 或未安裝對應的憑證,則啟動可能會失敗,並讓 CSS 處於永久狀況不良的狀態。 無論是哪一種情況,建議將叢集升級為比7.1 新的 SF 執行階段版本。 請先 CU3 再繼續。

啟用中央秘密服務

若要啟用中央密碼服務,請更新叢集設定,如下所述。 建議您使用與您的叢集憑證不同的加密憑證。 此憑證必須安裝在所有節點上。

{ 
    "fabricSettings": [
        {
            "name":  "CentralSecretService",
            "parameters":  [
                {
                    "name":  "DeployedState",
                    "value":  "enabled"
                },
                {
                    "name" : "EncryptionCertificateThumbprint",
                    "value": "<thumbprint>"
                },
                {
                    "name":  "MinReplicaSetSize",
                    "value":  "1"
                },
                {
                    "name":  "TargetReplicaSetSize",
                    "value":  "3"
                }
            ]
        }
    ]
}

注意

在 Service Fabric版本 8.0中引進的設定設定 "DeployedState" 是啟用或停用 CSS 的慣用機制;此函式是由設定設定 "IsEnabled" 在先前的版本中提供,現在已被視為過時。

集中秘密服務秘密模型

中央密碼服務 API 會公開兩種類型:秘密資源和秘密版本。 Secret 資源類型代表在概念上,用於特定用途的單一秘密系列版本;範例包括:連接字串、密碼、端點憑證。 Secret 資源類型的物件包含與該秘密相關聯的中繼資料,尤其是類型、內容類型和描述。 秘密版本類型代表其相關密碼的特定實例,並將密碼純文字儲存 (加密) ;繼續進行上述範例,秘密版本包含目前的密碼值,憑證物件在月底的結尾之前都是有效的。更新這些秘密時,應該 (產生新的秘密版本,並將其新增至 CSS) 。

將具體化模型時,下列是在 CSS 執行中所執行和強制執行的規則:

  • 秘密資源可能有零或多個版本
  • 每個秘密版本都是特定秘密資源的子系;版本只可有一個父資源
  • 可能會刪除個別的秘密版本,而不會影響相同秘密的其他版本
  • 刪除秘密資源會導致刪除其所有版本
  • 秘密版本的值不可變

可以在這裡找到秘密資源的一組完整 REST 管理 api,也可以在 這裡找到秘密版本。

宣告秘密資源

您可以使用 REST API 來建立秘密資源。

注意

如果叢集使用 Windows 驗證但沒有 HttpGateway 憑證,則會透過不安全的 HTTP 通道傳送 REST 要求。 若要啟用此通道的 TLS,應更新叢集定義以指定 HTTP 閘道伺服器憑證。

若要 supersecret 使用 REST API 建立秘密資源,請對進行 PUT 要求 https://<clusterfqdn>:19080/Resources/Secrets/supersecret?api-version=6.4-preview 。 您必須使用叢集憑證或系統管理用戶端憑證來進行驗證,以建立秘密資源。

$json = '{"properties": {"kind": "inlinedValue", "contentType": "text/plain", "description": "supersecret"}}'
Invoke-WebRequest  -Uri https://<clusterfqdn>:19080/Resources/Secrets/supersecret?api-version=6.4-preview -Method PUT -CertificateThumbprint <CertThumbprint> -Body $json

設定秘密值

使用下列腳本來使用 REST API 設定秘密值。

$Params = '{"properties": {"value": "mysecretpassword"}}'
Invoke-WebRequest -Uri https://<clusterfqdn>:19080/Resources/Secrets/supersecret/values/ver1?api-version=6.4-preview -Method PUT -Body $Params -CertificateThumbprint <ClusterCertThumbprint>

檢查秘密值

Invoke-WebRequest -CertificateThumbprint <ClusterCertThumbprint> -Method POST -Uri "https:<clusterfqdn>/Resources/Secrets/supersecret/values/ver1/list_value?api-version=6.4-preview"

在您的應用程式中使用秘密

應用程式可以從 CSS 取用秘密,方法是將它宣告為環境變數,或指定應將秘密純文字序列化的路徑。 遵循下列步驟來參考 CSS 秘密:

  1. 使用下列程式碼片段,在 settings.xml 檔案中新增區段。 請注意,此值的格式為 { secretname:version }。
     <Section Name="testsecrets">
      <Parameter Name="TopSecret" Type="SecretsStoreRef" Value="supersecret:ver1"/
     </Section>
  1. 匯入 ApplicationManifest.xml 中的區段。
<ServiceManifestImport>
<ServiceManifestRef ServiceManifestName="testservicePkg" ServiceManifestVersion="1.0.0" />
<ConfigOverrides />
<Policies>
 <ConfigPackagePolicies CodePackageRef="Code">
   <ConfigPackage Name="Config" SectionName="testsecrets" EnvironmentVariableName="SecretPath" />
   </ConfigPackagePolicies>
</Policies>
</ServiceManifestImport>

範例1:將秘密掛接至容器。 在容器內提供秘密所需的唯一變更就是中的 specify 掛接點 <ConfigPackage> 。 下列程式碼片段是修改過的 ApplicationManifest.xml

   <ServiceManifestImport>
       <ServiceManifestRef ServiceManifestName="testservicePkg" ServiceManifestVersion="1.0.0" />
       <ConfigOverrides />
       <Policies>
         <ConfigPackagePolicies CodePackageRef="Code">
           <ConfigPackage Name="Config" SectionName="testsecrets" MountPoint="C:\secrets" EnvironmentVariableName="SecretPath" />
           <!-- Linux Container
            <ConfigPackage Name="Config" SectionName="testsecrets" MountPoint="/mnt/secrets" EnvironmentVariableName="SecretPath" />
           -->
         </ConfigPackagePolicies>
       </Policies>
     </ServiceManifestImport>

秘密可在容器內的掛接點底下取得。

範例2:指定以將秘密系結至進程環境變數 Type='SecretsStoreRef 。 下列程式碼片段是如何 supersecret ver1 MySuperSecretServiceManifest.xml 中將版本系結至環境變數的範例。

   <EnvironmentVariables>
     <EnvironmentVariable Name="MySuperSecret" Type="SecretsStoreRef" Value="supersecret:ver1"/>
   </EnvironmentVariables>

環境變數 SecretPath 會指向儲存所有秘密的目錄。 區段底下所列的每個參數 testsecrets 都會儲存在不同的檔案中。 應用程式現在可以使用密碼,如下所示:

secretValue = IO.ReadFile(Path.Join(Environment.GetEnvironmentVariable("SecretPath"),  "TopSecret"))

輪替中央秘密服務加密憑證

請務必注意,憑證仍然有效,以供解密超過到期日。 目前,我們建議您在輪替之後繼續布建過去的加密憑證,以降低鎖定的機會。 輪替 CSS 加密憑證需要下列步驟:

  1. 將新憑證布建到叢集的每個節點。 目前,請勿移除/繼續布建先前的加密憑證。
  2. 啟動叢集設定升級,將的值變更為 EncryptionCertificateThumbprint 新憑證的 sha-1 指紋。 升級完成時,CSS 會開始將其現有的內容重新加密為新的加密憑證。 在此時間點之後新增至 CSS 的所有秘密都會直接加密至新的加密憑證。 由於將所有受到新憑證保護之秘密的融合都是非同步,因此,必須在所有節點上都安裝舊的加密憑證,並且可供 CSS 使用。

從您的叢集中移除中央秘密服務

從叢集中移除中央密碼服務保管庫需要兩個升級。 第一次升級功能會停用 CSS,而第二次升級則會從叢集定義中移除服務,包括永久刪除其內容。 這兩階段程式可避免意外刪除服務,並可協助確保在移除過程中不會有任何孤立的 CSS 相依性。 這項功能可從 SF 8.0 版開始提供。

步驟1:更新要移除的 CSS DeployedState

"IsEnabled" = "true" 或將叢集定義升級 "DeployedState" = "enabled"

{
    "name":  "DeployedState",
    "value":  "removing"
}

一旦中央密碼服務進入已部署狀態 Removing ,它就會拒絕所有連入的秘密 API 呼叫,不論是直接 REST 呼叫,還是啟用包含 SecretStoreRefs 或 KeyVaultReferences 的服務。 叢集中仍相依于 CSS 的任何應用程式或元件會進入警告狀態。 如果發生這種情況,就應該復原升級至已部署狀態 Removing ; 如果升級已成功,則應該起始新的升級,將 CSS 變更回 DeployedState = Enabled 。 如果中央密碼服務在部署狀態下收到要求 Removing ,則會傳回 HTTP 代碼 401 (未授權的) ,並使其成為警告健全狀況狀態。

步驟2:將 CSS DeployedState 更新為停用

將叢集定義從升級 "DeployedState" = "removing"

{
    "name":  "DeployedState",
    "value":  "disabled"
}

中央密碼服務應該不會再于叢集中執行,且不會出現在系統服務清單中。 CSS 的內容無可挽回嚴重遺失。

下一步