Extending Expired Client Secret for SharePoint Online Add-Ins

Problem Statement

The user has a Provider-hosted Add-ins for SharePoint Online (SPO) which is hosted in either Azure or a public facing IIS Server and it fails due to Expired client secret key.


All newly installed Add-Ins fails with errors below in logs or existing add-in started having an issue connecting to the remote web. You might see errors in logs like below:


Microsoft.IdentityModel.SecurityTokenService.RequestFailedException: Token request failed. ---> System.Net.WebException: The remote server returned an error: (401) Unauthorized.


Invalid issuer or signature.

at Microsoft.IdentityModel.S2S.Tokens.JsonWebSecurityTokenHandler.VerifySignature(String signingInput, String signature, String algorithm, SecurityToken signingToken)

at Microsoft.IdentityModel.S2S.Tokens.JsonWebSecurityTokenHandler.ReadTokenCore(String token, Boolean isActorToken)




By default, all client secrets are set to expire in SPO after one year of the initial Add-in install or registration. The client secrets must be renewed otherwise the applications will stop working.


The user can extend client secret for up to 3 years before they are expired. Microsoft provides excellent documentation for replacing an expiring or expired client secret in a SharePoint Add-ins and that should always be the first and primary source of instructions for updating a client secret.

Once you have determined that your client secret has expired or about be expired, there are two ways to update client secret either by creating new secret or extending the existing ones.

NOTE: This document merely will serve as a guide to update the client secret but we rely mainly on Microsoft Instructions since this entire process is controlled by Microsoft and Gimmal is not responsible for validity and accuracy of instructions over its lifetime.

This prerequisite is required for all three methods below:


Here is the quick overview of the steps involved:

1. Determine if the client secret has expired. Follow instructions in Appendix A to determine the end date.

2. Check for duplicate or multiple app registrations or client secret. Follow instructions in Appendix B to clear out duplicates.

3. Use appropriate methods below to resolve your client secret expiration issue:

a) Method 1: Create a New client secret

b) Method 2: Extend an existing client secret

c) Method 3: Use Gimmal Scripts

Method 1Create a New Client Secret

Microsoft provides documentation for replacing an expiring or expired client secret in a SharePoint Add-ins by generating new client secret. These instructions will be the primary source for extending a client secret.

Use these instructions to update all the Content Governance and Record Management(RM) Add-ins client secret keys, which is installed in SharePoint Online. The Microsoft instructions mention updating web.config files for add-ins with the new client secret keys. Please refer to Appendix C and Appendix D on how to locate web.config files for all Gimmal Add-ins with a remote web application.

Since we are generating a new client secret, there are some important additional product-specific post configuration steps described in Appendix E. These steps must be performed for Gimmal add-ins to use new client secret keys.


As Mentioned in the last step of Microsoft documentation it is highly recommended to wait for at least 24 hours after extending client secret for it to be effective.

Method 2Extending an existing Client Secret

NOTE: These steps only apply if either your client secret is already expired or want to use the same client secret.

The benefit of extending existing client secret is that you don’t have to perform post configuration steps for our Add-Ins.

  1. Locate existing Client ID and ClientSecret keys from web.config for each Add-Ins. Use Appendix C and Appendix D to locate web.config files for each product.
  2. Copy the ClientID and ClientSecret keys to a notepad file.
  3. Use the Microsoft instructions described here, using the client secret keys copied in step 2 and extend it for 3 years.
  4. Skip the ‘Generate a new secret’ step in Microsoft Instructions.

Method 3: Gimmal Extend Client Secret Script

Gimmal has created a script(attached) to simplify the Microsoft client secret extension process for people who find MS instructions hard to follow or are not comfortable with PowerShell. The script basically uses the same MS commands and present it in a user-friendly manner.

  1. Extract the attached ExtendClientSecret.zip file to a directory on the server which meets all the prerequisites mentioned earlier.
  2. You should find following in the directory: 
  3. Open the Client_Secret.csv file and fill in the following fields

Display Name: This is a product display name used at the time of install. You can get this by running ‘checkAppPrincipalExpire.ps1’ script described in Appendix A.

Client ID: This is unique 32 bit Id unique to each product. You can get this either from web.config(see Appendix C and D for location) for the add-in or .GAI file or by running ‘checkAppPrincipalExpire.ps1’ script described in Appendix A.

Client Secret: Copy the existing ClientSecret key from either web.config(see Appendix C and D for location) or .GAI of the add-in.

