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

This document explains how to create a service principal name to manage Azure and Azure Stack 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 service principal name (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 Azure AD PowerShell Modules
- Configure the Azure Stack user's PowerShell environment
- Azure AD PowerShell Module. To install:
```
Install-Module -Name AzureAD -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
$AzsUsernameAdmin	The username of a user with admin privileges for Azure Stack
$AzsUserPasswordAdmin	The password of a user with admin privileges for Azure Stack
$AppName	The name of the SPN to be created
$AppURL	The homepage URL of the SPN to be created
$AppPassword	The client secret (password) of the SPN to be created
$TenantDomain	Your Azure Active Directory tenant domain
$ArmEndpoint	The Azure Resource Manager endpoint for Azure Stack
$PublicAzureResourceGroup	Resource group to be created in public Azure to test the SPN
$AzureStackResourceGroup	Resource group to be created in Azure Stack 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

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

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 environment.
Log in to your Azure Stack Subscription with administrator user credentials (needs to have Owner role).
Assign the appropriate Role to your Azure application inside your Azure Stack Subscription.
Log in to your Azure Stack Subscription using the SPN account.
Create a new resource group using the SPN account in Azure Stack.
Remove the resource group you just created from Azure Stack.

Azure and Azure Stack SPN creation code

# Declare Variables
$AppName = "TestApp"
$AppURL = "https://test.app"
$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 you will be creating you SPN on
$PublicAzureAdminUsername = "user@contoso.onmicrosoft.com"
$PublicAzureAdminPassword = ConvertTo-SecureString -String 'Password123!' -AsPlainText -Force
$PublicAzureAdminCred = 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 on
Connect-AzureAD -Credential $PublicAzureAdminCred -TenantId $TenantDomain
Connect-AzureRmAccount -Credential $PublicAzureAdminCred

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

# Set context to be your active Subscription
Get-AzureRmSubscription -SubscriptionId $SubId.SubscriptionId -TenantId $SubId.TenantId | Set-AzureRmContext

# Create an Azure AD application, this is the object that you need in order to set SPN record against.
# Record ApplicationId from output.
$App = New-AzureADApplication -DisplayName $AppName -HomePage $AppURL -IdentifierUris $AppURL
$AppPassword = New-AzureADApplicationPasswordCredential -ObjectId $App.ObjectId -Value $AppPassword
$AppGet = Get-AzureADApplication -ObjectId $App.ObjectId
$AppGet

# Create a Service Principal Name (SPN) for the application you created earlier.
$SPN = New-AzureADServicePrincipal -AppId $AppGet.AppId
$SPNGet = Get-AzureADServicePrincipal -SearchString "$($AppGet.DisplayName)"
$SPNGet

# Assign the Service Principal Name a role i.e. Owner, Contributor, Reader, etc. - In public Azure
#### Requires a few seconds... before it can be run
Write-Output -InputObject "Waiting for the SPN to be created..."
Start-Sleep -Seconds 30
$RoleAssignment = New-AzureRmRoleAssignment -RoleDefinitionName $PublicAzureRole -ServicePrincipalName $AppGet.AppId

# Grant Permission to Azure Active Directory to SPN
$Req = New-Object -TypeName "Microsoft.Open.AzureAD.Model.RequiredResourceAccess"
$Req.ResourceAppId = "00000002-0000-0000-c000-000000000000"
$Acc1 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "5778995a-e1bf-45b8-affa-663a9f3f4d04", "Role"
$Acc2 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "abefe9df-d5a9-41c6-a60b-27b38eac3efb", "Role"
$Acc3 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "78c8a3c8-a07e-4b9e-af1b-b5ccab50a175", "Role"
$Acc4 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "1138cb37-bd11-4084-a2b7-9f71582aeddb", "Role"
$Acc5 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "9728c0c4-a06b-4e0e-8d1b-3d694e8ec207", "Role"
$Acc6 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "824c81eb-e3f8-4ee6-8f6d-de7f50d565b7", "Role"
$Acc7 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "1cda74f2-2616-4834-b122-5cb1b07f8a59", "Role"
$Acc8 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "aaff0dfd-0295-48b6-a5cc-9f465bc87928", "Role"
$Acc9 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "a42657d6-7f20-40e3-b6f0-cee03008a62a", "Scope"
$Acc10 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "5778995a-e1bf-45b8-affa-663a9f3f4d04", "Scope"
$Acc11 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "78c8a3c8-a07e-4b9e-af1b-b5ccab50a175", "Scope"
$Acc12 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "970d6fa6-214a-4a9b-8513-08fad511e2fd", "Scope"
$Acc13 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "6234d376-f627-4f0f-90e0-dff25c5211a3", "Scope"
$Acc14 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "c582532d-9d9e-43bd-a97c-2667a28ce295", "Scope"
$Acc15 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "cba73afc-7f69-4d86-8450-4978e04ecd1a", "Scope"
$Acc16 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "311a71cc-e848-46a1-bdf8-97ff7156d8e6", "Scope"
$Acc17 = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess" -ArgumentList "2d05a661-f651-4d57-a595-489c91eda336", "Scope"
$Req.ResourceAccess = $Acc1, $Acc2, $Acc3, $Acc4, $Acc5, $Acc6, $Acc7, $Acc8, $Acc9, $Acc10, $Acc11, $Acc12, $Acc13, $Acc14, $Acc15, $Acc16, $Acc17

$AzureADPermissions = Set-AzureADApplication -ObjectId $AppGet.ObjectId -RequiredResourceAccess $Req
$AzureADPermissionsGet = Get-AzureADApplication -ObjectId $AppGet.ObjectId | Select-Object -Property *
$AzureADPermissionsGet

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

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

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

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

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

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

# Login to Azure Stack as Admin (Subscription Owner)
Connect-AzureRmAccount -EnvironmentName "AzureStackUser" -Credential $AzsCredAdmin

# Find application details from Azure AD
$AzsApp = Get-AzureRmADApplication -DisplayNameStartWith "$($AppGet.DisplayName)"

# Find Object Id of your Service Principal Name in Azure Stack
$SPNAzsGet = Get-AzureRmADServicePrincipal -SearchString "$($AzsApp.DisplayName)"
$SPNAzsGet

# Wait for the application and SPN to be created
Write-Output -InputObject "Waiting for the application and SPN to be created..."
Start-Sleep -Seconds 30

# Assign the Service Principal Name a role i.e. Owner, Contributor, Reader, etc. - In Azure Stack
$RoleAssignmentAzs = New-AzureRmRoleAssignment -RoleDefinitionName $AzureStackRole -ServicePrincipalName $AzsApp.ApplicationId.Guid
$RoleAssignmentGet = Get-AzureRmRoleAssignment -ObjectId $SPNAzsGet.Id.Guid
$RoleAssignmentGet

# Log in to Azure Stack using SPN account
Connect-AzureRmAccount -EnvironmentName "AzureStackUser" -Credential $AzsCred -ServicePrincipal -TenantId $TenantDomain

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

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

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

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

$OutputObject

Overview of the creation process for Azure Stack SPN

Declare your variables accordingly.
Create your Azure Stack environment.
Log in to your Azure Stack 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 Subscription using the SPN account.
Create a new resource group using the SPN account in Azure Stack.
Remove the resource group you just created from Azure Stack.

Azure Stack SPN creation code

# Declare Variables
$AppName = "TestApp"
$AppURL = "https://test.app"
$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 Environment so that you can log in to it
Add-AzureRmEnvironment -Name "AzureStackUser" -ArmEndpoint $ArmEndpoint

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

# Login to Azure Stack as Admin (Subscription Owner) and Azure AD
Connect-AzureAD -Credential $AzsCredAdmin -TenantId $TenantDomain
Connect-AzureRmAccount -EnvironmentName "AzureStackUser" -Credential $AzsCredAdmin

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

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

# Create an Azure AD application, this is the object that you need in order to set SPN record against.
# Record ApplicationId from output.
$App = New-AzureADApplication -DisplayName $AppName -HomePage $AppURL -IdentifierUris $AppURL
$AppPassword = New-AzureADApplicationPasswordCredential -ObjectId $App.ObjectId -Value $AppPassword
$AppGet = Get-AzureADApplication -ObjectId $App.ObjectId
$AppGet

# Create a Service Principal Name (SPN) for the application you created earlier.
$SPN = New-AzureADServicePrincipal -AppId $AppGet.AppId
$SPNAzsGet = Get-AzureADServicePrincipal -SearchString "$($AppGet.DisplayName)"
$SPNAzsGet

# Wait for the application and SPN to be created
Write-Output -InputObject "Waiting for the application and SPN to be created..."
Start-Sleep -Seconds 30

# Find application details from Azure AD
$AzsApp = Get-AzureRmADApplication -DisplayNameStartWith "$($AppGet.DisplayName)"

# Assign the Service Principal Name a role i.e. Owner, Contributor, Reader, etc. - In Azure Stack
$RoleAssignmentAzs = New-AzureRmRoleAssignment -RoleDefinitionName $AzureStackRole -ServicePrincipalName $AzsApp.ApplicationId.Guid
$RoleAssignmentGet = Get-AzureRmRoleAssignment -ObjectId $SPNAzsGet.ObjectId
$RoleAssignmentGet

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

# Log in to Azure Stack using SPN account
Connect-AzureRmAccount -EnvironmentName "AzureStackUser" -Credential $AzsCred -ServicePrincipal -TenantId $TenantDomain

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

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

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

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

$OutputObject

Feedback

If you find an issue with this article, click Improve this Doc to suggest a change. If you have an idea for how we could improve any of our services, visit the Ideas section of the UKCloud Community.