Power BI Connector for Azure Data Lake Storage

Build 22.0.8479

DSN の作成

このセクションでは、DSN 設定の編集方法と、Azure Data Lake Storage API へ認証および接続について説明します。

DSN 設定の編集

Microsoft ODBC データソースアドミニストレーターを使ってDSN 設定を編集できます。DSN はインストールプロセス中に作成されることに注意してください（コネクタのインストール 参照）。

DSN 設定を編集するには、次の手順を実行してください。

  1. ［スタート］->［検索］ を選択し、［検索］ボックスに［ODBC データソース］ と入力します。
  2. Power BI Desktop インストールのビット数（32-bit または64-bit）に対応するODBC アドミニストレーターのバージョンを選択してください。
  3. ［システムDSN］ タブをクリックします。
  4. システムデータソースを選択して［構成］をクリックします。
  5. ［接続］タブの情報を編集して［OK］をクリックします。

Azure DataLakeStorage Gen 1 への接続

To connect to a Gen 1 DataLakeStorage account, you should first set the following properties:

  • Schema：ADLSGen1 に設定。
  • Account：アカウント名に設定。
  • AzureTenant：テナントId に設定。取得方法について詳しくは、プロパティを参照してください。
  • Directory：（オプション）複製されたファイルを格納するために使用されるパスに設定。指定しない場合は、ルートディレクトリが使用されます。

Azure DataLakeStorage Gen 1 への認証

Gen 1 は、次の認証メソッドをサポートしています。Azure Active Directory OAuth (AzureAD) and Managed Service Identity (AzureMSI).

Azure AD

Azure AD is a connection type that leverages OAuth to authenticate. OAuth requires the authenticating user to interact with Azure Data Lake Storage using an internet browser. The 本製品 facilitates this in several ways as described below. Set your AuthScheme to AzureAD. The rest of the AzureAD flows assume that you have done so.

Desktop Applications

CData provides an embedded OAuth application that simplifies OAuth desktop Authentication. Alternatively, you can create a custom OAuth application. See カスタムAzureAD アプリの作成 for information about creating custom applications and reasons for doing so.

For authentication, the only difference between the two methods is that you must set two additional connection properties when using custom OAuth applications.

After setting the following connection properties, you are ready to connect:

  • OAuthClientId: (custom applications only) Set this to the client Id in your application settings.
  • OAuthClientSecret: (custom applications only) Set this to the client secret in your application settings.
  • CallbackURL: Set this to the Redirect URL in your application settings.

When you connect the 本製品 opens the OAuth endpoint in your default browser. Log in and grant permissions to the application.

Headless Machines

To configure the driver, use OAuth with a user account on a headless machine. You need to authenticate on another device that has an internet browser.

  1. Choose one of these two options:

    • Option 1: Obtain the OAuthVerifier value as described in "Obtain and Exchange a Verifier Code" below.
    • Option 2: Install the 本製品 on another machine and transfer the OAuth authentication values after you authenticate through the usual browser-based flow.

  2. Then configure the 本製品 to automatically refresh the access token from the headless machine.

Option 1: Obtain and Exchange a Verifier Code

To obtain a verifier code, you must authenticate at the OAuth authorization URL.

Follow the steps below to authenticate from the machine with an internet browser and obtain the OAuthVerifier connection property.

  1. Choose one of these options:

    • If you are using the Embedded OAuth Application click Azure Data Lake Storage OAuth endpoint to open the endpoint in your browser.
    • If you are using a custom OAuth application, create the Authorization URL by setting the following properties:
      • InitiateOAuth: Set to OFF.
      • OAuthClientId: Set to the client Id assigned when you registered your application.
      • OAuthClientSecret: Set to the client secret assigned when you registered your application.
      Then call the GetOAuthAuthorizationURL stored procedure with the appropriate CallbackURL. Open the URL returned by the stored procedure in a browser.

  2. Log in and grant permissions to the 本製品. You are then redirected to the callback URL, which contains the verifier code.
  3. Save the value of the verifier code. Later you will set this in the OAuthVerifier connection property.
