인증 처리

아티클
01/19/2024

인증 종류

확장은 하나 이상의 종류의 인증을 지원할 수 있습니다. 각 인증 종류는 다른 유형의 자격 증명입니다. 파워 쿼리에서 최종 사용자에게 표시되는 인증 UI는 확장에서 지원하는 자격 증명 유형에 의해 구동됩니다.

지원되는 인증 유형 목록은 확장의 데이터 원본 종류 정의의 일부로 정의됩니다. 각 인증 값은 특정 필드가 있는 레코드입니다. 다음 표에서는 각 종류의 예상 필드를 나열합니다. 달리 표시되지 않는 한 모든 필드가 필요합니다.

인증 종류	필드	설명
익명		익명(이라고도 함 `Implicit`) 인증 종류에는 필드가 없습니다.
OAuth	StartLogin	OAuth 흐름을 시작하기 위한 URL 및 상태 정보를 제공하는 함수입니다. OAuth 흐름 구현 섹션으로 이동합니다.
	FinishLogin	OAuth 흐름과 관련된 access_token 및 기타 속성을 추출하는 함수입니다.
	새로 고침	(선택 사항) 새로 고침 토큰에서 새 액세스 토큰을 검색하는 함수입니다.
	로그아웃	(선택 사항) 사용자의 현재 액세스 토큰을 무효화하는 함수입니다.
	Label	(선택 사항) 이 AuthenticationKind의 기본 레이블을 재정의할 수 있는 텍스트 값입니다.
Aad	AuthorizationUri	`text` Microsoft Entra ID 권한 부여 엔드포인트(예: `"https://login.microsoftonline.com/common/oauth2/authorize"`)를 반환하는 값 또는 단항 함수입니다. Microsoft Entra ID 인증 섹션으로 이동합니다.
	리소스	`text` 서비스에 대한 Microsoft Entra ID 리소스 값을 반환하는 값 또는 단항 함수입니다.
	범위	(선택 사항)`text` 인증 흐름의 일부로 요청할 범위 목록을 반환하는 값 또는 단항 함수입니다. 여러 범위 값을 공백으로 구분해야 합니다. 범위 값은 애플리케이션 ID URI(예: `Data.Read`)가 없는 범위 이름이어야 합니다. 제공되지 않으면 범위가 `user_impersonation` 요청됩니다.
UsernamePassword	UsernameLabel	(선택 사항) 자격 증명 UI의 사용자 이름 텍스트 상자에 대한 기본 레이블을 바꿀 텍스트 값입니다.
	PasswordLabel	(선택 사항) 자격 증명 UI의 암호 텍스트 상자에 대한 기본 레이블을 바꿀 텍스트 값입니다.
	Label	(선택 사항) 이 AuthenticationKind의 기본 레이블을 재정의할 수 있는 텍스트 값입니다.
Windows	UsernameLabel	(선택 사항) 자격 증명 UI의 사용자 이름 텍스트 상자에 대한 기본 레이블을 바꿀 텍스트 값입니다.
	PasswordLabel	(선택 사항) 자격 증명 UI의 암호 텍스트 상자에 대한 기본 레이블을 바꿀 텍스트 값입니다.
	Label	(선택 사항) 이 AuthenticationKind의 기본 레이블을 재정의할 수 있는 텍스트 값입니다.
키	KeyLabel	(선택 사항) 자격 증명 UI의 API 키 텍스트 상자에 대한 기본 레이블을 바꿀 텍스트 값입니다.
	Label	(선택 사항) 이 AuthenticationKind의 기본 레이블을 재정의할 수 있는 텍스트 값입니다.

다음 샘플에서는 OAuth, 키, Windows, 기본(사용자 이름 및 암호) 및 익명 자격 증명을 지원하는 커넥터에 대한 인증 레코드를 보여 줍니다.

예제:

Authentication = [
    OAuth = [
        StartLogin = StartLogin,
        FinishLogin = FinishLogin,
        Refresh = Refresh,
        Logout = Logout
    ],
    Key = [],
    UsernamePassword = [],
    Windows = [],
    Anonymous = []
]

