節點 Azure Functions 客戶端連結庫的驗證事件觸發程式

發行項
01/10/2024

Azure Functions 驗證事件觸發程式會處理所有後端處理， (例如令牌/json 架構驗證，) 用於驗證事件的傳入 Http 要求。並提供要搭配使用的強型別版本物件模型，這表示開發人員不需要事先瞭解要求和回應 json 承載。

此項目架構提供下列功能：

保護 API 呼叫的令牌驗證
物件模型、輸入和 IDE Intellisense
API 要求和回應架構的輸入和輸出驗證
版本控制
不需要重複使用程序代碼。

開始使用

安裝 npm 套件

npm install @azure/functions-authentication-events

必要條件

Azure 函式工具
Azure 函式核心工具
如果使用 Visual Studio Code 下列延伸模組：
- ms-azuretools.vscode-azurefunctions
- ms-dotnettools.csharp

驗證用戶端

當 Azure AD 驗證事件服務呼叫您的自定義擴充功能時，它會傳送 Authorization 具有 Bearer {token}的標頭。此權杖將代表服務對服務驗證，其中：

「資源」也稱為 「物件」是您註冊來代表 API 的應用程式。這會以 aud 令牌中的宣告表示。
「用戶端」是代表 Azure AD 驗證事件服務的 Microsoft 應用程式。 appId其值為 99045fe1-7639-4a75-9d4a-577b6ca3810f。這以下列方式表示：
- 如果您的應用程式accessTokenAcceptedVersion屬性設定2為，則azp令牌中的宣告。
- 如果您的資源應用程式的屬性設定1為或 null，appidaccessTokenAcceptedVersion則令牌中的宣告。

有三種方法可以處理令牌。您可以使用應用程式設定來自定義行為，如下所示，或透過本機環境中的 local.settings.json 檔案。

使用 Azure AD 驗證整合 Azure Functions 驗證令牌

在生產環境中執行函式時，強烈建議使用 Azure Functions Azure AD 驗證整合來驗證傳入令牌。

移至函式應用程式中的 [驗證] 索引標籤
按兩下 [新增識別提供者]
選取 [Microsoft] 作為識別提供者
選取[提供現有應用程式註冊的詳細資料]
Application ID輸入應用程式在 Azure AD 中代表 API 的

簽發者和允許的物件取決於 accessTokenAcceptedVersion 應用程式 (的屬性，可以在應用程式) 的「指令清單」中找到。

accessTokenAcceptedVersion如果屬性設定為 2：6。請設定 Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" 7. Set an 'Allowed Audience' to the Application ID (appId 的)

accessTokenAcceptedVersion如果屬性設定為 1 或 null：6。如果使用自定義功能變數名稱，請將Issuer URL to "https://sts.windows.net/{tenantId}/" 7. Set an 'Allowed Audience' to the Application ID URI (also known asidentifierUri). It should be in the format ofapi://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}'。

根據預設，驗證事件觸發程式會驗證是否已設定 Azure 函式驗證整合，而且它會檢查令牌中的用戶端是否已設定azp為99045fe1-7639-4a75-9d4a-577b6ca3810f透過令牌中的或 appid 宣告 () 。

如果您想要針對不是 Azure AD 驗證事件服務的一些其他客戶端測試 API，例如使用 Postman，您可以設定 選擇性 的應用程式設定：

AuthenticationEvents__CustomCallerAppId - 所需用戶端的 GUID。如果未提供， 99045fe1-7639-4a75-9d4a-577b6ca3810f 則會假設為。

讓觸發程式驗證令牌

在 Azure 函式服務中未載入的本機環境或環境中，觸發程式可以執行令牌驗證。設定下列應用程式設定：

AuthenticationEvents__TenantId - 您的租使用者識別碼
AuthenticationEvents__AudienceAppId - 與選項 1 中「允許的物件」相同的值。
AuthenticationEvents__CustomCallerAppId (選擇性) - 所需用戶端的 GUID。如果未提供， 99045fe1-7639-4a75-9d4a-577b6ca3810f 則會假設為。

範例 local.settings.json 檔案：

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__TenantId": "8615397b-****-****-****-********06c8",
    "AuthenticationEvents__AudienceAppId": "api://46f98993-****-****-****-********0038",
    "AuthenticationEvents__CustomCallerAppId": "46f98993-****-****-****-********0038"
  }
}

沒有令牌驗證

如果您想要在本機開發時不要驗證令牌，請設定下列應用程式設定：

AuthenticationEvents__BypassTokenValidation - 的值 true 會使觸發程式不會檢查令牌的驗證。

快速入門

