App Service 인증의 API 및 런타임 버전 관리

이 문서에서는 App Service에서 기본 제공 인증 및 권한 부여의 API 및 런타임 버전을 사용자 지정하는 방법을 설명합니다.

App Service 인증을 위한 관리 API에는 두 가지 버전이 있습니다. V2 버전은 Azure Portal의 인증 환경에 필요합니다. 이미 V1 API를 사용하는 앱은 몇 가지 변경 사항이 적용된 후 V2 버전으로 업그레이드할 수 있습니다. 특히 비밀 구성은 슬롯 고정 애플리케이션 설정으로 이동해야 합니다. 포털에 있는 앱의 인증 섹션에서 비밀 구성을 자동으로 이동할 수 있습니다.

구성 버전 업데이트

Warning

V2로 마이그레이션하면 Azure Portal, Azure CLI 및 Azure PowerShell의 기존 환경과 같은 일부 클라이언트를 통해 애플리케이션에 대한 App Service 인증/권한 부여 기능을 관리할 수 없습니다. 이 마이그레이션은 되돌릴 수 없습니다.

V2 API는 V1과 마찬가지로 Microsoft 계정을 고유 공급자로 만들거나 편집하는 것을 지원하지 않습니다. 오히려, 통합된 Microsoft ID 플랫폼을 활용하여 Microsoft Entra 계정과 개인 Microsoft 계정 모두로 사용자를 로그인시킵니다. V2 API로 전환하면 V1 Microsoft Entra 구성을 사용하여 Microsoft ID 플랫폼 공급자를 구성합니다. V1 Microsoft 계정 공급자는 마이그레이션 프로세스에서 계속 진행되며 정상적으로 계속 작동하지만 최신 Microsoft ID 플랫폼 모델로 이동해야 합니다. 자세한 내용은 구성을 Microsoft Entra 공급자로 전환하세요.

자동화된 마이그레이션 프로세스는 공급자 비밀을 애플리케이션 설정으로 이동한 다음 나머지 구성을 새 형식으로 변환합니다. 자동 마이그레이션을 사용하려면 다음을 수행합니다.

  1. 포털에서 앱으로 이동하고 왼쪽 창에서 설정>인증 을 선택합니다.
  2. 앱이 V1 모델로 구성된 경우 업그레이드 단추가 표시됩니다.
  3. 업그레이드 단추를 선택합니다. 확인 프롬프트에서 설명을 검토합니다. 마이그레이션을 수행할 준비가 되면 프롬프트에서 업그레이드를 선택합니다.

수동으로 마이그레이션 관리

다음 단계를 사용하면 앞에서 설명한 자동 버전을 사용하지 않으려는 경우 애플리케이션을 V2 API로 수동으로 마이그레이션할 수 있습니다.

애플리케이션 설정으로 비밀 이동

ID 공급자 비밀을 애플리케이션 설정으로 이동하려면 다음 단계를 완료합니다.

  1. V1 API를 사용하여 기존 구성을 가져옵니다.

    az webapp auth show -g <group_name> -n <app_name>

    결과로 발생한 JSON 페이로드에 구성한 각 공급자에 사용되는 비밀 값을 기록해 둡니다.

    • Microsoft Entra: clientSecret
    • Google: googleClientSecret
    • 페이스 북: facebookAppSecret
    • X: twitterConsumerSecret
    • Microsoft 계정: microsoftAccountClientSecret

    중요

    비밀 값은 중요한 보안 자격 증명이므로 신중하게 처리해야 합니다. 이러한 값을 공유하거나 로컬 머신에 유지하지 마세요.

  2. 각 비밀 값에 관한 슬롯 고정 애플리케이션 설정을 만듭니다. 각 애플리케이션 설정의 이름을 선택할 수 있습니다. 해당 값은 이전 단계에서 얻은 값과 일치하거나 해당 값으로 만든 Azure Key Vault 비밀을 참조 해야 합니다.

    설정을 만들려면 Azure Portal을 사용하거나 각 공급자에 대해 다음 명령의 변형을 실행할 수 있습니다.

    # For web apps, Google example    
az webapp config appsettings set -g <group_name> -n <app_name> --slot-settings GOOGLE_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

# For Azure Functions, X example
az functionapp config appsettings set -g <group_name> -n <app_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

    참고

    이 구성에 대한 애플리케이션 설정은 슬롯 고정으로 표시되어야 합니다. 즉, 슬롯 교환 작업 중에 환경 간에 이동하지 않습니다. 인증 구성이 환경에 연결되므로 이 구성이 필요합니다.

  3. authsettings.json이라는 새 JSON 파일을 만듭니다. 이전에 받은 출력을 가져와 각 비밀 값을 제거합니다. 파일에 나머지 출력을 추가하여 비밀이 포함되지 않도록 합니다. 경우에 따라 구성에 빈 문자열이 포함된 배열이 있을 수 있습니다. microsoftAccountOAuthScopes이(가) 아닌지 확인하십시오. 이 경우 값을 null.로 변경합니다.

  4. 각 공급자를 위해 이전에 만든 애플리케이션 설정 이름을 가리키는 authsettings.json에 속성을 추가합니다.

    • Microsoft Entra: clientSecretSettingName
    • Google: googleClientSecretSettingName
    • 페이스 북: facebookAppSecretSettingName
    • X: twitterConsumerSecretSettingName
    • Microsoft 계정: microsoftAccountClientSecretSettingName

    이 작업 후의 설정 파일은 다음과 유사할 수 있습니다. 이 경우 Microsoft Entra ID에 대해서만 구성됩니다.

    {
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myresourcegroup/providers/Microsoft.Web/sites/mywebapp/config/authsettings",
    "name": "authsettings",
    "type": "Microsoft.Web/sites/config",
    "location": "Central US",
    "properties": {
        "enabled": true,
        "runtimeVersion": "~1",
        "unauthenticatedClientAction": "AllowAnonymous",
        "tokenStoreEnabled": true,
        "allowedExternalRedirectUrls": null,
        "defaultProvider": "AzureActiveDirectory",
        "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "clientSecret": "",
        "clientSecretSettingName": "MICROSOFT_IDENTITY_AUTHENTICATION_SECRET",
        "clientSecretCertificateThumbprint": null,
        "issuer": "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/",
        "allowedAudiences": [
            "https://mywebapp.azurewebsites.net"
        ],
        "additionalLoginParams": null,
        "isAadAutoProvisioned": true,
        "aadClaimsAuthorization": null,
        "googleClientId": null,
        "googleClientSecret": null,
        "googleClientSecretSettingName": null,
        "googleOAuthScopes": null,
        "facebookAppId": null,
        "facebookAppSecret": null,
        "facebookAppSecretSettingName": null,
        "facebookOAuthScopes": null,
        "gitHubClientId": null,
        "gitHubClientSecret": null,
        "gitHubClientSecretSettingName": null,
        "gitHubOAuthScopes": null,
        "twitterConsumerKey": null,
        "twitterConsumerSecret": null,
        "twitterConsumerSecretSettingName": null,
        "microsoftAccountClientId": null,
        "microsoftAccountClientSecret": null,
        "microsoftAccountClientSecretSettingName": null,
        "microsoftAccountOAuthScopes": null,
        "isAuthFromFile": "false"
    }   
}

  5. 이 파일을 앱에 대한 새 인증/권한 부여 구성으로 제출합니다.

    az rest --method PUT --url "/subscriptions/<subscription_id>/resourceGroups/<group_name>/providers/Microsoft.Web/sites/<app_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json

  6. 파일을 제출한 후에도 앱이 예상대로 작동하고 있는지 확인합니다.

  7. 이전 단계에서 사용한 파일을 삭제합니다.

이제 ID 공급자 비밀을 애플리케이션 설정으로 저장하도록 앱을 마이그레이션했습니다.

구성을 Microsoft Entra 공급자로 전환

