Connect-DataGatewayServiceAccount
Connect to the Data Gateway service.
Syntax
User (Default)
Connect-DataGatewayServiceAccount
[-Environment <PowerBIEnvironmentType>]
[<CommonParameters>]
ServicePrincipal
Connect-DataGatewayServiceAccount
-ApplicationId <String>
-ClientSecret <SecureString>
[-Tenant <String>]
[-Environment <PowerBIEnvironmentType>]
[<CommonParameters>]
ServicePrincipalCertificate
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:
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.
Grant admin consent for the application with the configured permissions if you specified the
RequiredResourceAccessargument. 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.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
ServicePrincipal
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
ServicePrincipalCertificate
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
ServicePrincipalCertificate
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ClientSecret
Application client secret for the service principal.
Parameter properties
| Type: | SecureString |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
ServicePrincipal
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Environment
Cloud environment to connect against. Default is Public.
Parameter properties
| Type: | PowerBIEnvironmentType |
| Default value: | None |
| Accepted values: | Public, Germany, USGov, China, USGovHigh, USGovMil |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Tenant
Tenant name or tenant ID containing the service principal account. If not specified, the COMMON tenant is used.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | TenantId |
Parameter sets
ServicePrincipal
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
ServicePrincipalCertificate
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.