Visual Studio Code
- 啟動 Visual Studio Code
- 透過命令選擇區執行終端機命令func init . --worker-runtime node
- 透過命令選擇區執行終端機命令func new
- 遵循專案建立提示
- 透過命令選擇區執行終端機命令npm install @azure/functions-authentication-events
- 透過命令選擇區執行終端機命令npm install
- 透過命令選擇區執行終端機命令npm run-script build
為了開發權杖驗證以進行測試：
將 AuthenticationEvents__BypassTokenValidation 應用程式密鑰新增至local.settings.json檔案中的[值] 區段，並將它的值設定為 true。如果您在本機環境中沒有local.settings.json檔案，請在函式應用程式的根目錄中建立一個檔案。

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AuthenticationEvents__BypassTokenValidation": true
  }
}

載入項目之後，您可以執行範例程式代碼，您應該會看到 Azure Functions 開發人員的應用程式載入您的端點。

重要概念

您可以在這裡找到 Azure .NET SDK 的重要概念

文件

其中一個函式已發佈，有一些關於記錄和計量的良好閱讀，可在這裡找到
如需 API 檔，請參閱 (連結 TBD)
一旦移至預覽，我們除了沒有重大變更之外，也就像移除指向私人預覽的 nuget 來源一樣簡單。

範例

若要測試令牌擴增，請執行下列動作。

開啟在上一個步驟中建立的專案。 (快速入門)
執行應用程式。 func host start
一旦 Azure Functions 開發人員的應用程式啟動，請複製隨應用程式一起顯示的接聽 URL。
注意：列出所有驗證函式，在此情況下，我們有一個稱為 “OnTokenIssuanceStart” 的函式接聽程序註冊
您的函式端點接著會是接聽 URL 和函式的組合，例如：「http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)&function=OnTokenIssuanceStart”
使用 Postman 或 Fiddler 之類的內容張貼下列承載。
如需使用Postman的步驟，請參閱 (連結TBD)

{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/00000001-0000-0ff1-ce00-000000000000/applications/ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "00000001-0000-0ff1-ce00-000000000000",
        "authenticationEventListenerId": "f2390d57-9664-4dde-b625-f0115925e1e2",
        "customAuthenticationExtensionId": "9cc1c1ed-5f04-4fdf-85c0-94a7c6ea819c",
        "authenticationContext": {
            "correlationId": "f4bd1870-b774-4fa5-ba78-e08ac6be14c0",
            "client": {
                "ip": "127.0.0.1",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "resourceServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "user": {
                "companyName": "Evo Sts Test",
                "country": "",
                "id": "69d24544-c420-4721-a4bf-106f2378d9f6",
                "mail": "testadmin@evostsoneboxtest.com",
                "onPremisesSamAccountName": "testadmin",
                "onPremisesSecurityIdentifier": "testadmin",
                "preferredDataLocation": "",
                "userPrincipalName": "testadmin@evostsoneboxtest.com"
            }
        }
    }
}

您應該會看到此回應：

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "ProvideClaimsForToken",
                "claims": [
                    {
                        "DateOfBirth": "01/01/2000"
                    },
                    {
                        "CustomRoles": [
                            "Writer",
                            "Editor"
                        ]
                    }
                ]
            }
        ]
    }
}

疑難排解

Visual Studio Code
- 如果在 Visual Studio Code 中執行，您會收到本機 Azure 記憶體模擬器行無法使用的錯誤，您可以手動啟動模擬器。！ (注意：Azure 記憶體模擬器現在已被取代，建議的取代專案是 Azurite)
- 如果在 Mac 上使用 Visual Studio Code，請使用 Azurite
- 如果您在 Windows 上看到下列錯誤， (嘗試執行所投影專案時) 錯誤。
- 您可以在 powershell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine 中執行此指令來解決此問題，如需詳細資訊，請參閱這裡和這裡

下一步

如需 Azure SDK 的詳細資訊，請參閱此網站

發佈

請遵循這裡的指示來建立和發佈您的 Azure 應用程式。 </azure/azure-functions/functions-develop-vs？tabs=in-process#publish-to-azure>
若要判斷已發佈的張貼端點，請結合您建立的 azure 函式端點、路由傳送至接聽程式和接聽程式程式代碼，您可以流覽至您的 Azure 函式應用程式、選取 [應用程式密鑰] 並複製AuthenticationEvents_extension的值來找到接聽程式代碼。
例如：“https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)&function=OnTokenIssuanceStart”
請確定您的生產環境具有正確的令牌驗證應用程式設定。
同樣地，您可以將上述承載張貼至新的端點，以測試已發佈的函式。

參與

如需參與此存放庫的詳細資訊，請參閱參與指南。

此專案歡迎參與和提供建議。大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。如需詳細資料，請前往 https://cla.microsoft.com 。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。請遵循 bot 提供的指示。您只需要使用 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。

共用方式為