Edit

Replace an expiring client secret in a SharePoint Add-in

  • Article

Important

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.

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.

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:

Generate a new secret

  1. 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'

  2. Connect to AzureAD PowerShell.

    $AzureAdCred = Get-Credential
Connect-AzureAD -Credential $AzureAdCred # Login to AzureAD

  3. 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.

  4. 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.

  1. 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>

  2. Change the name of the ClientSecret key to SecondaryClientSecret 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 property SecondaryClientSecret is already present and contains the initial or already expired old secret. In this case, delete the SecondaryClientSecret property first before renaming ClientSecret.

  3. 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 the SecondaryClientSecret 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.

  4. If you changed to a new TokenHelper.[cs|vb] file, rebuild the project.

  5. Republish the web application.

See also