How to create a service principal name for Azure Stack Hub using PowerShell

This article explains how to create a service principal name (SPN) to manage Azure and Azure Stack Hub using PowerShell.

It will guide you through the creation of:

An Azure application
A service principal name
Role assignment
Permissions

What is a service principal name?

An Azure SPN is a security identity used by user-created applications, services, and automation tools to access specific Azure resources. Think of it as a 'user identity' (username and password or certificate) with a specific role, and tightly controlled permissions. It only needs to be able to do specific things, unlike a general user identity. It improves security if you grant it only the minimum permissions level needed to perform its management tasks.

To log in and manage your resources via SPN you'll need to create an Azure application and then assign SPN to it. Only then will you be able to perform tasks against your environment.

Prerequisites

Prerequisites from a Windows-based external client are:

PowerShell 5.1, AzureStack and Microsoft Graph PowerShell Modules
- Configure the Azure Stack Hub user's PowerShell environment
- Microsoft Graph PowerShell Module:
```
Install-Module -Name Microsoft.Graph -Force -Verbose
```
Azure Active Directory

Declare variables

Enter details below to provide values for the variables in the scripts in this article:

Variable name	Variable description	Input
$PublicAzureAdminUsername	The username of a user with admin privileges for public Azure
$PublicAzureAdminPassword	The password of a user with admin privileges for public Azure
$AzureStackUsernameAdmin	The username of a user with admin privileges for Azure Stack Hub
$AzureStackUserPasswordAdmin	The password of a user with admin privileges for Azure Stack Hub
$AppName	The name of the SPN to be created
$AppURL	The homepage URL of the SPN to be created
$AppPassword	The app password for the SPN
$TenantDomain	Your Azure Active Directory tenant domain
$ArmEndpoint	The Azure Resource Manager endpoint for Azure Stack Hub
$PublicAzureResourceGroup	Resource group to be created in public Azure to test the SPN
$AzureStackResourceGroup	Resource group to be created in Azure Stack Hub to test the SPN
$PublicAzureRegion	Region in public Azure to create the test resource group in
$PublicAzureRole	Role to assign SPN in public Azure
$AzureStackRole	Role to assign SPN in Azure Stack Hub

Create a service principal name

Important

Azure AD Graph has been on a deprecation path since 30th June 2020, and will be retired on 30th June 2022. After 30th June 2022, applications will no longer receive responses from the Azure AD Graph endpoint https://graph.windows.net/.

As of October 2021, the Az PowerShell module is still using the deprecated Azure AD Graph API for cmdlets targeting Azure Active Directory (for example, Get-AzAdApplication). However, Microsoft has stated that they will update the module to use the newer and supported Microsoft Graph API.

Public Azure and Azure Stack Hub SPN
Azure Stack Hub SPN

Overview of the creation process for public Azure and Azure Stack Hub SPN

The following steps outline the process for the Azure and Azure Stack Hub SPN creation code.

Declare your variables accordingly.
Log in to your public Azure Subscription.
Create your Azure application.
Create a new service principal name for the Azure application.
Assign the appropriate Role to your service principal name.
Grant Azure AD permissions to your Azure application.
Log in to the public Azure using the SPN account.
Create a new resource group using the SPN account in the public Azure.
Remove the resource group you just created from the public Azure.
Create your Azure Stack Hub environment.
Log in to your Azure Stack Hub Subscription with administrator user credentials (needs to have Owner role).
Assign the appropriate Role to your Azure application inside your Azure Stack Hub Subscription.
Log in to your Azure Stack Hub Subscription using the SPN account.
Create a new resource group using the SPN account in Azure Stack Hub.
Remove the resource group you just created from Azure Stack Hub.

Azure and Azure Stack Hub SPN creation code

# Declare variables
$AppName = "TestApp"
$AppURL = "https://test.app"
# You can also generate a GUID app password by using: (New-Guid).Guid
$AppPassword = 'Password123!'
$AppPasswordSecure = ConvertTo-SecureString -String $AppPassword -AsPlainText -Force
$TenantDomain = "contoso.onmicrosoft.com"
$ArmEndpoint = "https://management.frn00006.azure.ukcloud.com"
$PublicAzureResourceGroup = "RGTest01"
$AzureStackResourceGroup = "RGTest01"
$PublicAzureRegion = "ukwest"
$PublicAzureRole = "Owner"
$AzureStackRole = "Owner"