Provider Host URL: This would be server URL where the remote web is hosted, include the port number (if not 443 or 80) but no protocols (HTTP, HTTPS). e.g., serverdomainurl.com:8003

  1. Save and Close the CSV file.
  2. Open Windows PowerShell(with Microsoft Online Services PowerShell Module) as administrator and navigate to the directory where the above script is stored.
  3. Run the command below to connect to O365 tenant with Tenant administrator credentials


  1. Run extendsecret.ps1 and provide the name of the .csv file you filled in step 3.
  2. Once the above script is finished the client secret for all your add-ins entered in the .csv file should be extended for 3 years. However, as per Microsoft Documentation wait for 24 hours for a new client secret to be effective.

Appendix A: How to find the Client Secret End date

You can follow the Microsoft instructions here to find out the expiration dates of Installed SharePoint Add-Ins in O365.

Gimmal have used same Microsoft instructions and created a script called ‘checkAppPrincipalExpire.ps1’(attached) which can provide you with the same details in a more user-friendly manner.

  1. Open Windows PowerShell(with Microsoft Online Services PowerShell Module) as an Administrator
  2. Run the following command and enter your O365 tenant admin credentials


  1. Run the checkAppPrincipalExpire.ps1
  2. When prompted for the search string, enter the name of the Add-In. Ex: Gimmal Advanced Content Type Retention Administration. The script returns the expiration date details for that Add-in.                                              

Appendix B: Remove Duplicates

If you find yourself in the following condition:

1. Have Duplicate registrations for same App Principle or Client Id.

2. Multiple app registrations with different Client Ids.

3. Incorrect server URL or port number used at the app registration process

Even though some of this would not hurt but It is highly recommended that to clean up these entries. Follow the instructions below to find and remove these redundant entries:

a) Open Windows PowerShell(with Microsoft Online Services PowerShell Module) and run following commands:


#Enter O365 Tenant administrator credentials

Get-MsolServicePrincipal > c:\appids.txt

b) Open appids.txt file from the location and copy the App Principal ID values which you intend to remove and run following command to remove that entry:

Remove-MsolServicePrincipal -AppPrincipalId 'copied app principle ID'

Appendix C: Locating the Remote web and Web Config file through IIS

How to locate web config file for any SharePoint Online Add-in which as a Remote Web Application hosted on IIS:

  1. Navigate to the server which is hosting your remote web application for Concerned Add-In. e.g., Willow.
  2. Open Internet Information Services(IIS) Manager and locate the add-in web application under sites and Right click on it and click Explore                                    
  3. It will take you to web directory where web.config is located                                   
  4. Open the web.config with Edit permission and locate Client ID and Client Secret keys under <appsettings> tag     

Appendix D: Default Directory Location of Gimmal Add-Ins Config files

The location below gives you the generic default location of the following:

1. web.config file for all Governance and RM Add-Ins.

2. Config file for Gimmal Job Scheduler.

3. Config file for RM online connector service.

The Location of this directory could be different for each customer depending on how and where they kept their web application directory but the app name should remain the same.

Governance Apps:


Default app directory names for all Governance Add-Ins:










Gimmal Job Scheduler:

C:\Gimmal Job Scheduler\GovernanceHub.TimerService.exe.config

SharePoint Online Connector(Record Management):

C:\Program Files\RecordLion\SharePoint Online Connector\Web\web.config

SharePoint Online Connector Service Config :
C:\Program Files\RecordLion\SharePoint Online Connector\Services\RecordLion.RecordsManager.SPOnline.Service.exe.config

Appendix E: Post Configuration Steps

These steps only apply if the client secret key was changed while extending. There are some additional product-specific configuration files which use Add-ins Client ID and Secret for its functions.

1. Content Governance Add-ins

  • Gimmal Job Scheduler uses Governance Hub Add-In Client ID and Secret information for its functioning. Therefore it is important to update its config file with the new Governance Hub client secret key. Please refer to Appendix D to locate the config file for Gimmal Job Scheduler.
  • It is recommended that you update the .GAI files which you saved for each Governance Add-in (at time of initial installation) with this new client secret so it has the latest values when next time you upgrade the Add-ins.

2. Records Management Add-in

  • SharePoint Online Connector has an additional service config file which utilizes add-ins client secret for its functioning and therefore needs to be updated with new client secret key. You can refer to Appendix D to get the location of this config file. 
Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk