共用方式為

Azure Static Web Apps 中的自訂驗證

  • 發行項

Azure Static Web Apps 提供受控驗證，並使用由 Azure 管理的提供者註冊。 若要讓註冊更有彈性，您可以使用自訂註冊來覆寫預設值。

  • 自訂驗證也可讓您設定支援 OpenID Connect 的自訂提供者。 此設定允許多個外部提供者註冊。

  • 使用任何自訂註冊皆會停用所有預先設定的提供者。

注意

自訂驗證僅適用於 Azure Static Web Apps 標準方案。

設定自訂識別提供者

自訂識別提供者在設定檔的 auth 區段中進行設定。

為了避免將祕密放在原始程式碼控制中，設定會查看設定檔中名稱相符的應用程式設定。 您也可以選擇將祕密儲存在 Azure Key Vault。

若要建立註冊，請先建立下列應用程式設定：

設定名稱 值
AZURE_CLIENT_ID Microsoft Entra 應用程式註冊的應用程式 (用戶端) 識別碼。
`AZURE_CLIENT_SECRET_APP_SETTING_NAME 保留 Microsoft Entra 應用程式註冊用戶端密碼的應用程式設定名稱。

接下來，請使用下列範例在設定檔中設定提供者。

Microsoft Entra 提供者有兩個不同的版本。 第 1 版明確定義了 userDetailsClaim，讓承載可傳回使用者資訊。 相較之下，第 2 版根據預設會傳回使用者資訊，並在 openIdIssuer URL 中由 v2.0 指定。

Microsoft Entra 第 1 版

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretSettingName": "AZURE_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

務必將 <TENANT_ID> 取代為您的 Microsoft Entra 租用戶識別碼。

Microsoft Entra 第 2 版

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretSettingName": "AZURE_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

務必將 <TENANT_ID> 取代為您的 Microsoft Entra 租用戶識別碼。

如需如何設定 Microsoft Entra ID 的詳細資訊，請參閱使用現有註冊中的 App Service 驗證/授權文件。

若要設定哪些帳戶可以登入，請參閱修改應用程式支援的帳戶，並將 Microsoft Entra 應用程式限制為 Microsoft Entra 租用戶中的一組使用者。

注意

雖然 Microsoft Entra ID 的設定區段是 azureActiveDirectory，但平台會將其在 URL 中化名為 aad，用來登入、登出和清除使用者資訊。 請參閱驗證和與授權錯誤碼區段瞭解詳細資訊。

自訂憑證

使用下列步驟，將自訂憑證新增至您的 Microsoft Entra ID 應用程式註冊。

  1. 如果尚未這麼做，請將您的憑證上傳至 Microsoft Key Vault。

  2. 在您的靜態 Web 應用程式上新增受控識別。

    針對使用者指派的受控識別，請將靜態網站物件上的 keyVaultReferenceIdentity 屬性設定為使用者指派受控識別的 resourceId。

    如果您的受控識別為系統指派，請略過此步驟。

  3. 授與受控識別下列存取原則：

    • 袐密：取得/列出
    • 憑證：取得/列出

  4. 使用 clientSecretCertificateKeyVaultReference 值更新設定區段的 azureActiveDirectory 驗證設定區段，如下列範例所示：

    {
  "auth": {
    "rolesSource": "/api/GetRoles",
    "identityProviders": {
      "azureActiveDirectory": {
        "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/common/v2.0",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretCertificateKeyVaultReference": "@Microsoft.KeyVault(SecretUri=https://<KEY_VAULT_NAME>.azure.net/certificates/<CERTIFICATE_NAME>/<CERTIFICATE_VERSION_ID>)",
          "clientSecretCertificateThumbprint": "*"
        }
      }
    }
  }
}

    請務必將您的值取代 <> 所圍繞的預留位置。

    在袐密 URI 中，指定金鑰保存庫名稱和憑證名稱。 如果您想要固定至某版本，請包含憑證版本，否則請省略版本以允許執行階段選取最新版本的憑證。

    將 clientSecretCertificateThumbprint 設定為等於 *，以一律提取最新版本的憑證指紋。

驗證呼叫

識別提供者需要重新導向 URL 才能完成登入或登出要求。 大部分的提供者都需要您將呼叫 URL 新增至允許清單。 下列端點可作為重新導向的目的地。

類型 URL 模式
登入 https://<YOUR_SITE>/.auth/login/<PROVIDER_NAME_IN_CONFIG>/callback
Logout https://<YOUR_SITE>/.auth/logout/<PROVIDER_NAME_IN_CONFIG>/callback

如果您使用 Microsoft Entra ID，請使用 aad 作為 <PROVIDER_NAME_IN_CONFIG> 預留位置的值。

注意

這些 URL 由 Azure Static Web Apps 提供，接收來自驗證提供者的回應，您不需要在這些路由建立頁面。

登入、登出和使用者詳細資料

若要使用自訂識別提供者，請使用下列 URL 模式。

動作 模式
登入 /.auth/login/<PROVIDER_NAME_IN_CONFIG>
Logout /.auth/logout
使用者詳細資料 /.auth/me
清除使用者詳細資料 /.auth/purge/<PROVIDER_NAME_IN_CONFIG>

如果您使用 Microsoft Entra ID，請使用 aad 作為 <PROVIDER_NAME_IN_CONFIG> 預留位置的值。

管理角色

每位存取靜態 Web 應用程式的使用者都屬於一或多個角色。 使用者可以屬於兩個內建角色：

  • 匿名：所有使用者都會自動屬於匿名角色。
  • 已驗證：登入的所有使用者都屬於 已驗證的角色。

除了內建角色，您還可以將自訂角色指派給使用者，並在 staticwebapp.config.json 檔案中加以參考。

將使用者新增至角色

若要將使用者新增至角色，您可以產生邀請，藉此將使用者與特定角色產生關聯。 角色會在 staticwebapp.config.json 檔案中定義及維護。

建立邀請

邀請專屬於個別的授權提供者，因此當您選取要支援的提供者時，請考慮您的應用程式需求。 有些提供者會公開使用者的電子郵件地址，而有些則只提供網站的使用者名稱。

授權提供者 公開
Microsoft Entra ID 電子郵件地址
GitHub username
X username

使用下列步驟來建立邀請。

  1. 在 Azure 入口網站中移至 Static Web Apps 資源。
  2. 在 [設定] 底下，選取 [角色管理]。
  3. 選取 [邀請]。
  4. 從選項清單中選取 [授權的提供者]。
  5. 將收件者的使用者名稱或電子郵件地址新增至 [邀請詳細資料] 方塊中。
    • 針對 GitHub 和 X，輸入使用者名稱。 針對所有其他項目，輸入收件者的電子郵件地址。
  6. 從 [網域] 下拉式功能表，選取您靜態網站的網域。
    • 您選取的網域是出現在邀請中的網域。 如果您有與網站相關聯的自訂網域，請選擇自訂網域。
  7. 在 [角色] 方塊中，新增以逗號分隔的角色名稱清單。
  8. 輸入您希望邀請保持有效的最長時數。
    • 可能的最大限制為 168 個小時，也就是 7 天。
  9. 選取產生。
  10. 從 [邀請連結] 方塊中複製連結。
  11. 以電子郵件將邀請連結傳送給您要授與存取權的使用者。

當使用者選取邀請中的連結時，系統會提示他們使用其對應的帳戶登入。 成功登入之後，使用者會與選取的角色相關聯。

警告

請確定您的路由規則不會與選取的驗證提供者衝突。 使用路由規則封鎖提供者，會讓使用者無法接受邀請。

更新角色指派

  1. 在 Azure 入口網站中移至 Static Web Apps 資源。
  2. 在 [設定] 底下，選取 [角色管理]。
  3. 在清單中選取使用者。
  4. 編輯 [角色] 方塊中的角色清單。
  5. 選取更新。

移除使用者

  1. 在 Azure 入口網站中移至 Static Web Apps 資源。
  2. 在 [設定] 底下，選取 [角色管理]。
  3. 在清單中找出使用者。
  4. 勾選使用者資料列的核取方塊。
  5. 選取 [刪除]。

當您移除使用者時，請記住下列項目：

  • 移除使用者會使其權限失效。
  • 全球傳播可能需要幾分鐘的時間。
  • 如果將使用者新增回應用程式，則 userId 會變更。

下一步

以程式設計方式設定使用者角色