# Create your Public Azure admin credentials in order to log in to your Azure subscription which you will be creating your SPN in
$PublicAzureAdminUsername = "user@contoso.onmicrosoft.com"
$PublicAzureAdminPassword = ConvertTo-SecureString -String 'Password123!' -AsPlainText -Force
$PublicAzureAdminCreds = New-Object -TypeName "System.Management.Automation.PSCredential" -ArgumentList $PublicAzureAdminUsername, $PublicAzureAdminPassword

# Log in to your public Azure subscription and Azure AD you will be creating your SPN in
Connect-MgGraph -TenantId $TenantDomain -Scopes "Directory.AccessAsUser.All"
Connect-AzAccount -Credential $PublicAzureAdminCreds

# List subscriptions
$SubId = Get-AzSubscription | Select-Object -Property SubscriptionId, TenantId

# Set context to be your active subscription
Get-AzSubscription -SubscriptionId $SubId.SubscriptionId -TenantId $SubId.TenantId | Set-AzContext

# Create an Azure AD application, this is the object that you need in order to set the SPN record against
try {
    $App = New-AzADApplication -DisplayName $AppName -HomePage $AppUrl -IdentifierUris $AppUrl -Password $AppPasswordSecure
    $AppGet = Get-AzADApplication -ObjectId $App.ObjectId.Guid
    $AppGet

    # Create a Service Principal Name (SPN) for the application created earlier
    $SPN = New-AzADServicePrincipal -ApplicationId $AppGet.ApplicationId

    Write-Output -InputObject "Waiting for the SPN to be created..."
    Start-Sleep -Seconds 35

    # Assign the Service Principal Name a role
    New-AzRoleAssignment -RoleDefinitionName $PublicAzureRole -ServicePrincipalName $AppGet.ApplicationId | Out-Null
    Get-AzRoleAssignment -ObjectId $SPN.Id.Guid
}
catch {
    Write-Error -Message $_.Exception.Message
    break
}

# Get Microsoft Graph SPN
$GraphSPN = Get-MgServicePrincipal -Filter "AppId eq '00000003-0000-0000-c000-000000000000'"
# Get all available Application permissions (Role) for Microsoft Graph
$AllApplicationPermissions = $GraphSPN.AppRoles
# Get all available Delegated permissions (Scope) for Microsoft Graph
$AllDelegatedPermissions = $GraphSPN.Oauth2PermissionScopes

# Filter down to the required permissions
$RequiredApplicationPermissionNames = @(
    "Member.Read.Hidden",
    "Application.ReadWrite.OwnedBy",
    "Application.ReadWrite.All",
    "Domain.ReadWrite.All",
    "Directory.Read.All",
    "Directory.ReadWrite.All",
    "Device.ReadWrite.All"
)
$RequiredApplicationPermissions = $AllApplicationPermissions | Where-Object -FilterScript { $_.Value -in $RequiredApplicationPermissionNames }

$RequiredDelegatedPermissionNames = @(
    "User.Read",
    "User.ReadBasic.All",
    "User.Read.All",
    "Group.Read.All",
    "Group.ReadWrite.All",
    "Directory.Read.All",
    "Directory.ReadWrite.All",
    "Directory.AccessAsUser.All",
    "Member.Read.Hidden"
)
$RequiredDelegatedPermissions = $AllDelegatedPermissions | Where-Object -FilterScript { $_.Value -in $RequiredDelegatedPermissionNames }

# Create a RequiredResourceAccess object containing the required application and delegated permissions
$RequiredPermissions = New-Object -TypeName "Microsoft.Graph.PowerShell.Models.MicrosoftGraphRequiredResourceAccess"
$RequiredPermissions.ResourceAppId = $GraphSPN.AppId
# Create application permission objects (Role)
foreach ($RequiredApplicationPermission in $RequiredApplicationPermissions) {
    $NewApplicationPermission = New-Object -TypeName "Microsoft.Graph.PowerShell.Models.MicrosoftGraphResourceAccess" -Property @{ Id = $RequiredApplicationPermission.Id; Type = "Role" }
    $RequiredPermissions.ResourceAccess += $NewApplicationPermission
}
# Create delegated permission objects (Scope)
foreach ($RequiredDelegatedPermission in $RequiredDelegatedPermissions) {
    $NewDelegatedPermission = New-Object -TypeName "Microsoft.Graph.PowerShell.Models.MicrosoftGraphResourceAccess" -Property @{ Id = $RequiredDelegatedPermission.Id; Type = "Scope" }
    $RequiredPermissions.ResourceAccess += $NewDelegatedPermission
}
$RequiredPermissions.ResourceAccess

