Automating On-Premises Gateways Using PowerShell
    • Dark
      Light
    • PDF

    Automating On-Premises Gateways Using PowerShell

    • Dark
      Light
    • PDF

    Article Summary

    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.

    2-Overview

    3-ObjectId

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

    4-secret(3)

    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.

    5-Api

    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.

    6-ManageGatewayInstallers

    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.


    Was this article helpful?