Maintaining the Service Principal secret

When you register the add-in in SharePoint using _layouts/15/appregnew.aspx it will create a ServicePrincipal and a credential that is valid for communicating with the provider website. Before this secret expires, you need to create a new secret to not interrupt the service.

Note

As default, the credential for the ServicePrincipal is only valid for 1 year.

PowerShell scripts

To be able to run the following scripts, see Running Microsoft Online PowerShell scripts.

List credentials

The following script will list all credentials and show their valid dates. Use this to determine when you need to create a new secret.

$clientId='f86d1d91-b945-43d6-8cc9-86c947e0bc0c'

Get-MsolServicePrincipalCredential -AppPrincipalId $clientId -ReturnKeyValues $false | Where-Object { $_.Type -eq "Password" } | ForEach-Object { [PSCustomObject][Ordered]@{KeyID = $_.KeyId;StartDate = $_.StartDate;EndDate = $_.EndDate } }

Create secret

To create a secret and set it expiration date to 3 years, run the following code.

Note

Observe that it will take up to 24h for the new keys to be propagated to SharePoint Office (SPO) so make the change in good time before the old keys expires.

$secret=[Contact support@meriworks.se to get the Client Secret]
$clientId='f86d1d91-b945-43d6-8cc9-86c947e0bc0c'

$dtStart = [System.DateTime]::Now
$dtEnd = $dtStart.AddYears(3)

New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Symmetric -Usage Sign -Value $secret -StartDate $dtStart -EndDate $dtEnd
New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Symmetric -Usage Verify -Value $secret -StartDate $dtStart -EndDate $dtEnd
New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Password -Usage Verify -Value $secret -StartDate $dtStart -EndDate $dtEnd

Note

There exists two secrets to be able to allow full key rotations but in theory it should be ok to just create the new credential using the same secret as before.

Remove expired secrets

Since expired secrets will not be used, it's better to remove them.

$clientId='f86d1d91-b945-43d6-8cc9-86c947e0bc0c'

$keys = Get-MsolServicePrincipalCredential -AppPrincipalId $clientId -ReturnKeyValues $false
$dtNow = [System.DateTime]::Now
foreach($key in $keys)
{
  if($key.EndDate -lt  $dtNow)
  {
    Remove-MsolServicePrincipalCredential -KeyIds @($key.KeyId) -AppPrincipalId $clientId
    write-host $key.KeyId " - Expired - Deleted"
  } else {
    write-host $key.KeyId " - OK"
  }
}

Running Microsoft Online PowerShell scripts

Maintenance of Service Principal secrets are done using PowerShell scripts and the MsOnline PowerShell module. In order to run the PowerShell scripts above, and connect to Microsoft Office Service, the following commands are useful.

Install MsOnline module

The PowerShell module MsOnline is required. Install it using the following scripts or see the documentation above for more information.

Install-Module MsOnline

Connect to Microsoft Entra ID

To be able to find the ServicePrincipal and other things you need to connect to Microsoft Entra ID using an admin account. Run the script below or consult the documentation for more information.

Connect-MsolService