# Add the permissions to the application
Update-MgApplication -ApplicationId $AppGet.ObjectId.Guid -RequiredResourceAccess $RequiredPermissions

# Grant admin consent for the new permissions
# The error "no reply URLs configured" can be safely ignored, the consent will have worked, this simply means that you have no redirect URIs configured for your app registration
Start-Process -FilePath "https://login.microsoftonline.com/common/adminconsent?client_id=$($AppGet.ApplicationId)"

Get-MgApplication -ApplicationId $AppGet.ObjectId | Select-Object -Property *

# Create your SPN credentials login
# Note: Username is "ApplicationId"
$SPNCreds = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $AppGet.ApplicationId, $AppPasswordSecure

# Log in to public Azure using SPN account
Connect-AzAccount -Credential $SPNCreds -ServicePrincipal -TenantId $TenantDomain

# Test your SPN account by creating a new resource group in public Azure
New-AzResourceGroup -Name $PublicAzureResourceGroup -Location $PublicAzureRegion

# Remove test resource group
Remove-AzResourceGroup -Name $PublicAzureResourceGroup -Force

# Create Azure Stack Hub environment so that you can log in to it
Add-AzEnvironment -Name "AzureStackUser" -ArmEndpoint $ArmEndpoint

# Create your Azure Stack Hub Admin (Subscription Owner) credentials
# Note: This account CAN, but does not have to, be the same as your public Azure account
$AzureStackUsernameAdmin = "user@contoso.onmicrosoft.com"
$AzureStackUserPasswordAdmin = ConvertTo-SecureString -String 'Password123!' -AsPlainText -Force
$AzureStackCredAdmin = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $AzureStackUsernameAdmin, $AzureStackUserPasswordAdmin

# Login to Azure Stack Hub as Admin (Subscription Owner)
Connect-AzAccount -EnvironmentName "AzureStackUser" -Credential $AzureStackCredAdmin

# Find application details from Azure AD
$AzureStackApp = Get-AzADApplication -DisplayName $AppGet.DisplayName

# Find Object Id of your Service Principal Name in Azure Stack Hub
$SPNAzureStackGet = Get-AzADServicePrincipal -DisplayName $AzureStackApp.DisplayName
$SPNAzureStackGet

# Assign the Service Principal Name a role i.e. Owner, Contributor, Reader, etc. - In Azure Stack Hub
New-AzRoleAssignment -RoleDefinitionName $AzureStackRole -ServicePrincipalName $AzureStackApp.ApplicationId.Guid | Out-Null
Get-AzRoleAssignment -ObjectId $SPNAzureStackGet.Id.Guid

# Log in to Azure Stack Hub using SPN account
Connect-AzAccount -EnvironmentName "AzureStackUser" -Credential $SPNCreds -ServicePrincipal -TenantId $TenantDomain

# Pull location from environment
$Location = (Get-AzLocation).Location

# Test your SPN account by creating a new resource group in Azure Stack Hub
New-AzResourceGroup -Name $AzureStackResourceGroup -Location $Location

# Remove test resource group
Remove-AzResourceGroup -Name $AzureStackResourceGroup -Force

# Export data of your SPN
$SPN = [PSCustomObject]@{
    ArmEndpoint    = $ArmEndpoint
    SubscriptionId = $SubId.SubscriptionId
    ClientId       = $AppGet.ApplicationId
    ClientSecret   = $AppPassword
    TenantId       = $SubId.TenantId
}

# Present SPN credentials
foreach ($Item in $SPN) {
    Write-Output -InputObject $Item
}

Overview of the creation process for Azure Stack Hub SPN

