Automating On-Premises Gateways Using PowerShell

Gateways are an important part of Power Platform architectures. Since Gateways allow for connectivity between the cloud and on-premises data assets we want to be selective when it comes to who can install a gateway, who can use a gateway and what sort of permissions do they have with that gateway.

In this post we will cover how we can automate who is able to install gateways and what permissions they have. To see a video recording of this tip, please refer to this YouTube video.

Service Principal

We are going to use a Service Principal as part of our automation. This will allow us to silently install the gateway and not have it tied to a particular individual. When we create a Service Principal there are a few values that we need to capture including Application/Client Id, Directory/Tenant Id and our Managed application Object Id.

In order to connect to the Power BI APIs we will need to create a client secret from the Certificates & secrets experience.

Next, we need to assign our Service Principal access to the Power BI Service. When we add a permission we will need to include both the Tenant.Read.All and Tenant.ReadWrite.All permissions. Note, this will require tenant admin consent.

Set Managed Installers

Most organizations have implemented a control over who can install a gateway. Through the user interface in the Power Platform Admin center, we can include people who are allowed to install the gateway. However, this user experience currently does not support Service Principals. But, that is ok, we can use the following PowerShell script to add our Service Principal into the list of gateway installers.

Note: Even after you add the service principal, you won’t find it listed in this list but you can also access this from PowerShell cmdlets.

The following script will allow you to add your Service Principal to the list of users who can install a gateway. Full script is available here.

$Psversion = (Get-Host).Version
if($Psversion.Major -ge 7)
{

if (!(Get-Module "DataGateway")) 
{
Install-Module -Name DataGateway 
}

$securePassword = "<<Secure Key>>" | ConvertTo-SecureString -AsPlainText -Force;
$ApplicationId ="<<Your Client/Application ID>>";
$Tenant = "<<Your Tenant ID>>";
$installerID = "<<Your ServicePrincipal's Managed Application Object ID";


#Gateway Login
Connect-DataGatewayServiceAccount -ApplicationId $ApplicationId -ClientSecret $securePassword  -Tenant $Tenant

#Set Gateway Installer
Set-DataGatewayInstaller -PrincipalObjectIds $installerID -Operation Add -GatewayType Resource

}
else
{
exit 1
}

Install Gateway

With our Service Principal now in the list of permitted gateway installers, we can now go ahead and install a gateway. The following script is also available here.

$Psversion = (Get-Host).Version
if($Psversion.Major -ge 7)
{
if (!(Get-Module "DataGateway")) {
Install-Module -Name DataGateway 
}
$securePassword = "<<Your Service Principal Key>>" | ConvertTo-SecureString -AsPlainText -Force;
$ApplicationId ="<<Your Service Principal Client Id>>";
$Tenant = "<<Your Tenant/Directory ID>>";
$GatewayName = "<<Your GatewayName>>";
$RecoverKey = <<Your RecoveryKey>>| ConvertTo-SecureString -AsPlainText -Force;
$userIDToAddasConnection = "<<User to add Object ID GUID>>";
$groupIDToAddasAdmin = "<<Groups Object ID GUID to add as admin>>";


#Gateway Login
Connect-DataGatewayServiceAccount -ApplicationId $ApplicationId -ClientSecret $securePassword  -Tenant $Tenant

#Installing Gateway 
Install-DataGateway -AcceptConditions 

#Configuring Gateway
$GatewayDetails = Add-DataGatewayCluster -Name $GatewayName -RecoveryKey  $RecoverKey -OverwriteExistingGateway

#We can restrict what data sources users have access to.
$dsTypes = New-Object 'System.Collections.Generic.List[Microsoft.PowerBI.ServiceContracts.Api.DatasourceType]'
$dsTypes.Add([Microsoft.PowerBI.ServiceContracts.Api.DatasourceType]::Sql)

#Reference: https://docs.microsoft.com/en-us/powershell/module/datagateway/add-datagatewayclusteruser?view=datagateway-ps#parameters

#Add User as Admin
Add-DataGatewayClusterUser -GatewayClusterId $GatewayDetails.GatewayObjectId -PrincipalObjectId $groupIDToAddasAdmin -AllowedDataSourceTypes $null -Role Admin
Add-DataGatewayClusterUser -GatewayClusterId $GatewayDetails.GatewayObjectId -PrincipalObjectId $userIDToAddasConnection -AllowedDataSourceTypes $dsTypes -Role ConnectionCreator

}
else{
exit 1
}

Conclusion

Within this post we reviewed how we can script the installation of the On-Prem data gateway. This will help enforcing consistency and making managing gateways easier. To see a video recording of this tip, please refer to this YouTube video.