Next, you need to exchange the OAuth verifier code for OAuth refresh and access tokens. Set the following properties:

On the headless machine, set the following connection properties to obtain the OAuth authentication values:

  • InitiateOAuth: Set this to REFRESH.
  • OAuthVerifier: Set this to the verifier code.
  • OAuthClientId: (custom applications only) Set this to the client Id in your custom OAuth application settings.
  • OAuthClientSecret: (custom applications only) Set this to the client secret in the custom OAuth application settings.
  • OAuthSettingsLocation: Set this to the path to the file where the driver saves the OAuth token values that persist across connections.

After the OAuth settings file is generated, you need to re-set the following properties to connect:

  • InitiateOAuth: Set this to REFRESH.
  • OAuthClientId: (custom applications only) Set this to the client Id assigned when you registered your application.
  • OAuthClientSecret: (custom applications only) Set this to the client secret assigned when you registered your application.
  • OAuthSettingsLocation: Set this to the file containing the encrypted OAuth authentication values. Make sure this file grants read and write permissions to the 本製品 to enable the automatic refreshing of the access token.

Option 2: Transfer OAuth Settings

Prior to connecting on a headless machine, you need to create and install a connection with the driver on a device that supports an internet browser. Set the connection properties as described in "Desktop Applications" above.

After completing the instructions in "Desktop Applications", the resulting authentication values are encrypted and written to the path specified by OAuthSettingsLocation. The default filename is OAuthSettings.txt.

Once you have successfully tested the connection, copy the OAuth settings file to your headless machine.

On the headless machine, set the following connection properties to connect to data:

  • InitiateOAuth: Set this to REFRESH.
  • OAuthClientId: (custom applications only) Set this to the client Id assigned when you registered your application.
  • OAuthClientSecret: (custom applications only) Set this to the client secret assigned when you registered your application.
  • OAuthSettingsLocation: Set this to the path to your OAuth settings file. Make sure this file gives read and write permissions to the 本製品 to enable the automatic refreshing of the access token.

Admin Consent

Admin consent refers to when the Admin for an Azure Active Directory tenant grants permissions to an application which requires an admin to consent to the use case. The embedded app within the CData Power BI Connector for Azure Data Lake Storage, contains no permissions that require admin consent. Therefore, this information applies only to custom applications.

Admin Consent Permissions

When creating a new OAuth app in the Azure Portal, you must specify which permissions the app will require. Some permissions may be marked stating "Admin Consent Required". For example, all Groups permissions require Admin Consent. If your app requires admin consent, there are a couple of ways this can be done.

The easiest way to grant admin consent is to just have an admin log into portal.azure.com and navigate to the app you have created in App Registrations. Under API Permissions, there will be a button for Grant Consent. You can consent here for your app to have permissions on the tenant it was created under.

If your organization has multiple tenants or the app needs to be granted permissions for other tenants outside your organization, the GetAdminConsentURL may be used to generate the Admin Authorization url. Unlike the GetOAuthAuthorizationURL, there will be no important information returned from this endpoint. If the grants access, it will simply return a boolean indicating that permissions were granted.

Once an admin grants consent, authentication may be performed as normal.

Client Credentials

Client credentials refers to a flow in OAuth where there is no direct user authentication taking place. Instead, credentials are created for just the app itself. All tasks taken by the app are done without a default user context. This makes the authentication flow a bit different from standard.

Client OAuth Flow

All permissions related to the client oauth flow require admin consent. This means the app embedded with the CData Power BI Connector for Azure Data Lake Storage cannot be used in the client oauth flow. You must create your own OAuth app in order to use client credentials. See カスタムAzureAD アプリの作成 for more details.

In your App Registration in portal.azure.com, navigate to API Permissions and select the Microsoft Graph permissions. There are two distinct sets of permissions - Delegated and Application permissions. The permissions used during client credential authentication are under Application Permissions. Select the applicable permissions you require for your integration.