현재 자격 증명에 액세스

함수를 사용하여 Extension.CurrentCredential 현재 자격 증명을 검색할 수 있습니다.

확장성을 사용하도록 설정된 M 데이터 원본 함수는 확장의 자격 증명 범위를 자동으로 상속합니다. 대부분의 경우 현재 자격 증명에 명시적으로 액세스할 필요는 없지만 다음과 같은 예외가 있습니다.

사용자 지정 헤더 또는 쿼리 문자열 매개 변수(예: API 키 인증 형식을 사용하는 경우)에서 자격 증명을 전달합니다.
ODBC 또는 ADO.NET 확장에 대한 연결 문자열 속성 설정
OAuth 토큰에서 사용자 지정 속성 확인
OAuth v1 흐름의 일부로 자격 증명 사용

이 함수는 Extension.CurrentCredential 레코드 개체를 반환합니다. 포함된 필드는 인증 유형별로 다릅니다. 다음 표에는 세부 정보가 포함되어 있습니다.

필드	설명	사용 대상
AuthenticationKind	이 자격 증명에 할당된 인증 종류의 이름(UsernamePassword, OAuth 등)을 포함합니다.	모두
사용자 이름	사용자 이름 값	UsernamePassword, Windows
암호	암호 값입니다. 일반적으로 UsernamePassword와 함께 사용되지만 키에 대해서도 설정됩니다.	Key, UsernamePassword, Windows
access_token	OAuth 액세스 토큰 값입니다.	OAuth
속성	지정된 자격 증명에 대한 다른 사용자 지정 속성을 포함하는 레코드입니다. 일반적으로 인증 흐름 중에 access_token 반환된 다른 속성(예: refresh_token)을 저장하기 위해 OAuth와 함께 사용됩니다.	OAuth
키	API 키 값입니다. 키 값은 암호 필드에서도 사용할 수 있습니다. 기본적으로 매시업 엔진은 이 값이 기본 인증 암호(사용자 이름 없음)인 것처럼 권한 부여 헤더에 이 키를 삽입합니다. 이 유형의 동작이 원하는 동작이 아닌 경우 옵션 레코드에서 ManualCredentials = true 옵션을 지정해야 합니다.	키
EncryptConnection	데이터 원본에 대한 암호화된 연결이 필요한지 여부를 결정하는 논리적 값입니다. 이 값은 모든 인증 종류에 사용할 수 있지만 데이터 원본 정의에 Encrypt커넥트ion이 지정된 경우에만 설정됩니다.	모두

다음 코드 샘플에서는 API 키에 대한 현재 자격 증명에 액세스하고 이를 사용하여 사용자 지정 헤더(x-APIKey)를 채웁니다.

예제:

MyConnector.Raw = (_url as text) as binary =>
let
    apiKey = Extension.CurrentCredential()[Key],
    headers = [

        #"x-APIKey" = apiKey,
        Accept = "application/vnd.api+json",
        #"Content-Type" = "application/json"
    ],
    request = Web.Contents(_url, [ Headers = headers, ManualCredentials = true ])
in
    request

OAuth 흐름 구현

OAuth 인증 유형을 사용하면 확장에서 해당 서비스에 대한 사용자 지정 논리를 구현할 수 있습니다. 이를 위해 확장은 (OAuth 흐름을 시작하기 위해 StartLogin 권한 부여 URI를 반환) 및 FinishLogin (액세스 토큰에 대한 권한 부여 코드 교환) 함수를 제공합니다. 확장은 필요에 따라 구현(새 액세스 토큰에 대한 새로 고침 토큰 교환) 및 Logout (현재 새로 고침 및 액세스 토큰 만료) 함수도 구현 Refresh 할 수 있습니다.

참고 항목

파워 쿼리 확장은 클라이언트 컴퓨터에서 실행되는 애플리케이션에서 평가됩니다. 데이터 커넥트 사용자는 확장을 검사하거나 네트워크 트래픽을 검사하여 비밀을 알아볼 수 있으므로 OAuth 흐름에서 기밀 비밀을 사용하면 안 됩니다. 공유 비밀에 의존하지 않는 흐름 제공에 대한 자세한 내용은 OAuth 공용 클라이언트 RFC (PKCE라고도 함)의 코드 교환용 증명 키로 이동합니다. 이 흐름의 샘플 구현은 GitHub 사이트에서 찾을 수 있습니다.