기존 구성에 Microsoft 계정 공급자가 포함되어 있고 Microsoft Entra 공급자가 없는 경우 구성을 Microsoft Entra 공급자로 변경한 다음 마이그레이션을 수행할 수 있습니다.

  1. Azure Portal에서 앱 등록 으로 이동하여 Microsoft 계정 공급자와 연결된 등록을 찾습니다. 소유된 애플리케이션 제목 아래에 있을 수 있습니다.
  2. 등록에 대한 인증(미리 보기) 페이지로 이동합니다. 리디렉션 URI에서 항목이 로 끝나는 것을 볼 수 있습니다/.auth/login/microsoftaccount/callback. 이 URI를 복사합니다.
  3. 방금 복사한 URI와 일치하는 새 URI를 추가하되, 마지막에 /.auth/login/aad/callback로 끝내세요. 이 URI를 사용하면 App Service 인증/권한 부여 구성에서 등록을 사용할 수 있습니다.
  4. 포털에서 앱으로 이동합니다. 설정>인증 선택합니다.
  5. Microsoft 계정 공급자에 대한 구성을 수집합니다.
  6. 고급 관리 모드를 사용하여 이전 단계에서 수집한 클라이언트 ID 및 클라이언트 비밀 값을 제공하여 Microsoft Entra 공급자를 구성합니다. 발급자 URL의 경우 .를 사용합니다<authentication-endpoint>/<tenant-id>/v2.0. 클라우드 환경에서 <authentication-endpoint>을(를) 자신의 클라우드 환경의 인증 엔드포인트로 교체하십시오 (예: "https://login.microsoftonline.com"", 전역 Microsoft Entra ID의 경우). <tenant-id>를 디렉터리(테넌트) ID로 바꿉니다.
  7. 구성을 저장한 후 브라우저에서 사이트의 엔드포인트로 이동하고 /.auth/login/aad 로그인 흐름을 완료하여 로그인 흐름을 테스트합니다.
  8. 이 시점에서 구성을 성공적으로 복사했지만 기존 Microsoft 계정 공급자 구성은 그대로 유지됩니다. 제거하기 전에 앱의 모든 부분이 로그인 링크 등을 통해 Microsoft Entra 공급자를 참조하는지 확인합니다. 앱의 모든 부분이 예상대로 작동하는지 확인합니다.
  9. 모든 항목이 Microsoft Entra 공급자와 함께 작동하는지 확인하면 Microsoft 계정 공급자 구성을 제거할 수 있습니다.

Warning

Microsoft Entra 앱 등록에 대해 지원되는 계정 유형을 수정하여 두 등록을 수렴할 수 있습니다. 그러나 이 구성은 Microsoft 계정 사용자에 대한 새 동의 프롬프트를 강제로 적용하며, 이러한 사용자의 ID 클레임은 구조가 다를 수 있으며, sub 특히 새 앱 ID가 사용 중이기 때문에 값을 변경할 수 있습니다. 이 방법은 완전히 이해하지 않는 한 권장되지 않습니다. 대신 V2 API 표면에서 두 등록을 위한 지원을 대기해야 합니다.

V2로 전환

이전 단계를 완료한 후 Azure Portal에서 앱으로 이동합니다. 인증(미리 보기) 섹션을 선택합니다.

대안으로, 사이트 리소스 아래의 config/authsettingsv2 리소스에 대해 PUT 요청을 수행할 수 있습니다. 페이로드에 대한 스키마는 파일 기반 구성에서 캡처된 스키마와 동일합니다.

앱을 특정 인증 런타임 버전에 고정

인증/권한 부여를 사용하도록 설정하면 기능 개요에 설명된 대로 플랫폼 미들웨어가 HTTP 요청 파이프라인에 삽입됩니다. 이 플랫폼 미들웨어는 루틴 플랫폼 업데이트의 일부로 새로운 기능 및 향상된 기능이 정기적으로 업데이트됩니다. 기본적으로 웹 또는 함수 앱은 이 플랫폼 미들웨어의 최신 버전에서 실행됩니다. 이러한 자동 업데이트는 항상 이전 버전과 호환됩니다. 그러나 드문 경우이지만 자동 업데이트에서 웹 또는 함수 앱에 런타임 문제가 발생하여 이전 미들웨어 버전으로 일시적으로 롤백할 수 있습니다. 이 섹션에서는 특정 버전의 인증 미들웨어에 앱을 일시적으로 고정하는 방법을 설명합니다.

자동 및 수동 버전 업데이트

앱 설정을 구성하여 앱을 특정 버전의 플랫폼 미들웨어에 고정할 수 있습니다. 앱은 특정 버전에 명시적으로 고정하도록 선택하지 않는 한 항상 최신 버전에서 실행됩니다. 한 번에 몇 가지 버전이 지원됩니다. 더 이상 지원되지 않는 잘못된 버전에 고정하는 경우 앱은 대신 최신 버전을 사용합니다. 최신 버전을 항상 실행하려면 runtimeVersion를 ~1로 설정하십시오.

현재 런타임 버전 확인 및 업데이트

앱에서 사용하는 런타임 버전을 변경할 수 있습니다. 새 런타임 버전은 앱을 다시 시작한 후에 적용됩니다.

현재 런타임 버전 보기

Azure CLI를 사용하거나 앱의 기본 제공 버전 HTTP 엔드포인트 중 하나를 통해 플랫폼 인증 미들웨어의 현재 버전을 볼 수 있습니다.

Azure CLI에서

Azure CLI를 사용하여 az webapp auth show 명령을 사용하여 현재 미들웨어 버전을 봅니다.

az webapp auth show --name <my_app_name> \
--resource-group <my_resource_group>

이 코드에서 <my_app_name>을 함수 앱 이름으로 바꿉니다. <my_resource_group>을 앱의 리소스 그룹 이름으로 바꾸십시오.

CLI 출력에 runtimeVersion 필드가 표시됩니다. 이는 명확성을 위해 잘리는 다음 예제 출력과 유사합니다.

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}
버전 엔드포인트에서

앱에서 /.auth/version 엔드포인트를 눌러 앱이 실행 중인 현재 미들웨어 버전을 볼 수도 있습니다. 출력은 다음과 유사합니다.

{
"version": "1.3.2"
}

현재 런타임 버전 업데이트

Azure CLI를 사용하면 runtimeVersion 명령을 사용하여 앱에서 설정을 업데이트할 수 있습니다.

az webapp auth update --name <my_app_name> \
--resource-group <my_resource_group> \
--runtime-version <version>

<my_app_name>을 앱 이름으로 바꿉니다. <my_resource_group>을 앱의 리소스 그룹 이름으로 바꾸십시오. <version>을(를) 1.x 런타임의 유효한 버전으로 교체하거나 최신 버전에는 ~1을(를) 사용하십시오. Azure Functions에 고정할 버전을 확인하려면 Azure Functions 런타임 버전 개요를 참조하세요.

이전 코드 샘플에서 Open Cloud Shell을 선택하여 Azure Cloud Shell에서 이 명령을 실행할 수 있습니다. az login을 실행하여 로그인한 후 Azure CLI를 로컬로 사용하여 이 명령을 실행할 수도 있습니다.

다음 단계

자습서: 엔드투엔드 사용자 인증 및 권한 부여

  • Last updated on