Azure Data Studio - Azure 연결
Azure Data Studio는 기본값으로 Microsoft 인증 라이브러리(MSAL)를 사용하여 Microsoft Entra ID에서 액세스 토큰을 얻습니다. Microsoft Entra 인증에 적용되는 설정과 함께 일반적으로 나타나는 문제점과 해결 방법에 대해서도 설명합니다.
참고 항목
Microsoft Entra ID는 Azure AD(Azure Active Directory)의 새 이름이지만, 기존 환경의 중단을 방지하기 위해 UI 필드, 연결 공급자, 오류 코드 및 cmdlet과 같은 일부 하드 코딩된 요소에는 여전히 Azure AD가 남아 있습니다. 이 문서에서는 두 이름을 혼용할 수 있습니다.
Azure 인증 라이브러리
이 설정은 Azure Data Studio 1.41에서 1.45에서만 사용할 수 있습니다. Azure Data Studio 1.46 이후 버전에서는 더 이상 사용할 수 없습니다.
이 설정은 Microsoft Entra 계정을 추가하는 경우 Azure Data Studio에서 사용되는 인증 라이브러리를 제어합니다. Microsoft 인증 라이브러리(MSAL)는 OAuth 2.0 및 OpenID Connect(OIDC) 1.0의 표준을 준수하는 구현을 사용하여 인증 및 권한 부여 서비스를 제공합니다. Microsoft 인증 라이브러리(MSAL)에 대해 자세히 알아보세요. Azure Data Studio 1.46 이상 버전에서는 ADAL(Active Directory 인증 라이브러리)이 더 이상 사용되지 않으므로 MSAL이 사용 중인 유일한 라이브러리입니다.
Azure 인증 방법
Azure Data Studio는 다음 모드를 사용하여 Microsoft Entra MFA(다단계 인증)를 지원합니다.
- 코드 부여 인증 사용(기본값으로 사용)
- 디바이스 코드 인증 사용용
계정 > Azure > 인증: 코드 부여
Settings.json
"accounts.azure.auth.codeGrant": true
코드 부여 메서드를 선택하면 사용자에게 브라우저 기반 인증을 사용하여 인증하라는 프롬프트가 표시됩니다. 기본적으로 이 옵션은 사용하도록 설정됩니다.
계정 > Azure > 인증: 디바이스 코드
Settings.json
"accounts.azure.auth.deviceCode": true
디바이스 코드 메서드를 사용하면 사용자에게 코드와 URL이 제공되며 이를 입력하여 로그인할 수 있습니다.
두 옵션을 모두 선택하면 사용자는 Microsoft Entra 계정을 추가할 때 두 가지 인증 모드 중 하나를 선택하라는 메시지를 받습니다.
Azure 클라우드 구성
Azure Data Studio는 국가별 클라우드를 통한 Microsoft Entra 인증을 지원합니다. Azure 퍼블릭 클라우드는 기본값으로 사용되지만 사용자는 필요에 따라 다른 국가 클라우드를 사용할 수 있습니다.
Settings.json
"accounts.azure.cloud.enableChinaCloud": false,
"accounts.azure.cloud.enablePublicCloud": true,
"accounts.azure.cloud.enableUsGovCloud": false
사용자 지정 클라우드 엔드포인트도 정의할 수 있습니다. 사용자 지정 클라우드 엔드포인트 구성을 참조하세요.
Azure 리소스 구성
이러한 설정은 Azure 리소스 및 테넌트에 필터를 적용합니다.
- 리소스 구성 필터: 표시되어야 하는 리소스에 포함 필터를 적용합니다.
- 테넌트 구성 필터: 무시해야 할 테넌트에 제외 필터를 적용합니다.
Settings.json
"azure.resource.config.filter": [],
"azure.tenant.config.filter": [
"313b5f9e-9b92-414c-8d87-a317e42d0222"
]
Microsoft Entra 인증 설정의 프록시 설정
프록시 뒤에서 Azure Data Studio를 사용하는 경우 사용자는 Azure Data Studio가 외부 엔드포인트와 통신할 수 있도록 프록시 설정을 지정해야 합니다. Azure Data Studio에서 사용할 프록시 설정을 제공하는 방법은 두 가지가 있습니다.
- Azure Data Studio에서 프록시 구성 설정(설정 > Http: 프록시 설정)
- 프록시 구성에 대한 환경 변수 설정
Azure Data Studio 설정은 환경 변수보다 우선합니다.
Azure Data Studio 프록시 설정
Azure Data Studio에서 사용할 수 있는 설정은 다음과 같습니다.
Settings.json
"http.proxy": "https://userName@fqdn:yourPassword@yourProxyURL.com:8080",
"http.proxyStrictSSL": true,
"http.proxyAuthorization": "",
"http.proxySupport" : "override"
프록시에 지원되는 환경 변수
'HTTP_PROXY': 'http://userName@fqdn:yourPassword@yourProxyURL.com:8080''HTTPS_PROXY': 'https://userName@fqdn:yourPassword@yourProxyURL.com:8080'
허용 목록 URL
프록시 환경에서 사용자 응용 프로그램은 Azure Data Studio에서 사용되는 특정 도메인을 허용해야 할 수 있습니다. 통신을 허용해야 하거나 허용하려는 호스트 이름은 다음과 같습니다.
Azure 공용
https://management.azure.comhttps://login.microsoftonline.com/
Azure(미국 정부)
https://management.core.usgovcloudapi.net/https://login.microsoftonline.us/
21Vianet에서 운영하는 Azure
https://management.core.chinacloudapi.cn/https://login.partner.microsoftonline.cn/
허용할 URL은 경우에 따라 달라질 수 있습니다. 어떤 URL도 통과하지 못하도록 차단하지 않았는지 확인하려면 도움말 > 토글 개발자 도구로 가서 네트워크 탭을 선택하세요. 차단된 모든 URL이 나열되며, 계정을 성공적으로 추가하려면 해당 URL을 허용해야 할 수 있습니다.
사용자 지정 클라우드 엔드포인트 구성
Azure Data Studio 1.46에서는 비공개 클라우드에 대한 사용자 지정 엔드포인트를 추가하는 기능을 지원합니다.
사용자 지정 클라우드 엔드포인트 추가
Azure Data Studio에서 설정을 열고(Ctrl/Cmd + Shift + P) Azure: 사용자 지정 공급자 설정을 입력한 다음 settings.json에서 편집을 선택하면 settings.json 파일이 자동으로 열리고 azure.customProviderSettings이 추가됩니다.
엔드포인트가 작동하려면 다음 항목이 필요합니다.
hostclientIdscopessqlResourcemicrosoftResourcearmResourcegraphResourceazureStorageResource
한 공급자에 대한 JSON 항목의 예시는 가이드로 제공됩니다.
"azure.customProviderSettings": [
{
"name": "Azure Custom",
"settings": {
"metadata": {
"displayName": "Azure Custom Cloud",
"id": "azure_customCloud",
"endpoints": {
"host": "https://hostendpoint.com/",
"clientId": "test",
"microsoftResource": "https://microsoftresource.com/",
"graphResource": "https://graphresource.com/",
"msGraphResource": "https://msgraphresource.com/",
"armResource": "https://armresource.com/",
"sqlResource": "https://sqlresource.net/",
"azureKeyVaultResource": "https://azurekeyvault.net/",
"azureLogAnalyticsResource": "https://azure.loganalytic.io/",
"azureStorageResource": {
"endpoint": "",
"endpointSuffix": ".azurestorage.net/"
},
"azureKustoResource": "https://kusto.net/",
"powerBiResource": "https://powerbi.net/",
"scopes": "https://management.net/scopes",
"portalEndpoint": "https://portal.azure.com"
}
}
}
}
]
엔드포인트를 추가한 후 settings.json 파일을 저장합니다. Azure Data Studio에서 응용 프로그램을 다시 로드하라고 알려줍니다. 다시 로드되면 사용자 지정 엔드포인트가 로드되었다는 알림이 표시됩니다.
이 메시지가 나타나지 않을 경우, 엔드포인트에 대한 모든 항목이 존재하고 채워져 있는지 확인합니다.
사용자 지정 클라우드를 추가한 후 Azure 연결 계정 창을 열면 사용자 지정 클라우드 뷰렛이 나타납니다. 계정 추가를 선택하고 프롬프트가 나타나면 인증 모드를 선택합니다. 인증을 위해 호스트 엔드포인트로 이동하게 됩니다.
다양한 사용자 지정 클라우드 공급자
동일한 형식을 사용하여 추가 클라우드 공급자를 settings.json 파일에 추가할 수 있습니다.
"azure.customProviderSettings": [
{
"name": "Azure Custom",
"settings": {
"metadata": {
"displayName": "Azure Custom Cloud",
"id": "azure_customCloud",
"endpoints": {
"host": "https://hostendpoint.com/",
"clientId": "test",
"microsoftResource": "https://microsoftresource.com/",
"graphResource": "https://graphresource.com/",
"msGraphResource": "https://msgraphresource.com/",
"armResource": "https://armresource.com/",
"sqlResource": "https://sqlresource.net/",
"azureKeyVaultResource": "https://azurekeyvault.net/",
"azureLogAnalyticsResource": "https://azure.loganalytic.io/",
"azureStorageResource": {
"endpoint": "",
"endpointSuffix": ".azurestorage.net/"
},
"azureKustoResource": "https://kusto.net/",
"powerBiResource": "https://powerbi.net/",
"scopes": "https://management.net/scopes",
"portalEndpoint": "https://portal.azure.com"
}
}
}
},
{
"name": "Azure Custom 2",
"settings": {
"metadata": {
"displayName": "Azure Custom Cloud 2",
"id": "azure_customCloud2",
"endpoints": {
"host": "https://hostendpoint.com/",
"clientId": "test",
"microsoftResource": "https://microsoftresource.com/",
"graphResource": "https://graphresource.com/",
"msGraphResource": "https://msgraphresource.com/",
"armResource": "https://armresource.com/",
"sqlResource": "https://sqlresource.net/",
"azureKeyVaultResource": "https://azurekeyvault.net/",
"azureLogAnalyticsResource": "https://azure.loganalytic.io/",
"azureStorageResource": {
"endpoint": "",
"endpointSuffix": ".azurestorage.net/"
},
"azureKustoResource": "https://kusto.net/",
"powerBiResource": "https://powerbi.net/",
"scopes": "https://management.net/scopes",
"portalEndpoint": "https://portal.azure.com"
}
}
}
}
]
일반적인 인증 문제
Azure 계정을 추가하는 경우의 가능한 문제와 해답에 대해 설명합니다.
문제: localhost 페이지의 SSL 오류(ERR_SSL_PROTOCOL_ERROR)
사용자는 계정에 로그인할 때 SSL 오류가 나타날 수 있습니다. 이 흐름은 일반적으로 사용자에게 표준 Microsoft 인증 프롬프트를 통해 로그인하라는 메시지를 표시하여 localhost로 외부 웹 페이지를 엽니다. 이 페이지의 URL은 http://localhost:50055/signin?nonce=...과(와) 유사합니다.
일부 브라우저는 https에 대한 모든 http 링크를 자동으로 리디렉션하도록 설정되어 있을 수 있는데, 웹 페이지를 제공하는 로컬 서버가 https를 지원하지 않기 때문에 이 프로세스가 중단됩니다. 주소창의 링크가 https(으)로 시작하면 SSL 오류가 발생하여 페이지를 로드할 수 없습니다. 그런 경우 여기에 나열된 해결 방법을 통해 문제를 해결할 수 있습니다.
URL을 http로 변경
먼저 URL을 https://에서 http://로 수동으로 변경합니다. 브라우저가 이를 https로 다시 변경할 수 있는데, 이 경우 다른 옵션을 시도해야 합니다.
HSTS(HTTP Strict Transport Security) 사용 중지
Edge/Chrome 브라우저의 경우 localhost에 대해 HSTS를 사용 중지할 수 있습니다.
- Edge/Chrome을 열고 주소 표시줄에
edge://net-internals/#hsts(또는 Chrome의 경우chrome://net-internals/#hsts)을 입력합니다. - 페이지 하단으로 스크롤을 움직여
Delete domain security policies섹션에서localhost을(를) 입력하고Delete을(를) 누릅니다.
이 작업이 완료되면 로그인이 가능해지고 브라우저가 localhost 링크를 자동으로 https(으)로 리디렉션하지 않게 됩니다.
문제: 프록시 뒤에 계정을 추가할 수 없음
사용자 응용 프로그램이 프록시 뒤의 환경에서 실행되는 경우 사용자 인증이 완료되지 않을 수 있으며, 다음 단계를 사용하여 문제를 해결할 수 있습니다.
Azure Data Studio에서 환경 변수와 http.proxy 설정을 다시 확인합니다. 프록시에 사용자 인증이 필요한 경우 http.proxy URL에 사용자 이름/비밀번호를 제공하면 인증 문제를 해결할 수 있습니다. 그렇지 않으면 Azure Data Studio에서 로그인한 사용자 자격 증명을 읽을 수 없습니다. 또는 다른 사용자로 Azure Data Studio를 실행해 보면 프록시 인증 문제를 해결하는 데 도움이 될 수 있습니다. 그러나 후자의 경우는 일부 시나리오에서만 작동합니다.
허용할 URL은 사례마다 다를 수 있습니다. 어떤 URL도 통과하지 못하도록 차단하지 않았는지 확인하려면 도움말 > 토글 개발자 도구로 가서 네트워크 탭을 선택하세요. 여기서 계정을 성공적으로 추가하기 위해 허용해야 할 수 있는 차단된 URL을 볼 수 있습니다.
Http: Proxy Strict SSL을 선택 취소합니다. 프록시 인증서를 신뢰할 수 있는 CA 목록에서 확인할 수 없는 것 같습니다. Strict SSL을 사용 중지하면 프록시 인증서가 문제로 배제될 수 있습니다.
결론은 다음과 같습니다.
Azure Data Studio 프록시 확인은 플랫폼 간 응용 프로그램으로서 응용 프로그램 내의 설정이나 환경 변수를 통해 프록시를 가져옵니다. 목적은 다양한 운영 체제에 따라 상당히 달라질 수 있는 시스템 설정과의 상호 작용을 피하는 것입니다.
문제: Azure Core 확장이 사용 중지됨
Azure Core 확장 기능은 Azure Data Studio의 기본 제공 확장 기능입니다. 실수로 사용 중지되거나 제거되지 않았는지 확인하세요. 이 확장은 Microsoft Entra 계정을 인증하고 MFA를 사용하여 리소스에 연결하는 데 필요합니다.
문제: 시스템 CA 인증서가 만료되었습니다.
Azure Data Studio의 기본 동작에는 HTTPS 프로토콜을 사용하여 REST API 호출을 할 때 시스템의 루트 CA 인증서를 유효성 검사하는 작업이 포함됩니다. 유효성 검사는 기본값으로 사용되는 http:systemCertificates 설정을 통해 제어됩니다.
"http.systemCertificates": true
시스템의 루트 CA 인증서가 만료되면 Microsoft Entra ID에 대한 인증 요청이 실패하고 Azure 계정 로그에 오류가 기록됩니다.
error: certificate is expired
이 오류를 완화하려면 만료된 루트 CA 인증서를 제거하거나 시스템 인증서의 유효성을 검사하지 않도록 설정을 비활성화해야 합니다.
Azure 인증에 대한 로그 캡처
Azure Data Studio는 기본값으로 Microsoft Entra 계정 활동에 대한 오류 이벤트를 캡처합니다. 더욱 자세한 추적을 가능하게 하기 위해 사용자는 다음 설정을 수정할 수 있습니다.
Azure: 로깅 수준
이 설정은 Azure Data Studio에서 캡처할 수 있는 Azure Core의 정보에 대한 로깅 수준을 구성합니다. 인증 실패를 진단하는 데 유용할 수 있는 자세한 로그를 캡처하려면 세부 정보 표시 또는 모두로 변경하세요. 자세한 내용은 Azure Data Studio 로그 및 위치를 참조하여 로깅 정보를 캡처하는 방법을 알아보세요.
Settings.json
"azure.loggingLevel": "Verbose"
Azure: PII 로깅
사용자는 로컬 테스트 및 디버깅 목적으로 PII(개인 식별 정보) 로깅을 활성화할 수 있습니다. 이 설정을 사용하면 인증 프로세스를 보다 철저하게 로깅할 수 있지만 Microsoft Entra ID로 인증할 때 액세스 토큰이나 사용자 ID와 같은 중요한 정보가 포함될 수 있습니다. 이 로깅은 중요한 정보를 캡처하므로 다음 사항을 권장합니다.
- 특히 GitHub 문제에 로그를 추가할 때 다른 사람과 로그 공유 금지
- 필요한 정보를 수집한 후 설정을 사용 중지
- 설정이 사용 중지되면 로그 파일 삭제
Settings.json
"azure.piiLogging": true
Azure: 시스템 키체인 없음
이 설정은 macOS에서 키체인 접근 메시지가 반복적으로 표시되는 것을 방지하기 위해 시스템 키체인 통합을 사용 중지합니다. 사용자 자격 증명은 사용자의 홈 디렉터리에 있는 플랫 파일에도 저장됩니다.
Settings.json
"azure.noSystemKeychain": true
Microsoft Entra 계정 토큰 캐시 지우기
Azure Data Studio는 Microsoft Entra ID에 대한 토큰 요청이 제한되는 것을 방지하기 위해 액세스 토큰 캐시를 유지 관리합니다. Azure Data Studio의 토큰 캐시가 오래되었을 수 있으며, 이 경우 만료된 액세스 토큰을 응용 프로그램 캐시에서 정리해야 합니다.
연결된 Microsoft Entra 계정에 대한 액세스 토큰을 지우려면 명령 팔레트(Ctrl/CMD + Shift + P)에서 이 명령을 실행하세요.
Azure Accounts: Clear Azure Account Token Cache (accounts.clearTokenCache)
저장된 모든 Microsoft Entra 계정 지우기
Azure Data Studio에서 연결된 모든 Microsoft Entra 계정을 제거하려면 명령 팔레트(Ctrl/CMD + Shift + P)에서 이 명령을 실행하세요.
저장된 모든 계정 지우기(clearSavedAccounts)