이 문서에서는 Azure App Service에서 기본 제공 인증 및 권한 부여를 위해 OAuth 토큰을 관리하는 방법을 보여 줍니다.
앱 코드에서 토큰 검색
Azure App Service는 쉽게 액세스할 수 있도록 공급자별 토큰을 요청 헤더에 삽입합니다. 공급자별 토큰을 가져오려면 앱 에 토큰 저장소 를 사용하도록 설정해야 합니다.
모바일 앱 또는 브라우저 내 JavaScript와 같은 클라이언트 코드에서 HTTP GET 요청을 /.auth/me 보냅니다. 반환된 JSON에는 공급자별 토큰이 있습니다.
참고
액세스 토큰은 공급자 리소스에 액세스하기 위한 것이므로 클라이언트 암호를 사용하여 공급자를 구성하는 경우에만 존재합니다.
다음 표에서는 여러 App Service 기본 제공 공급자의 OAuth 토큰 헤더 이름을 나열합니다.
| 공급자 | 헤더 이름 |
|---|---|
| Microsoft Entra | X-MS-TOKEN-AAD-ID-TOKEN X-MS-TOKEN-AAD-ACCESS-TOKEN X-MS-TOKEN-AAD-EXPIRES-ON X-MS-TOKEN-AAD-REFRESH-TOKEN |
| 페이스북 | X-MS-TOKEN-FACEBOOK-ACCESS-TOKEN X-MS-TOKEN-FACEBOOK-EXPIRES-ON |
| 구글 | X-MS-TOKEN-GOOGLE-ID-TOKEN X-MS-TOKEN-GOOGLE-ACCESS-TOKEN X-MS-TOKEN-GOOGLE-EXPIRES-ON X-MS-TOKEN-GOOGLE-REFRESH-TOKEN |
| X | X-MS-TOKEN-TWITTER-ACCESS-TOKEN X-MS-TOKEN-TWITTER-ACCESS-TOKEN-SECRET |
참고
다른 언어 프레임워크는 이러한 헤더를 앱 코드에 소문자로 표시하거나 단어의 첫 글자를 대문자로 표시하는 것과 같이 다양한 형식을 사용할 수 있습니다.
인증 토큰 새로 고침
다음 정보는 공급자 토큰을 참조합니다. 세션 토큰의 경우 세션 토큰 만료 유예 기간 연장을 참조하세요.
공급자의 액세스 토큰이 만료되는 경우 해당 토큰을 다시 사용하려면 먼저 사용자를 다시 인증해야 합니다. 애플리케이션의 /.auth/refresh 엔드포인트에 대한 GET 호출을 수행하면 토큰 만료를 방지할 수 있습니다.
언제든지 액세스 토큰을 새로 고치려면 모든 언어로 호출 /.auth/refresh 합니다. 다음 코드 조각은 jQuery를 사용하여 JavaScript 클라이언트에서 액세스 토큰을 새로 고칩니다.
function refreshTokens() {
let refreshUrl = "/.auth/refresh";
$.ajax(refreshUrl) .done(function() {
console.log("Token refresh completed successfully.");
}) .fail(function() {
console.log("Token refresh failed. See application logs for details.");
});
}
호출되면 App Service에서는 인증된 사용자를 위한 토큰 저장소의 액세스 토큰을 자동으로 새로 고칩니다. 토큰에 대한 후속 요청은 새로 고친 토큰을 가져옵니다. 앱 코드의 토큰 검색에 나열된 헤더를 사용하여 새로 고침 토큰과 만료 시간을 볼 수 있습니다.
참고
사용자가 앱에 부여한 사용 권한을 취소하면, /.auth/me을 호출할 때 403 Forbidden 응답으로 실패할 수 있습니다. 오류를 진단하려면 세부 정보에 대한 애플리케이션 로그를 확인합니다.
새로 고침 토큰을 제공하도록 공급자 구성
토큰 새로 고침이 작동하려면 토큰 저장소에 공급자의 새로 고침 토큰이 포함되어야 합니다. 각 공급자는 새로 고침 토큰을 가져오는 방법을 설명합니다. 다음 표에서는 간략한 요약을 제공합니다.
| 공급자 | 토큰 새로 고침 |
|---|---|
| 마이크로소프트 | Microsoft Entra 공급자를 구성하여 새로 고침 토큰을 공급하는 절차를 따르십시오. |
| 페이스북 | 새로 고침 토큰을 제공하지 않습니다. 수명이 긴 토큰은 60일 후에 만료됩니다. 자세한 내용은 Long-Lived 액세스 토큰을 참조하세요. |
| 구글 | /.auth/login/google API 호출에 access_type=offline 쿼리 문자열 매개변수를 추가하십시오. 자세한 내용은 Google 새로 고침 토큰을 참조하세요. |
| X | 액세스 토큰이 만료되지 않습니다. 자세한 내용은 OAuth FAQ를 참조하세요. |
새로 고침 토큰을 제공하도록 Microsoft Entra 공급자 구성
- Azure Portal에서 API 플레이그라운드(미리 보기)로 이동하여 필요한 경우 새 요청을 선택합니다.
- API 버전 필드를 포함한 ARM 상대 경로 입력에서 다음 문자열을 입력하고 자리 표시자를 구독 ID, 리소스 그룹 이름 및 앱 이름으로 바꿉니다.
subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Web/sites/<app-name>/config/authsettingsV2?api-version=2024-11-01 - 실행을 선택합니다.
- 왼쪽 위에서 선택하고
PUT요청 본문 탭을 선택합니다. GET응답 본문 필드의 응답 내용을 복사하여 요청 본문 탭에 붙여넣습니다.- 코드에서 섹션을
"identityProviders":>>"azureActiveDirectory":"login":찾고 다음 줄을 추가합니다."loginParameters": ["scope=openid profile email offline_access"] - 실행을 선택합니다. 응답 본문 필드에 변경 내용이 표시됩니다.
Offline_access 새로 고침 토큰을 제공하는 범위입니다. App Service는 이미 기본적으로 다른 범위를 요청합니다. 자세한 내용은 OpenID Connect 범위 및 Web Apps - 인증 설정 V2 업데이트를 참조하세요.
세션 토큰 만료 유예 기간 연장
인증된 세션은 8시간 후에 만료되며 72시간의 기본 유예 기간은 다음과 같습니다. 이 유예 기간 내에 사용자를 다시 인증하지 않고 App Service를 사용하여 세션 토큰을 새로 고칠 수 있습니다. 세션 토큰이 유효하지 않은 경우 호출 /.auth/refresh 할 수 있으며 토큰 만료를 직접 추적할 필요가 없습니다.
72시간 유예 기간이 경과하면 사용자는 다시 로그인하여 유효한 세션 토큰을 가져와야 합니다. 72시간보다 긴 만료 기간이 필요한 경우 연장할 수 있지만, 인증 토큰이 유출되거나 도난당한 경우 장기간 만료를 연장하면 보안에 상당한 영향을 미칠 수 있습니다. 설정을 기본값인 72시간으로 두거나 확장 기간을 가능한 가장 작은 값으로 설정하는 것이 가장 좋습니다.
기본 만료 기간을 확장하려면 Azure Cloud Shell에서 다음 Azure CLI 명령을 실행합니다.
az webapp auth update --resource-group <group_name> --name <app_name> --token-refresh-extension-hours <hours>
참고
유예 기간은 ID 공급자의 액세스 토큰이 아니라 App Service 인증 세션에만 적용됩니다. 만료된 공급자 토큰에 대한 유예 기간이 없습니다.