You are ready to connect after setting one of the below connection properties groups depending on the authentication type.

  1. Client Secret
    • InitiateOAuth: Set this to GETANDREFRESH. You can cuse InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
    • AzureTenant: Set this to the tenant you wish to connet to.
    • OAuthGrantType: Set this to CLIENT.
    • OAuthClientId: Set this to the Client Id in your app settings.
    • OAuthClientSecret: Set this to the Client Secret in your app settings.
  2. Certificate
    • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
    • AzureTenant: Set this to the tenant you wish to connect to.
    • OAuthGrantType: Set this to CLIENT.
    • OAuthClientId: Set this to the Client Id in your app settings.
    • OAuthJWTCert: Set this to the JWT Certificate store.
    • OAuthJWTCertType: Set this to the type of the certificate store specified by OAuthJWTCert.

Authentication with client credentials will take place automatically like any other connection, except there will be no window opened prompting the user. Because there is no user context, there is no need for a browser popup. Connections will take place and be handled internally.

Azure サービスプリンシパル

Azure サービスプリンシパルは、OAuth を経由する接続タイプです。AuthScheme をAzureServicePrincipal に設定します。 Azure サービスプリンシパルとしての認証は、OAuth クライアントクレデンシャルフローを介して処理され、直接のユーザー認証は行われません。代わりに、クレデンシャルはアプリ自体のためだけに作成されます。アプリで実行されるすべてのタスクは、デフォルトユーザーコンテキストなしで実行されます。 リソースへのアプリケーションのアクセスは、割り当てられたロールの権限によって制御されます。

Note： ロールを割り当てる前に、カスタムアプリケーションを作成する必要があります。詳しくは、カスタムAzureAD アプリの作成 を参照してください。

Azure サービスプリンシパルを使用して認証する場合、Azure AD テナントにアプリケーションを登録する必要があります。以下の手順に従って、ロールベースのアクセス制御で使用できる新しいサービスプリンシパルを作成します。

アプリケーションへのロールの割り当て

サブスクリプションのリソースにアクセスするには、アプリケーションにロールを割り当てる必要があります。

  1. 検索バーでサブスクリプションサービスを検索・選択して、［サブスクリプション］ページを開きます。
  2. アプリケーションを割り当てる特定のサブスクリプションを選択します。
  3. ［アクセス制御 (IAM)］を開き、［追加］->［ロール割り当ての追加］を選択して［ロール割り当ての追加］ページを開きます。
  4. 作成したAzure AD アプリに割り当てるロールとして、［所有者］を選択します。

認証の完了

設定されたアプリ認証（クライアントシークレットまたは証明書）に応じて、以下のいずれかの接続プロパティグループを設定すると、接続できるようになります。

両メソッド共通

クライアントシークレットか証明書認証を選択する前に、まず以下の手順に従って設定を行います。その後、該当するセクションの設定に進んでください。

  1. AuthScheme：アプリ設定のAzureServicePrincipal に設定。
  2. InitiateOAuth：GETANDREFRESH に設定。InitiateOAuth を使えば、繰り返しOAuth の交換を行ったり、手動でOAuthAccessToken を設定する必要はなくなります。
  3. AzureTenant：接続するテナントに設定。
  4. OAuthClientId：アプリ設定のクライアントId に設定。
クライアントシークレットを使用した認証

続いて、以下を設定します。

  1. OAuthClientId：アプリ設定のクライアントId に設定。
  2. OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。

証明書を使用した認証

続いて、以下を設定します。

  1. OAuthJWTCert：JWT 証明書ストアを設定。
  2. OAuthJWTCertType：OAuthJWTCert で指定された証明書ストアの種類に設定。

MSI

Azure VM 上でAzure Data Lake Storage を実行している場合は、Managed Service Identity（MSI）の資格情報を利用して接続が可能です。

  • AuthScheme：AzureMSI に設定。

MSI 資格情報が認証用に自動的に取得されます。

Azure DataLakeStorage Gen 2 への接続

To connect to a Gen 2 DataLakeStorage account, you should first set the following properties:

  • Schema：ADLSGen2 に設定。
  • Account：ストレージアカウント名に設定。
  • FileSystem：このアカウントに使用されるファイルシステム名に設定。例えば、Azure Blob コンテナの名前。
  • Directory：（オプション）複製されたファイルを格納するために使用されるパスに設定。指定しない場合は、ルートディレクトリが使用されます。

Azure DataLakeStorage Gen 2 への認証

Gen 2 supports the following authentication methods: using an AccessKey, using a Shared Access Signature, Azure Active Directory OAuth (AzureAD), Managed Service Identity (AzureMSI).

Access Key を使用した認証

To connect using a Shared Access Signature set the AccessKey property and the AuthScheme to AccessKey.

You can obtain an access key for the ADLS Gen2 storage account using the Azure portal:

  1. Go to your ADLS Gen2 Storage Account in the Azure portal.
  2. 設定で［アクセスキー］を選択します。
  3. Copy the value for one of the available access keys to the AccessKey connection property.

共有アクセス署名（SAS）

To connect using a Shared Access Signature set the SharedAccessSignature property to a valid signature of a resource to connect to and the AuthScheme to SAS. The SharedAccessSignature may be generated with a tool such as Azure Storage Explorer.

Azure AD

Azure AD is a connection type that leverages OAuth to authenticate. OAuth requires the authenticating user to interact with Azure Data Lake Storage using an internet browser. The 本製品 facilitates this in several ways as described below. Set your AuthScheme to AzureAD. The rest of the AzureAD flows assume that you have done so.

Desktop Applications

CData provides an embedded OAuth application that simplifies OAuth desktop Authentication. Alternatively, you can create a custom OAuth application. See カスタムAzureAD アプリの作成 for information about creating custom applications and reasons for doing so.

For authentication, the only difference between the two methods is that you must set two additional connection properties when using custom OAuth applications.

After setting the following connection properties, you are ready to connect:

  • OAuthClientId: (custom applications only) Set this to the client Id in your application settings.
  • OAuthClientSecret: (custom applications only) Set this to the client secret in your application settings.
  • CallbackURL: Set this to the Redirect URL in your application settings.

When you connect the 本製品 opens the OAuth endpoint in your default browser. Log in and grant permissions to the application.

Headless Machines

To configure the driver, use OAuth with a user account on a headless machine. You need to authenticate on another device that has an internet browser.

  1. Choose one of these two options:

    • Option 1: Obtain the OAuthVerifier value as described in "Obtain and Exchange a Verifier Code" below.
    • Option 2: Install the 本製品 on another machine and transfer the OAuth authentication values after you authenticate through the usual browser-based flow.

  2. Then configure the 本製品 to automatically refresh the access token from the headless machine.

Option 1: Obtain and Exchange a Verifier Code

To obtain a verifier code, you must authenticate at the OAuth authorization URL.

Follow the steps below to authenticate from the machine with an internet browser and obtain the OAuthVerifier connection property.

  1. Choose one of these options:

    • If you are using the Embedded OAuth Application click Azure Data Lake Storage OAuth endpoint to open the endpoint in your browser.
    • If you are using a custom OAuth application, create the Authorization URL by setting the following properties:
      • InitiateOAuth: Set to OFF.
      • OAuthClientId: Set to the client Id assigned when you registered your application.
      • OAuthClientSecret: Set to the client secret assigned when you registered your application.
      Then call the GetOAuthAuthorizationURL stored procedure with the appropriate CallbackURL. Open the URL returned by the stored procedure in a browser.

  2. Log in and grant permissions to the 本製品. You are then redirected to the callback URL, which contains the verifier code.
  3. Save the value of the verifier code. Later you will set this in the OAuthVerifier connection property.
Next, you need to exchange the OAuth verifier code for OAuth refresh and access tokens. Set the following properties:

On the headless machine, set the following connection properties to obtain the OAuth authentication values:

  • InitiateOAuth: Set this to REFRESH.
  • OAuthVerifier: Set this to the verifier code.
  • OAuthClientId: (custom applications only) Set this to the client Id in your custom OAuth application settings.
  • OAuthClientSecret: (custom applications only) Set this to the client secret in the custom OAuth application settings.
  • OAuthSettingsLocation: Set this to the path to the file where the driver saves the OAuth token values that persist across connections.

After the OAuth settings file is generated, you need to re-set the following properties to connect:

  • InitiateOAuth: Set this to REFRESH.
  • OAuthClientId: (custom applications only) Set this to the client Id assigned when you registered your application.
  • OAuthClientSecret: (custom applications only) Set this to the client secret assigned when you registered your application.
  • OAuthSettingsLocation: Set this to the file containing the encrypted OAuth authentication values. Make sure this file grants read and write permissions to the 本製品 to enable the automatic refreshing of the access token.

Option 2: Transfer OAuth Settings

Prior to connecting on a headless machine, you need to create and install a connection with the driver on a device that supports an internet browser. Set the connection properties as described in "Desktop Applications" above.

After completing the instructions in "Desktop Applications", the resulting authentication values are encrypted and written to the path specified by OAuthSettingsLocation. The default filename is OAuthSettings.txt.

Once you have successfully tested the connection, copy the OAuth settings file to your headless machine.

On the headless machine, set the following connection properties to connect to data:

  • InitiateOAuth: Set this to REFRESH.
  • OAuthClientId: (custom applications only) Set this to the client Id assigned when you registered your application.
  • OAuthClientSecret: (custom applications only) Set this to the client secret assigned when you registered your application.
  • OAuthSettingsLocation: Set this to the path to your OAuth settings file. Make sure this file gives read and write permissions to the 本製品 to enable the automatic refreshing of the access token.

Admin Consent

Admin consent refers to when the Admin for an Azure Active Directory tenant grants permissions to an application which requires an admin to consent to the use case. The embedded app within the CData Power BI Connector for Azure Data Lake Storage, contains no permissions that require admin consent. Therefore, this information applies only to custom applications.

Admin Consent Permissions

When creating a new OAuth app in the Azure Portal, you must specify which permissions the app will require. Some permissions may be marked stating "Admin Consent Required". For example, all Groups permissions require Admin Consent. If your app requires admin consent, there are a couple of ways this can be done.

The easiest way to grant admin consent is to just have an admin log into portal.azure.com and navigate to the app you have created in App Registrations. Under API Permissions, there will be a button for Grant Consent. You can consent here for your app to have permissions on the tenant it was created under.

If your organization has multiple tenants or the app needs to be granted permissions for other tenants outside your organization, the GetAdminConsentURL may be used to generate the Admin Authorization url. Unlike the GetOAuthAuthorizationURL, there will be no important information returned from this endpoint. If the grants access, it will simply return a boolean indicating that permissions were granted.

Once an admin grants consent, authentication may be performed as normal.

Client Credentials

Client credentials refers to a flow in OAuth where there is no direct user authentication taking place. Instead, credentials are created for just the app itself. All tasks taken by the app are done without a default user context. This makes the authentication flow a bit different from standard.

Client OAuth Flow

All permissions related to the client oauth flow require admin consent. This means the app embedded with the CData Power BI Connector for Azure Data Lake Storage cannot be used in the client oauth flow. You must create your own OAuth app in order to use client credentials. See カスタムAzureAD アプリの作成 for more details.

In your App Registration in portal.azure.com, navigate to API Permissions and select the Microsoft Graph permissions. There are two distinct sets of permissions - Delegated and Application permissions. The permissions used during client credential authentication are under Application Permissions. Select the applicable permissions you require for your integration.

You are ready to connect after setting one of the below connection properties groups depending on the authentication type.

  1. Client Secret
    • InitiateOAuth: Set this to GETANDREFRESH. You can cuse InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
    • AzureTenant: Set this to the tenant you wish to connet to.
    • OAuthGrantType: Set this to CLIENT.
    • OAuthClientId: Set this to the Client Id in your app settings.
    • OAuthClientSecret: Set this to the Client Secret in your app settings.
  2. Certificate
    • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
    • AzureTenant: Set this to the tenant you wish to connect to.
    • OAuthGrantType: Set this to CLIENT.
    • OAuthClientId: Set this to the Client Id in your app settings.
    • OAuthJWTCert: Set this to the JWT Certificate store.
    • OAuthJWTCertType: Set this to the type of the certificate store specified by OAuthJWTCert.

Authentication with client credentials will take place automatically like any other connection, except there will be no window opened prompting the user. Because there is no user context, there is no need for a browser popup. Connections will take place and be handled internally.

Azure サービスプリンシパル

Azure サービスプリンシパルは、OAuth を経由する接続タイプです。AuthScheme をAzureServicePrincipal に設定します。 Azure サービスプリンシパルとしての認証は、OAuth クライアントクレデンシャルフローを介して処理され、直接のユーザー認証は行われません。代わりに、クレデンシャルはアプリ自体のためだけに作成されます。アプリで実行されるすべてのタスクは、デフォルトユーザーコンテキストなしで実行されます。 リソースへのアプリケーションのアクセスは、割り当てられたロールの権限によって制御されます。

Note： ロールを割り当てる前に、カスタムアプリケーションを作成する必要があります。詳しくは、カスタムAzureAD アプリの作成 を参照してください。

Azure サービスプリンシパルを使用して認証する場合、Azure AD テナントにアプリケーションを登録する必要があります。以下の手順に従って、ロールベースのアクセス制御で使用できる新しいサービスプリンシパルを作成します。

アプリケーションへのロールの割り当て

サブスクリプションのリソースにアクセスするには、アプリケーションにロールを割り当てる必要があります。

  1. 検索バーでサブスクリプションサービスを検索・選択して、［サブスクリプション］ページを開きます。
  2. アプリケーションを割り当てる特定のサブスクリプションを選択します。
  3. ［アクセス制御 (IAM)］を開き、［追加］->［ロール割り当ての追加］を選択して［ロール割り当ての追加］ページを開きます。
  4. 作成したAzure AD アプリに割り当てるロールとして、［所有者］を選択します。

認証の完了

設定されたアプリ認証（クライアントシークレットまたは証明書）に応じて、以下のいずれかの接続プロパティグループを設定すると、接続できるようになります。

両メソッド共通

クライアントシークレットか証明書認証を選択する前に、まず以下の手順に従って設定を行います。その後、該当するセクションの設定に進んでください。

  1. AuthScheme：アプリ設定のAzureServicePrincipal に設定。
  2. InitiateOAuth：GETANDREFRESH に設定。InitiateOAuth を使えば、繰り返しOAuth の交換を行ったり、手動でOAuthAccessToken を設定する必要はなくなります。
  3. AzureTenant：接続するテナントに設定。
  4. OAuthClientId：アプリ設定のクライアントId に設定。
クライアントシークレットを使用した認証

続いて、以下を設定します。

  1. OAuthClientId：アプリ設定のクライアントId に設定。
  2. OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。

証明書を使用した認証

続いて、以下を設定します。

  1. OAuthJWTCert：JWT 証明書ストアを設定。
  2. OAuthJWTCertType：OAuthJWTCert で指定された証明書ストアの種類に設定。

MSI

Azure VM 上でAzure Data Lake Storage を実行している場合は、Managed Service Identity（MSI）の資格情報を利用して接続が可能です。

  • AuthScheme：AzureMSI に設定。

MSI 資格情報が認証用に自動的に取得されます。

Copyright (c) 2023 CData Software, Inc. - All rights reserved.
Build 22.0.8479