Replace an expiring client secret in a SharePoint Add-in
Important
The SharePoint Add-In model in SharePoint Online has been deprecated as of November 27th 2023, checkout the full retirement announcement to learn more.
Deprecation means that the feature will not get any new investments, but it's still supported. SharePoint add-in model is retired fully on April 2nd, 2026 and is no longer available after that time. Primary replacement technology for the SharePoint add-in model is SharePoint Framework (SPFx) which continues to be supported also in future.
Client secrets for SharePoint Add-ins that are registered by using the AppRegNew.aspx page expire after one year. This article explains how to add a new secret for the add-in, and how to create a new client secret that is valid for a customized date.
Note
This article is about SharePoint Add-ins that are distributed through an organization catalog and registered with the AppRegNew.aspx page. If the add-in is registered on the Seller Dashboard, see Create or update client IDs and secrets in the Seller Dashboard.
Recommended maintenance schedule
We recommend creating new secrets a minimum of 30 days before they expire. This gives you a month of time before the old credentials expire.
We recommend only removing secrets a minimum of 7 days after expiration, provided you have removed them from the application configuration.
Removing an expired secret from ACS before you remove it from the application configuration will cause errors.
Prerequisites
Ensure the following before you begin:
- You have installed Azure Active Directory PowerShell 2.0: Install Azure Active Directory PowerShell for Graph
- You're a tenant administrator for the Microsoft 365 tenant where the add-in was registered with the AppRegNew.aspx page.
Generate a new secret
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'
Connect to AzureAD PowerShell.
$AzureAdCred = Get-Credential Connect-AzureAD -Credential $AzureAdCred # Login to AzureAD
Generate a new client secret with the following lines:
$endDate = (Get-Date).AddYears(1) $app = Get-AzureADServicePrincipal -Filter "AppId eq '$clientId'" $objectId = $app.ObjectId $base64secret = New-AzureADServicePrincipalPasswordCredential -ObjectId $objectId -EndDate $endDate New-AzureADServicePrincipalKeyCredential -ObjectId $objectId -EndDate $endDate -Type Symmetric -Usage Verify -Value $base64secret.Value New-AzureADServicePrincipalKeyCredential -ObjectId $objectId -EndDate $endDate -Type Symmetric -Usage Sign -Value $base64secret.Value [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($base64secret.Value)) $base64secret.EndDate # Print the end date.
The new client secret appears on the Windows PowerShell console. Copy it to a text file. You use it in the next procedure.
Tip
By default, the secret lasts one year. You can customize by leveraging the example below to specify the EndDateTime.
$endDate = (Get-Date).AddYears(2) # 2 year.
Update the remote web application in Visual Studio to use the new secret
Important
If your add-in was originally created with a pre-release version of the Microsoft Office Developer Tools for Visual Studio, it may contain an out-of-date version of the TokenHelper.[cs|vb] file. If the file does not contain the string secondaryClientSecret
, it is out of date and must be replaced before you can update the web application with a new secret. To obtain a copy of a release version of the file, you need Visual Studio 2012 or later. Create a new SharePoint Add-in project in Visual Studio. Copy the TokenHelper.[cs|vb] file from it to the web application project of your SharePoint Add-in.
Open the SharePoint Add-in project in Visual Studio, and open the web.config file for the web application project. In the
appSettings
section, there are keys for the client ID and client secret. The following is an example:<appSettings> <add key="ClientId" value="your client id here" /> <add key="ClientSecret" value="your old secret here" /> ... other settings may be here ... </appSettings>
Change the name of the
ClientSecret
key toSecondaryClientSecret
as shown in the following example:<add key="SecondaryClientSecret" value="your old secret here" />
Note
If you are performing this procedure for the first time, there is no
SecondaryClientSecret
property entry at this point in the configuration file. However, if you are performing the procedure for a subsequent client secret expiration (second or third), the propertySecondaryClientSecret
is already present and contains the initial or already expired old secret. In this case, delete theSecondaryClientSecret
property first before renamingClientSecret
.Add a new
ClientSecret
key and give it your new client secret. Your markup should now look like the following:<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>
Important
You will not be able to use the newly generated client secret until the current client secret expires. Therefore, changing the
ClientId
key to the new client secret without theSecondaryClientSecret
key present will not work. You must follow the procedure in this article and wait for the previous client secret to expire. You can then remove the SecondaryClientSecret if you want to.If you changed to a new TokenHelper.[cs|vb] file, rebuild the project.
Republish the web application.