Updating an expiring Client Secret

Todd Chessum -

Prerequisites for Updating a Client Secret

Ensure the following before you begin:

  • Microsoft Online Services Sign-In Assistant is installed on the development computer.
  • Microsoft Online Services PowerShell Module ( 32-bit; 64-bit) is installed on the development computer.
  • You are a Tenant Administrator for the Office 365 tenant where Prime 365 was added (we'll check for this below).

Check that user is a Member of the "Company Administrator" Role

To generate a new Client Secret that is valid for 3 years your user will need to be a member of the Company Administrator Role (you will sometime see this role referred to as Tenant Administrator or Farm Administrator).

To check if your user is a member of the Company Administrator role do the following:

  1. Open Windows PowerShell (Run as Admin) and run the following code snippets:

    Import-Module MsOnline
    Connect-MsolService

  2. A login prompt will appear. Sign in using the Tenant Administrator credentials for the Office 365 tenancy where Prime 365 was added. If you don't know what this is, sign in using your Office 365 username and password.

  3. Now run the following code snippets

    $O365ROLE = Get-MsolRole -RoleName "Company Administrator"
    Get-MsolRoleMember -RoleObjectId $O365ROLE.ObjectId

This will generate a table on screen showing which users are members of the Company Administrator role. If your user did not appear on this list you have two choices:

  • Have a user that appears on the list assign your user to the Global administrator role. Please refer to Microsofts support article on how to Assign admin roles in Office 365 for business for assistance.

  • Have a user that appears on the list perform the following steps.

Generate a Report of SharePoint Add-In Expiration Dates

To generate a report that list each Add-In in the tenant with the Client Id (displayed as PrincipalId), keys (displayed as KeyId), and the expiration date (displayed as EndDate) for each key, run the following PowerShell code:

(Note: If you did not perform the previous step, you will need to first complete steps 1 and 2 above prior to proceeding.)

$applist = Get-MsolServicePrincipal -all |Where-Object -FilterScript { ($_.DisplayName -notlike "*Microsoft*") -and ($_.DisplayName -notlike "autohost*") -and ($_.ServicePrincipalNames -notlike "*localhost*") }
$output = " "
foreach ($appentry in $applist)
{
$principalId = $appentry.AppPrincipalId
$principalName = $appentry.DisplayName

$results = Get-MsolServicePrincipalCredential -AppPrincipalId $principalId -ReturnKeyValues $false | Where-Object { ($_.Type -ne "Other") -and ($_.Type -ne "Asymmetric") }
if($results.count -gt 0)
{
$output += "PrincipalId`t:`t$principalId`n"
$output += "PrincipalName`t:`t$principalName`n"
$output += "Keys`n"
foreach($result in $results)
{
$output += "Type`t:`t" + $result.Type + "`n"
$output += "Value`t:`t" + $result.Value + "`n"
$output += "KeyId`t:`t" + $result.KeyId + "`n"
$output += "StartDate`t:`t " + $result.StartDate + "`n"
$output += "EndDate`t:`t" + $result.EndDate + "`n"
$output += "Usage`t:`t" + $result.Usage+ "`n"
$output += "`n"
}
$output += "-----------------------------------------------`n"
$output += "`n"
}
}
$output | Out-File "c:\temp\appsec.txt"

This will generate a report file located at c:\temp\appsec.txt (feel free to change the final line of the script if you would like for the report to be saved elsewhere). We recommend opening the report in NotePad ++ or Excel. Search this report for "Prime" to determine the expiration date (EndDate) for your client keys (KeyId), as well and the Client ID (PrincipalId), which will be required for the following step. 

Generating a new Client Secret that is valid for 3 years

To create a Client Secret for a given Client ID (PrincipalId) that will last 3 years, run the following PowerShell script:

(Note: If you did not perform any of the preceding steps, you will need to first complete steps 1 and 2 within the Check that user is a Member of the "Company Administrator" Role heading prior to proceeding.)

$clientId = "Replace with Prime ClientID from above"
$bytes = New-Object Byte[] 32
$rand = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rand.GetBytes($bytes)
$rand.Dispose()
$newClientSecret = [System.Convert]::ToBase64String($bytes)
$dtStart = [System.DateTime]::Now
$dtEnd = $dtStart.AddYears(3)
New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Symmetric -Usage Sign -Value $newClientSecret -StartDate $dtStart -EndDate $dtEnd
New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Symmetric -Usage Verify -Value $newClientSecret -StartDate $dtStart -EndDate $dtEnd
New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Password -Usage Verify -Value $newClientSecret -StartDate $dtStart -EndDate $dtEnd
$newClientSecret

This will generate a new Client Secret which will appear on screen. Copy this value in its entirety and paste it to a file you plan to keep and will be able to reference at a later date if required. Make sure to also add the ClientID for which this Client Secret was created to the file. In addition, open a support ticket at https://emgage.zendesk.com, or create an email to support@emgage.com, paste in your new Client Secret and the corresponding ClientID and send it to Emgage Support. Once Emgage Support receives the new Client Secret and corresponding ClientID our team will update the Provider Hosted portion of your Prime App Parts to use the new secret, providing another 3 years of functionality. We'll reach out to let you know once this update has been completed.

Note: Apart from generating the new Client Secret and passing it on the Emgage Support, no addition action is required on your end.

Deleting expired Keys

Microsoft recommends that you delete all expired keys (KeyIds) for a given Client ID (PrincipalId). The PowerShell script below will grab any expired keys for a given ClientID and delete them.

(Note: If you did not perform any of the the preceding steps, you will need to first complete steps 1 and 2 within the Check that user is a Member of the "Company Administrator" Role heading prior to proceeding.)

$clientId = "Replace with ClientID (PrincipalId) of the add-in for which you would like to delete expired keys"
$keys = Get-MsolServicePrincipalCredential -AppPrincipalId $clientId -ReturnKeyValues $false
$dtNow = [System.DateTime]::Now
foreach($key in $keys)
{
if($key.EndDate -lt $dtNow)
{
write-host $key.KeyId " Expired"
Remove-MsolServicePrincipalCredential -KeyIds @($key.KeyId) -AppPrincipalId $clientId
}
}

When run, a list the removed Client Secrets (KeyIds) will appear on screen as a confirmation of their removal.

Deleting unused Keys

Since Microsoft recommends deleting all unused keys (KeyIds) for a given Client ID (PrincipalId). The PowerShell script below will delete the specified keys for a given ClientID. Replace each KeyId value (KeyId1, KeyId2 and KeyId3) in the last line of the script below with the three unused KeyId values connected to the desired Client ID (PrincipalId) found in the report generated within the Generate a Report of SharePoint Add-In Expiration Dates section above.

Important:  Make sure not to delete the keys associated with the new 3 year Client Secret created above. The the expiration dates (EndDate) on the report to ensure you are deleting only unused keys. You may want to re-run the script from the Generate a Report of SharePoint Add-In Expiration Dates section to confirm that you will be deleting the correct keys.

(Note: If you did not perform any of the the preceding steps, you will need to first complete steps 1 and 2 within the Check that user is a Member of the "Company Administrator" Role heading prior to proceeding.)

$clientId = "Replace with ClientID (PrincipalId) of the add-in for which you would like to delete specific keys"
$keys = Get-MsolServicePrincipalCredential -AppPrincipalId $clientId
Remove-MsolServicePrincipalCredential -KeyIds @("KeyId1"," KeyId2"," KeyId3") -AppPrincipalId $clientId

When run, you may receive the following prompt:

cmdlet Get-MsolServicePrincipalCredential at command pipeline position 1
Supply values for the following parameters:
ReturnKeyValues:

If you do, just hit the return key to proceed.

When done, feel free to re-run the script from the Generate a Report of SharePoint Add-In Expiration Dates section to confirm that the desired keys have been deleted.

That's it! You're all set for another 3 years.

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk