Connect-DataGatewayServiceAccount

  • Reference
Module:
DataGateway.Profile

Connect to the Data Gateway service.

Syntax

Connect-DataGatewayServiceAccount
       [-Environment <PowerBIEnvironmentType>]
       [<CommonParameters>]
Connect-DataGatewayServiceAccount
       -ApplicationId <String>
       -ClientSecret <SecureString>
       [-Tenant <String>]
       [-Environment <PowerBIEnvironmentType>]
       [<CommonParameters>]
Connect-DataGatewayServiceAccount
       -ApplicationId <String>
       -CertificateThumbprint <String>
       [-Tenant <String>]
       [-Environment <PowerBIEnvironmentType>]
       [<CommonParameters>]

Description

Connect to the Data Gateway service with either a user or service principal account (application secret or certificate).

For user accounts, an Azure Active Directory (AAD) First-Party application is leveraged for authentication.

Follow the "Creating an Azure AD application" to create a service principal account.

To log out call Disconnect-DataGatewayServiceAccount.

Examples

Creating an Azure AD application

To create an Azure AD application compatible with the DataGateway* cmdlets run the following script that uses the Microsoft.Graph module

# In the Azure portal these will show as the Permission names "Tenant.Read.All" and "Tenant.ReadWrite.All" with the "Application" type under the Power BI Service API
$resourceAccessItems = @(
                        @{Id="654b31ae-d941-4e22-8798-7add8fdf049f";Type="Role"},
                        @{Id="28379fa9-8596-4fd9-869e-cb60a93b5d84";Type="Role"}
                        );
# In the Azure portal the ResourceAppId below is the Power BI Service
$resourceAccess = @{ResourceAppId="00000009-0000-0000-c000-000000000000"; ResourceAccess=$resourceAccessItems};

# Create the application, if you do not want the application to have full permissions remove the -RequiredResourceAccess argument
$newApp = New-MgApplication -DisplayName "DataGatewayApplication" -RequiredResourceAccess $resourceAccess

# Optionally, create a secret for the new application
$applicationPasswordRequestOptions = @{PasswordCredential=@{DisplayName="ClientSecret"}}
$applicationPasswordResponse = Add-MgApplicationPassword -ApplicationId $newApp.Id -BodyParameter $applicationPasswordRequestOptions
$clientSecret = $pwd.SecretText | ConvertTo-SecureString -AsPlainText -Force

After running the above script there are a few more steps to complete:

  1. Create a new secret (if you didn't create one with the script above) or use a certificate. For more information, see Certificates and secrets.

  2. Grant admin consent for the application with the configured permissions if you specified the RequiredResourceAccess argument. For more information, see Grant admin consent in App registrations.

Example 1

PS C:\> Connect-DataGatewayServiceAccount

Logs in using user authentication against the Public cloud, a prompt will display to collect credentials.

Example 2

PS C:\> Connect-DataGatewayServiceAccount -Environment China

Logs in using user authentication against the China cloud, a prompt will display to collect credentials.

Example 3

PS C:\> Connect-DataGatewayServiceAccount -ApplicationId b5fde143-722c-4e8d-8113-5b33a9291468 -ClientSecret (Read-Host "Enter client secret" -AsSecureString) -Tenant 4E6F731E-FD8D-496D-8AF8-349ABC5F62E0

Logs in using a service in the specified tenant against the Public cloud, a prompt will display from Read-Host to read your client application secret.

Example 4

PS C:\> ConvertFrom-SecureString -SecureString (Read-Host "Enter client secret" -AsSecureString) | Out-File -FilePath .\encryptedClientSecret.txt
PS C:\> $secureClientSecret = (cat .\encryptedClientSecret.txt | ConvertTo-SecureString)
PS C:\> Connect-DataGatewayServiceAccount -ApplicationId b5fde143-722c-4e8d-8113-5b33a9291468 -ClientSecret $secureClientSecret -Tenant 4E6F731E-FD8D-496D-8AF8-349ABC5F62E0

Logs in using a service in the specified tenant against the Public cloud using a client secret securely stored in a file to make the cmdlet non-interactive.

Example 5

PS C:\> Connect-DataGatewayServiceAccount -ApplicationId b5fde143-722c-4e8d-8113-5b33a9291468 -CertificateThumbprint 38DA4BED389A014E69A6E6D8AE56761E85F0DFA4 -Tenant 4E6F731E-FD8D-496D-8AF8-349ABC5F62E0

Logs in using a service principal in the specified tenant with an installed certificate to the Public cloud. The certificate must be installed in either CurrentUser or LocalMachine certificate store (LocalMachine requires administrator access) with a private key installed.

Parameters

-ApplicationId

Azure Active Directory (AAD) application ID (also known as Client ID) to be used with a service principal account.

For more information about applications and service principals, see Application and service principal objects in Azure Active Directory.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-CertificateThumbprint

Certificate thumbprint of an installed certificate associated to an Azure Active Directory (AAD) application. Certificate must be installed in either the CurrentUser or LocalMachine personal certificate stores (LocalMachine requires an administrator prompt to access) with a private key installed.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ClientSecret

Application client secret for the service principal.

Type:SecureString
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Environment

Cloud environment to connect against. Default is Public.

Type:PowerBIEnvironmentType
Accepted values:Public, Germany, USGov, China, USGovHigh, USGovMil
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Tenant

Tenant name or tenant ID containing the service principal account. If not specified, the COMMON tenant is used.

Type:String
Aliases:TenantId
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Inputs

None

Outputs

Microsoft.DataMovement.Powershell.Abstractions.Interfaces.IPowerBIProfile