Applies to: Azure Stack integrated systems and Azure Stack Development Kit
When an application needs access to deploy or configure resources through Azure Resource Manager in Azure Stack, you create a service principal, which is a credential for your application. You can then delegate only the necessary permissions to that service principal.
As an example, you may have a configuration management tool that uses Azure Resource Manager to inventory Azure resources. In this scenario, you can create a service principal, grant the reader role to that service principal, and limit the configuration management tool to read-only access.
Service principals are preferable to running the app under your own credentials because:
- You can assign permissions to the service principal that are different than your own account permissions. Typically, these permissions are restricted to exactly what the app needs to do.
- You do not have to change the app's credentials if your responsibilities change.
- You can use a certificate to automate authentication when executing an unattended script.
Depending on how you have deployed Azure Stack, you start by creating a service principal. This document guides you through creating a service principal for both Azure Active Directory (Azure AD) and Active Directory Federation Services(AD FS). Once you've created the service principal, a set of steps common to both AD FS and Azure Active Directory are used to delegate permissions to the role.
Create service principal for Azure AD
If you've deployed Azure Stack using Azure AD as the identity store, you can create service principals just like you do for Azure. This section shows you how to perform the steps through the portal. Check that you have the required Azure AD permissions before beginning.
Create service principal
In this section, you create an application (service principal) in Azure AD that will represent your application.
- Log in to your Azure Account through the Azure portal.
- Select Azure Active Directory > App registrations > Add
- Provide a name and URL for the application. Select either Web app / API or Native for the type of application you want to create. After setting the values, select Create.
You have created a service principal for your application.
When programmatically logging in, you use the ID for your application and an authentication key. To get those values, use the following steps:
From App registrations in Active Directory, select your application.
Copy the Application ID and store it in your application code. The applications in the sample applications section refer to this value as the client id.
To generate an authentication key, select Keys.
Provide a description of the key, and a duration for the key. When done, select Save.
After saving the key, the value of the key is displayed. Copy this value because you are not able to retrieve the key later. You provide the key value with the application ID to sign as the application. Store the key value where your application can retrieve it.
Once complete, proceed to assigning your application a role.
Create service principal for AD FS
If you have deployed Azure Stack with AD FS, you can use PowerShell to create a service principal, assign a role for access, and sign in from PowerShell using that identity.
Before you begin
Import the Identity PowerShell module
After you download the tools, navigate to the downloaded folder and import the Identity PowerShell module by using the following command:
When you import the module, you may receive an error that says “AzureStack.Connect.psm1 is not digitally signed. The script will not execute on the system”. To resolve this issue, you can set execution policy to allow running the script with the following command in an elevated PowerShell session:
Create the service principal
You can create a Service Principal by executing the following command, making sure to update the DisplayName parameter:
$servicePrincipal = New-AzSADGraphServicePrincipal ` -DisplayName "<YourServicePrincipalName>" ` -AdminCredential $(Get-Credential) ` -AdfsMachineName "AZS-ADFS01" ` -Verbose
Assign a role
Once the Service Principal is created, you must assign it to a role
Sign in through PowerShell
Once you've assigned a role, you can sign in to Azure Stack using the service principal with the following command:
Add-AzureRmAccount -EnvironmentName "<AzureStackEnvironmentName>" ` -ServicePrincipal ` -CertificateThumbprint $servicePrincipal.Thumbprint ` -ApplicationId $servicePrincipal.ApplicationId ` -TenantId $directoryTenantId
Assign role to service principal
To access resources in your subscription, you must assign the application to a role. Decide which role represents the right permissions for the application. To learn about the available roles, see RBAC: Built in Roles.
You can set the scope at the level of the subscription, resource group, or resource. Permissions are inherited to lower levels of scope. For example, adding an application to the Reader role for a resource group means it can read the resource group and any resources it contains.
In the Azure Stack portal, navigate to the level of scope you wish to assign the application to. For example, to assign a role at the subscription scope, select Subscriptions. You could instead select a resource group or resource.
Select the particular subscription (resource group or resource) to assign the application to.
Select Access Control (IAM).
Select the role you wish to assign to the application.
Search for your application, and select it.
Select OK to finish assigning the role. You see your application in the list of users assigned to a role for that scope.
Now that you've created a service principal and assigned a role, you can begin using this within your application to access Azure Stack resources.