Replace an expiring client secret in a SharePoint Add-in
SharePoint add-in model is currently still fully supported, but will be officially deprecated soon (by end of 2023) in SharePoint Online. Consider using alternative extensibility options to be more future proven with your extensibility. See the different recommendations from provided modernization guidance.
Deprecation means official statement that the feature is no longer being invested, but it's still supported. End-of-life means that the feature will be discontinued and is no longer available for use.
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.
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.
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.
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
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
appSettingssection, 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
SecondaryClientSecretas shown in the following example:
<add key="SecondaryClientSecret" value="your old secret here" />
If you are performing this procedure for the first time, there is no
SecondaryClientSecretproperty 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 property
SecondaryClientSecretis already present and contains the initial or already expired old secret. In this case, delete the
SecondaryClientSecretproperty first before renaming
Add a new
ClientSecretkey 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>
You will not be able to use the newly generated client secret until the current client secret expires. Therefore, changing the
ClientIdkey to the new client secret without the
SecondaryClientSecretkey 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.