노드용 Azure Functions 클라이언트 라이브러리에 대한 인증 이벤트 트리거
Azure Functions 대한 인증 이벤트 트리거는 인증 이벤트에 대한 들어오는 Http 요청에 대한 모든 백 엔드 처리(예: 토큰/json 스키마 유효성 검사)를 처리합니다. 또한 개발자에게 작업할 강력한 형식의 버전이 지정된 개체 모델을 제공합니다. 즉, 개발자는 요청 및 응답 json 페이로드에 대한 사전 지식이 필요하지 않습니다.
이 프로젝트 프레임워크는 다음과 같은 기능을 제공합니다.
- API 호출을 보호하기 위한 토큰 유효성 검사
- 개체 모델, 입력 및 IDE intellisense
- API 요청 및 응답 스키마의 인바운드 및 아웃바운드 유효성 검사
- 버전 관리
- 상용구 코드가 필요하지 않습니다.
시작
npm 패키지 설치
npm install @azure/functions-authentication-events
사전 요구 사항
- Azure 함수 도구
- Azure Function Core 도구
- Visual Studio Code 사용하는 경우 다음 확장을 사용합니다.
클라이언트 인증
Azure AD 인증 이벤트 서비스에서 사용자 지정 확장을 호출하면 가 있는 헤더를 Authorization 보냅니다Bearer {token}. 이 토큰은 다음과 같은 서비스 인증을 나타냅니다.
- 대상 그룹이라고도 하는 '리소스'는 API를 나타내기 위해 등록하는 애플리케이션입니다. 토큰의 클레임으로
aud표시됩니다. - '클라이언트'는 Azure AD 인증 이벤트 서비스를 나타내는 Microsoft 애플리케이션입니다. 값은 입니다
appId99045fe1-7639-4a75-9d4a-577b6ca3810f. 이 값은 다음으로 표시됩니다.azp애플리케이션accessTokenAcceptedVersion속성이 로 설정된2경우 토큰의 클레임입니다.appid리소스 애플리케이션의 속성이 또는null로 설정된1경우 토큰의accessTokenAcceptedVersion클레임입니다.
토큰을 처리하는 방법에는 세 가지가 있습니다. 아래와 같이 애플리케이션 설정을 사용하거나 로컬 환경의 local.settings.json 파일을 통해 동작을 사용자 지정할 수 있습니다.
Azure Functions Azure AD 인증 통합을 사용하여 토큰 유효성 검사
프로덕션 환경에서 함수를 실행하는 경우 들어오는 토큰의 유효성을 검사하기 위해 Azure Functions Azure AD 인증 통합을 사용하는 것이 좋습니다.
- 함수 앱의 "인증" 탭으로 이동합니다.
- "ID 공급자 추가"를 클릭합니다.
- ID 공급자로 "Microsoft"를 선택합니다.
- "기존 앱 등록의 세부 정보 제공"을 선택합니다.
Application IDAzure AD API를 나타내는 앱의 를 입력합니다.
발급자 및 허용 대상 그룹은 애플리케이션의 속성에 accessTokenAcceptedVersion 따라 달라집니다(애플리케이션의 "매니페스트"에서 찾을 수 있습니다).
속성이 accessTokenAcceptedVersion : 6으로 2설정된 경우 appId를 Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" 7. Set an 'Allowed Audience' to the Application ID (설정합니다.)
속성이 accessTokenAcceptedVersion 또는 null: 6으로 1 설정된 경우 사용자 지정 도메인 이름을 사용하는 경우 identifierUri). It should be in the format ofapi://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}'를 설정합니다Issuer URL to "https://sts.windows.net/{tenantId}/" 7. Set an 'Allowed Audience' to the Application ID URI (also known as.
기본적으로 인증 이벤트 트리거는 Azure Function 인증 통합이 구성되어 있는지 확인하고 토큰의 클라이언트가 토큰의 또는 appid 클레임을 통해 azp 로 설정되어 99045fe1-7639-4a75-9d4a-577b6ca3810f 있는지 검사.
Postman 사용과 같이 인증 이벤트 서비스를 Azure AD 않은 다른 클라이언트에 대해 API를 테스트하려는 경우 선택적 애플리케이션 설정을 구성할 수 있습니다.
- AuthenticationEvents__CustomCallerAppId - 원하는 클라이언트의 guid입니다. 제공되지 않으면 가
99045fe1-7639-4a75-9d4a-577b6ca3810f가정됩니다.
트리거가 토큰의 유효성을 검사하도록 합니다.
Azure Function Service에서 호스트되지 않는 로컬 환경 또는 환경에서 트리거는 토큰 유효성 검사를 수행할 수 있습니다. 다음 애플리케이션 설정을 지정합니다.
- AuthenticationEvents__TenantId - 테넌트 ID
- 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실행
- 테스트를 위한 토큰 유효성 검사의 개발 목적 턴:
- local.settings.json 파일의 "값" 섹션에 AuthenticationEvents__BypassTokenValidation 애플리케이션 키를 추가하고 값을 true로 설정합니다. 로컬 환경에 local.settings.json 파일이 없는 경우 함수 앱의 루트에 파일을 만듭니다.
{
"IsEncrypted": false,
"Values": {
"AzureWebJobsStorage": "UseDevelopmentStorage=true",
"FUNCTIONS_WORKER_RUNTIME": "node",
"AuthenticationEvents__BypassTokenValidation": true
}
}
- 프로젝트가 로드되면 샘플 코드를 실행할 수 있으며 Azure 함수 개발자의 애플리케이션이 엔드포인트를 로드하는 것을 볼 수 있습니다.
주요 개념
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 Storage 에뮬레이터를 사용할 수 없는 경우 에뮬레이터를 수동으로 시작할 수 있습니다.! (참고: Azure Storage 에뮬레이터는 이제 더 이상 사용되지 않으며 제안된 대체는 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을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. CLA를 사용하여 모든 리포지토리에서 한 번만 이 작업을 수행해야 합니다.
이 프로젝트에는 Microsoft Open Source Code of Conduct(Microsoft 오픈 소스 준수 사항)가 적용됩니다. 자세한 내용은 Code of Conduct FAQ(규정 FAQ)를 참조하세요. 또는 추가 질문이나 의견은 opencode@microsoft.com으로 문의하세요.
Azure SDK for JavaScript