When an automated task or an app needs to access data from Office 365, you need to create an app in the tenant's Azure Active Directory (AAD). For having full control, e.g. for deleting objects in AAD, a so called Service Principal Name (SPN) can be used. That is similar to a Global Admin in Office 365, but just for apps and usually with a predefined expiration date. Which is good. Or?
You can get more information about SPN's at Service Principal Names and here. So, at some time, the expiration date is reached. And that's why I am writing this article. It happened ... today for some of my apps. This blog post is for developers and DevOps people who are already using SPN's and want to renew them. See the How-to here.
Using Azure CLI
There are multiple ways to create or maintain SPNs. I used the simple approach with Azure CLI for doing that job. You get the latest Windows version at https://aka.ms/InstallAzureCliWindows. See Install Azure CLI 2.0 on Windows for other platforms as Linux and for more details.
After the installation, you need to have a Global Admin of an Office 365 tenant for the login process. So, let's open a command prompt and try some CLI commands - they start with "az". az help shows the available commands. Check out Get started with Azure CLI 2.0 for the first steps.
az --version delivers the installed version of the CLI, in my case 2.0.21.
Login...
With az login , I can connect to my Azure subscriptions, see Interactive log-in.
So, the next step is to open the browser to register your current device with that code and to login with your Azure management account.
After the successful login, the browser informs: "Microsoft Azure Cross-platform Command Line Interface.
You have signed in to the Microsoft Azure Cross-platform Command Line Interface application on your device. You may now close this window." So, the browser can be closed.
Show all Azure subscriptions
The Azure CLI now automatically lists entitled Azure subscriptions for the authenticated user, similar to here with my account.
To get the list, use: az account list --all --out jsonc
Or redirect the output to a file for further usage... az account list --all --out jsonc > C:\temp\mysubscriptions.txt
Set the active Azure subscription
To work with a specific Azure subscription, set it by name (e.g. my subscription named S2): az account set --subscription "S2"
To check the current active subscription, use az account show
Create a new SPN
If you need a new SPN, create that object with az ad sp create-for-rbac
By default, this account is valid for one year from now on. You can add the --years parameter for another time frame. See more about Manage Azure Active Directory service principals for automation authentication, as using certificates, key vault, roles and scopes at az ad sp.
List existing SPNs
To list and to check service principals, use az ad sp list
...or redirect them to another file for further usage: az ad sp list > c:\temp\myspns.txt
We see the SPNs from Microsoft apps like Microsoft Flow Portal, Microsoft Device Directory Service, Azure Machine Learning, AzureApplicationInsights, etc. and custom created ones. This delivers all SPNs from all subscriptions, not just from the active subscription.
The interesting part here is, that we get most SPN properties, but no client secret (the "password" of a SPN) and no expiration date. So, one SPN is delivered as here:
{
"appId": "e7fd16c5-...",
"displayName": "azure-cli-2017-03-27-12-28-25",
"objectId": "195502e6-...",
"objectType": "ServicePrincipal",
"servicePrincipalNames": [
"http://azure-cli-2017-03-27-12-28-25",
"e7fd16c5-..."
]
}, ...{next SPN}...
But, for SPNs created with Azure CLI (as above), we see the displayName with the creation date of that SPN, in this sample created on March 27th, 2017. So, more or less we see the expired SPNs (after one or two years) and we can renew them.
Renew a SPN
Let's renew a SPN with a new secret ("password") and 2 years runtime as follows:
az ad sp reset-credentials --name "azure-cli-2017-03-27-12-28-25" --years 2
Kindly, you can also use the SPN objectId (with the same parameter) instead of the displayName to reset the credentials:
az ad sp reset-credentials --name "195502e6-..." --years 2
The command returns an output with the new generated password for that SPN, similar as here:
{
"appId": "195502e6-...",
"name": "azure-cli-2017-03-27-12-28-25",
"password": "d00c735d-...",
"tenant": "d827fc60-..."
}
As in the Azure portal in the AAD app management, this is the only chance to save the password (after creation), since you never get it again.
Renew your app
When this is done, you need to modify your app(s) that use that SPN and to paste in the new password from the output above (d00c735d-...).
Test the new SPN
You can test the new or renewed SPN with Azure CLI as well and see if it works:
az login --service-principal -username {APP_ID} -password {PASSWORD} -tenant {TENANT_ID}
Delete a SPN
If a SPN is no longer used, delete it, see az ad sp delete.
az ad sp delete --id "195502e6-..."
Add Azure roles to your SPN
If your want to use your SPN to access Azure subscriptions and resources with a specific role, check out az ad sp create-for-rbac.
This command assigns a RBAC role to the specified principal at the specified scope as here:
az ad sp create-for-rbac -n "MyApp" --role contributor
--scopes /subscriptions/{SubID}/resourceGroups/{ResourceGroup1}
/subscriptions/{SubID}/resourceGroups/{ResourceGroup2}
Or use PowerShell
If you prefer to work with PowerShell, install Azure AD PowerShell or the Azure AD PowerShell for Graph preview module from the PowerShell Gallery at the AzureADPreview page. Then, sign-in with Login-AzureRmAccount.
Check out New-AzureRmRoleAssignment. This is the equivalent to set a specified RBAC role to a principal with a specified scope. This sample adds the SPN as owner for a SQL Server resource:
New-AzureRmRoleAssignment -RoleDefinitionName Owner -ServicePrincipalName '{SPN-ID}' `
-Scope '/subscriptions/{Subscription-id}/resourceGroups/{RG-id}
/providers/Microsoft.Sql/servers/{MyDBServer}'
Add a reminder to your calendar
From a security perspective, it's a good idea to use SPNs with a runtime of just one year or two. But, don't forget to renew the credentials as described above and to add a reminder to your calendar for the renewal. Otherwise, you might to search for errors when the SPN has expired and you simply forgot to renew the SPN used by your app(s).
I hope this article helps Developers and DevOps people with the How-To to renew SPNs!