OAuth 함수 서명에는 최소 개수의 매개 변수가 포함된 원래 서명과 더 많은 매개 변수를 허용하는 고급 서명의 두 집합이 있습니다. 대부분의 OAuth 흐름은 원래 서명을 사용하여 구현할 수 있습니다. 구현에서 서명 형식을 혼합하고 일치시킬 수도 있습니다. 함수 호출은 매개 변수 수 및 해당 형식에 따라 일치합니다. 매개 변수 이름은 고려되지 않습니다.

자세한 내용은 GitHub 샘플로 이동합니다.

원래 OAuth 서명

StartLogin = (dataSourcePath, state, display) => ...;

FinishLogin = (context, callbackUri, state) => ...;

Refresh = (dataSourcePath, refreshToken) =>  ...;

Logout = (accessToken) => ...;

고급 OAuth 서명

고급 서명에 대한 참고 사항:

모든 서명은 나중에 사용하도록 예약된 레코드 값을 허용 clientApplication 합니다.
모든 서명은 ( dataSourcePath 대부분의 샘플에서라고도 함 resourceUrl ) 수락합니다.
함수는 Refresh 매개 변수를 oldCredential 수락합니다. 이 매개 변수는 함수(또는 이전 호출)에서 반환한 FinishLogin 이전 record 매개 변수입니다Refresh.

StartLogin = (clientApplication, dataSourcePath, state, display) => ...;

FinishLogin = (clientApplication, dataSourcePath, context, callbackUri, state) => ...;

Refresh = (clientApplication, dataSourcePath, oldCredential) =>  ...;

Logout = (clientApplication, dataSourcePath, accessToken) => ...;

Microsoft Entra ID 인증

Aad 인증 종류는 Microsoft Entra ID용 OAuth의 특수 버전입니다. 조직 계정 인증을 지원하는 기본 제공 파워 쿼리 커넥터와 동일한 Microsoft Entra ID 클라이언트를 사용합니다. 자세한 내용은 사용자 지정 커넥터 빠른 시작 가이드에 대한 Microsoft Entra 구성에서 찾을 수 있습니다.

참고 항목

Microsoft Entra ID에 대해 고유한 OAuth 흐름을 구현하는 경우 테넌트에 조건부 액세스를 사용하도록 설정한 사용자는 Power BI 서비스 사용하여 새로 고침할 때 문제가 발생할 수 있습니다. 이는 게이트웨이 기반 새로 고침에 영향을 주지 않지만 Power BI 서비스 새로 고침을 지원하는 인증된 커넥터에 영향을 줍니다. 사용자는 Power BI 서비스 통해 웹 기반 자격 증명을 구성할 때 공용 클라이언트 애플리케이션을 사용하여 커넥터에서 발생하는 문제가 발생할 수 있습니다. 이 흐름에서 생성된 액세스 토큰은 궁극적으로 원래 인증하는 데 사용한 컴퓨터(즉, 회사의 네트워크에서 데이터 원본 자격 증명을 구성하는 사용자의 컴퓨터)와 다른 컴퓨터(즉, 회사의 네트워크가 아닌 Azure 데이터 센터의 Power BI 서비스)에서 사용됩니다. 기본 제공 Aad 형식은 Power BI 서비스 자격 증명을 구성할 때 다른 Microsoft Entra ID 클라이언트를 사용하여 이 문제를 해결합니다. 이 옵션은 인증 종류를 사용하는 OAuth 커넥터에서 사용할 수 없습니다.

대부분의 커넥터는 해당 및 Resource 필드에 대한 AuthorizationUri 값을 제공해야 합니다. 두 필드 모두 값일 수도 있고 text , 값을 반환하는 단일 인수 함수일 수도 있습니다 text value.

AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize"

AuthorizationUri = (dataSourcePath) => FunctionThatDeterminesAadEndpointFromDataSourcePath(dataSourcePath)