Declare your variables accordingly.
Create your Azure Stack Hub environment.
Log in to your Azure Stack Hub Subscription with administrator user credentials (needs to have Owner role).
Create your Azure application.
Create a new service principal name for the Azure application.
Assign the appropriate Role to your service principal name.
Log in to your Azure Stack Hub Subscription using the SPN account.
Create a new resource group using the SPN account in Azure Stack Hub.
Remove the resource group you just created from Azure Stack Hub.

Azure Stack Hub SPN creation code

# Declare variables
$AppName = "TestApp"
$AppURL = "https://test.app"
# You can also generate a GUID app password by using: (New-Guid).Guid
$AppPassword = 'Password123!'
$AppPasswordSecure = ConvertTo-SecureString -String $AppPassword -AsPlainText -Force
$TenantDomain = "contoso.onmicrosoft.com"
$ArmEndpoint = "https://management.frn00006.azure.ukcloud.com"
$AzureStackResourceGroup = "RGTest01"
$AzureStackRole = "Owner"

# Create Azure Stack Hub environment so that you can log in to it
Add-AzEnvironment -Name "AzureStackUser" -ArmEndpoint $ArmEndpoint

# Create your Azure Stack Hub admin (Subscription Owner) credentials
# Note: This account CAN, but does not have to, be the same as your public Azure account
$AzureStackUsernameAdmin = "user@contoso.onmicrosoft.com"
$AzureStackUserPasswordAdmin = ConvertTo-SecureString -String 'Password123!' -AsPlainText -Force
$AzureStackCredAdmin = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $AzureStackUsernameAdmin, $AzureStackUserPasswordAdmin

# Login to Azure Stack Hub as admin (Subscription Owner)
Connect-AzAccount -EnvironmentName "AzureStackUser" -Credential $AzureStackCredAdmin

# List subscriptions
$SubId = Get-AzSubscription | Select-Object -Property SubscriptionId, TenantId

# Set context to be your active subscription
Get-AzSubscription -SubscriptionId $SubId.SubscriptionId -TenantId $SubId.TenantId | Set-AzContext

# Create an Azure AD application, this is the object that you need in order to set the SPN record against
try {
    $App = New-AzADApplication -DisplayName $AppName -HomePage $AppUrl -IdentifierUris $AppUrl -Password $AppPasswordSecure
    $AppGet = Get-AzADApplication -ObjectId $App.ObjectId.Guid
    $AppGet

    # Create a Service Principal Name (SPN) for the application created earlier
    $SPN = New-AzADServicePrincipal -ApplicationId $AppGet.ApplicationId

    Write-Output -InputObject "Waiting for the SPN to be created..."
    Start-Sleep -Seconds 35

    # Assign the Service Principal Name a role
    New-AzRoleAssignment -RoleDefinitionName "Owner" -ServicePrincipalName $AppGet.ApplicationId | Out-Null
    Get-AzRoleAssignment -ObjectId $SPN.Id.Guid
}
catch {
    Write-Error -Message $_.Exception.Message
    break
}

# Create your SPN credentials login
# Note: (Username is "ApplicationId")
$AzureStackCred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $AppGet.ApplicationId, $AppPasswordSecure

# Log in to Azure Stack Hub using SPN account
Connect-AzAccount -EnvironmentName "AzureStackUser" -Credential $AzureStackCred -ServicePrincipal -TenantId $TenantDomain

# Pull location from environment
$Location = (Get-AzLocation).Location

# Test your SPN account by creating a new resource group in Azure Stack Hub
New-AzResourceGroup -Name $AzureStackResourceGroup -Location $Location

## Remove test resource group
Remove-AzResourceGroup -Name $AzureStackResourceGroup -Force

# Export data of your SPN
$SPN = [PSCustomObject]@{
    ArmEndpoint    = $ArmEndpoint
    SubscriptionId = $SubId.SubscriptionId
    ClientId       = $AppGet.ApplicationId
    ClientSecret   = $AppPassword
    TenantId       = $SubId.TenantId
}

# Present SPN credentials
foreach ($Item in $SPN) {
    Write-Output -InputObject $Item
}

Feedback

If you find a problem with this article, click Improve this Doc to make the change yourself or raise an issue in GitHub. If you have an idea for how we could improve any of our services, send an email to feedback@ukcloud.com.