Renewing SharePoint Akumina App Secret Using PowerShell - Microsoft.Graph Module

  • Updated
Follow

Overview

There is a method available to renew an existing SharePoint App using PowerShell. This process maintains your existing Client ID while simply updating the Secret. Additionally, it allows you to:

  • Renew the Secret for multiple years.
  • Renew the app before it expires by retaining both the old and new Secrets, which automatically switch over upon expiration, ensuring no downtime.

You can also renew the app without needing to replace the current version in the site contents. For more details or assistance, please contact our support team.

Requirements

Ensure the following before you begin:

  • You have installed Microsoft Graph Powershell SDK: Install the Microsoft Graph PowerShell SDK.
  • You're a tenant administrator (or having Application.ReadWrite.All permission) for the Microsoft 365 tenant where the add-in was registered with the AppRegNew.aspx page.

Renewing the Client Secret

Confirm the current Client ID

There are 2 ways to do this:

  1. From 'web.config' on the AppManager server
  2. From SharePoint app in App Catalog
    1. Navigate to Admin> Admin Centers (more features)> SharePoint > Apps > App Catalog 
    2. Navigate to “Apps for SharePoint”, and locate the existing “Akumina InterChange” App and download (3 ellipses> 3 ellipses > Download)
    3. Once downloaded, navigate to file in your Windows file explorer. 
    4. Rename the downloaded file by adding the “.zip” file extension. 
    5. Extract all files to a new folder. 
    6. Open the “AppManifest” file with a program like Notepad. 

Please refer to the following documentation for the alternative options: Register SharePoint Add-ins

Prerequisites

PowerShell 7 and later is the recommended PowerShell version for use with the Microsoft Graph PowerShell SDK on all platforms. There are no additional prerequisites to use the SDK with PowerShell 7 or later.

The following prerequisites are required to use the Microsoft Graph PowerShell SDK with Windows PowerShell.

  • Upgrade to PowerShell 5.1 or later
  • Install .NET Framework 4.7.2 or later
  • Update PowerShellGet to the latest version using Install-Module PowerShellGet

The PowerShell script execution policy must be set to remote signed or less restrictive. Use Get-ExecutionPolicy to determine the current execution policy. For more information, see about_Execution_Policies.

To set the execution policy, run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Installation

To install the v1 module of the SDK in PowerShell Core or Windows PowerShell, run the following command.

Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force

Verify installation

After the installation is completed, you can verify the installed version with the following command.

Update-Module Microsoft.Graph

Generate a New Client Secret

Generate a new Client Secret with the following command lines:

Replace an expiring client secret in a SharePoint Add-in

Connect to Microsoft Graph

Connect to Microsoft Graph with Application.ReadWrite.All, Directory.ReadWrite.All scope.

Connect-MgGraph -Scopes "Application.ReadWrite.All,Directory.ReadWrite.All" # Login with corresponding scope. Should the tenant admin or anyone else have the permission.

Create a Client ID Variable

Create a client ID variable with the following line, using the client ID of the SharePoint Add-in as the parameter:

$clientId = 'client id of the add-in'

Generate a new Client Secret

Generate a new client secret with the following lines:

$appPrincipal = Get-MgServicePrincipal -Filter "AppId eq '$clientId'" # Get principal id by AppId
$params = @{
PasswordCredential = @{
DisplayName = "NewSecret" # Replace with a friendly name.
}
}
$result = Add-MgServicePrincipalPassword -ServicePrincipalId $appPrincipal.Id -BodyParameter $params # Update the secret
$base64Secret = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($result.SecretText)) # Convert to base64 string.
$app = Get-MgServicePrincipal -ServicePrincipalId $appPrincipal.Id # get existing app information
$existingKeyCredentials = $app.KeyCredentials # read existing credentials
$dtStart = [System.DateTime]::Now # Start date
$dtEnd = $dtStart.AddYears(2) # End date (equals to secret end date)
$keyCredentials = @( # construct keys
@{
Type = "Symmetric"
Usage = "Verify"
Key = [System.Text.Encoding]::ASCII.GetBytes($result.SecretText)
StartDateTime = $dtStart
EndDateTIme = $dtEnd
},
@{
type = "Symmetric"
usage = "Sign"
key = [System.Text.Encoding]::ASCII.GetBytes($result.SecretText)
StartDateTime = $dtStart
EndDateTIme = $dtEnd
}
) + $existingKeyCredentials # combine with existing
Update-MgServicePrincipal -ServicePrincipalId $appPrincipal.Id -KeyCredentials $keyCredentials # Update keys
$base64Secret # Print base64 secret
$result.EndDateTime # Print the end date.

Note

By default, the secret lasts two years if you didn't specify the EndDateTime. You can customize by using the example below to specify the EndDateTime.

$params = @{
PasswordCredential = @{
DisplayName = "NewSecret" # Replace with a friendly name.
EndDateTime = "2025-01-01T00:00:00Z" # Optional. Specify the end date you want. Using ISO 8601 format.
}
}
  • After running the above commands, the new client secret appears in the PowerShell console. You'll need to copy it to a text file to use in the next step.

Update AppManager with new Client Secret

For SharePoint Classic and Self-Hosted clients

  1. Open the web.config file for the web application project. In the appSettings section, there are keys for the client ID and client secret.
    1. The following is an example before changes are made: 
      • <appSettings>
          <add key="ClientId" value="your client id here" />
          <add key="ClientSecret" value="your old secret here" />
          <!-- ... other settings may be here ... -->
        </appSettings>
  2. Add the "SecondaryClientSecret" property and set it to your old client secret that is about to expire. Then, set the "ClientSecret" value to the new Client Secret from the previous step (from PowerShell). 
    • <appSettings>
        <add key="ClientId" value="your client id here" />
        <add key="ClientSecret" value="your NEW secret here" />
        <add key="SecondaryClientSecret" value="your OLD secret here" />
        <!-- ... other settings may be here ... -->
      </appSettings>

For Akumina-Hosted and Cloud-Hosted clients:

You'll need to provide your new Client Secret to Akumina Support to update for you.

Additional Recommendations

  • Once you renew your Client Secret, it is up to you to document and track the new expiration date.
  • If you allow your Client Secret to expire, all users will lose access to the AppManager.
  • Renewing an expired Client Secret using this process requires a 24 hour waiting period before the new Client Secret starts working. This is a limitation from Microsoft.

Related articles