Resource = "77256ee0-fe79-11ea-adc1-0242ac120002"   // Microsoft Entra ID resource value for your service - Guid or URL

Resource = (dataSourcePath) => FunctionThatDeterminesResourceFromDataSourcePath(dataSourcePath)

를 사용하는 커넥트orsURI 기반 식별자는 값을 제공할 Resource 필요가 없습니다. 기본적으로 값은 커넥터의 Uri 매개 변수의 루트 경로와 같습니다. 데이터 원본의 Microsoft Entra ID 리소스가 do기본 값과 다른 경우(예: GUID 사용) Resource 값을 제공해야 합니다.

Aad 인증 종류 샘플

다음 경우 데이터 원본은 공통 테넌트(Azure B2B 지원 없음)를 사용하여 글로벌 클라우드 Microsoft Entra ID를 지원합니다. .default 범위를 요청하면 파워 쿼리 클라이언트 애플리케이션 ID에 대해 이전에 권한이 부여된 모든 범위의 토큰이 반환됩니다.

Authentication = [
    Aad = [
        AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize",
        Resource = "77256ee0-fe79-11ea-adc1-0242ac120002", // Entra Application ID URI or app guid
        Scope = ".default"
    ]
]

다음 경우 데이터 원본은 OIDC(OpenID 커넥트) 또는 유사한 프로토콜을 기반으로 테넌트 검색을 지원합니다. 이 기능을 사용하면 커넥터가 데이터 원본 경로에서 하나 이상의 매개 변수를 기반으로 사용할 올바른 Microsoft Entra ID 엔드포인트를 결정할 수 있습니다. 이 동적 검색 방법을 사용하면 커넥터가 Azure B2B를 지원할 수 있습니다.


// Implement this function to retrieve or calculate the service URL based on the data source path parameters
GetServiceRootFromDataSourcePath = (dataSourcePath) as text => ...;

GetAuthorizationUrlFromWwwAuthenticate = (url as text) as text =>
    let
        // Sending an unauthenticated request to the service returns
        // a 302 status with WWW-Authenticate header in the response. The value will
        // contain the correct authorization_uri.
        // 
        // Example:
        // Bearer authorization_uri="https://login.microsoftonline.com/{tenant_guid}/oauth2/authorize"
        responseCodes = {302, 401},
        endpointResponse = Web.Contents(url, [
            ManualCredentials = true,
            ManualStatusHandling = responseCodes
        ])
    in
        if (List.Contains(responseCodes, Value.Metadata(endpointResponse)[Response.Status]?)) then
            let
                headers = Record.FieldOrDefault(Value.Metadata(endpointResponse), "Headers", []),
                wwwAuthenticate = Record.FieldOrDefault(headers, "WWW-Authenticate", ""),
                split = Text.Split(Text.Trim(wwwAuthenticate), " "),
                authorizationUri = List.First(List.Select(split, each Text.Contains(_, "authorization_uri=")), null)
            in
                if (authorizationUri <> null) then
                    // Trim and replace the double quotes inserted before the url
                    Text.Replace(Text.Trim(Text.Trim(Text.AfterDelimiter(authorizationUri, "=")), ","), """", "")
                else
                    error Error.Record("DataSource.Error", "Unexpected WWW-Authenticate header format or value during authentication.", [
                        #"WWW-Authenticate" = wwwAuthenticate
                    ])
        else
            error Error.Unexpected("Unexpected response from server during authentication.");

<... snip ...>

Authentication = [
    Aad = [
        AuthorizationUri = (dataSourcePath) =>
            GetAuthorizationUrlFromWwwAuthenticate(
                GetServiceRootFromDataSourcePath(dataSourcePath)
            ),
        Resource = "https://myAadResourceValue.com", // Microsoft Entra ID resource value for your service - Guid or URL
        Scope = ".default"
    ]
]

다른 유형의 인증

Kerberos 기반 Single Sign-On과 같이 이 문서에서 다루지 않는 다른 유형의 인증에 대한 자세한 내용은 추가 커넥터 기능 문서를 참조하세요.