You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Replace an expiring client secret in a SharePoint Add-in
3
3
description: Add a new client secret for a SharePoint Add-in that is registered with AppRegNew.aspx.
4
-
ms.date: 06/13/2022
4
+
ms.date: 06/21/2023
5
5
ms.prod: sharepoint
6
6
ms.localizationpriority: high
7
7
---
8
8
9
9
# Replace an expiring client secret in a SharePoint Add-in
10
10
11
-
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 three years.
11
+
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.
12
12
13
13
> [!NOTE]
14
-
> 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](/office/dev/store/create-or-update-client-ids-and-secrets).
14
+
> 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](/office/dev/store/create-or-update-client-ids-and-secrets).
15
15
16
16
## Recommended maintenance schedule
17
17
18
-
We recommend to create new secrets a minimum of 30 days before they expire. This gives you a month of time before the old credentials expire.
18
+
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.
19
19
20
-
We recommend to only remove secrets a minimum of 7 days after expiration, provided you have removed them from the application configuration.
20
+
We recommend only removing secrets a minimum of 7 days after expiration, provided you have removed them from the application configuration.
21
21
22
22
Removing an expired secret from ACS before you remove it from the application configuration will cause errors.
23
23
24
24
## Prerequisites
25
25
26
26
Ensure the following before you begin:
27
27
28
-
- Microsoft Online Services Sign-In Assistant is installed on the development computer.
29
-
- You can connect to Office 365 with PowerShell: [Connect to Office 365 PowerShell](/office365/enterprise/powershell/connect-to-office-365-powershell)
30
-
- You're a tenant administrator for the Office 365 tenant (or a farm administrator on the farm) where the add-in was registered with the AppRegNew.aspx page.
28
+
- You have installed Microsoft Graph Powershell SDK: [Install the Microsoft Graph PowerShell SDK](/powershell/microsoftgraph/installation)
29
+
- 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.
31
30
32
-
## Find out the expiration dates of the SharePoint Add-ins installed to the Office 365 tenancy
31
+
## Generate a new secret
33
32
34
-
1.Open Windows PowerShell and run the following cmdlet:
33
+
1.Create a client ID variable with the following line, using the client ID of the SharePoint Add-in as the parameter:
35
34
36
35
```powershell
37
-
Connect-MsolService
36
+
$clientId = 'client id of the add-in'
38
37
```
39
-
40
-
1. At the sign-in prompt, enter tenant-administrator (or farm administrator) credentials for the Office 365 tenancy or farm where the add-in was registered with AppRegNew.aspx.
41
-
1. Generate a report that lists each add-in and the date that its secret expires with the following lines. Note the following about this code:
42
-
43
-
- It first filters out Microsoft's own applications, add-ins still under development (and a now-deprecated type of add-in that was called autohosted).
44
-
- From the remainder, it filters out non-SharePoint add-ins and add-ins that use asymmetric keys, such as workflows.
38
+
1. Connect to graph with **Application.ReadWrite.All** scope:
# login with the corresponding scope; this user should be a tenant admin or anyone granted this permission
62
43
```
63
-
64
-
1. Open the file C:\temp\appsec.csv to see the report. Leave the Windows PowerShell window open for the next procedure, if any of the secrets are near expiration.
65
-
66
-
## Generate a new secret
67
-
68
-
1. Create a client ID variable with the following line, using the client ID of the SharePoint Add-in as the parameter.
44
+
45
+
1. Generate a new client secret with the following lines:
69
46
70
47
```powershell
71
-
$clientId = 'client id of the add-in'
72
-
```
48
+
$appPrincipal = Get-MgServicePrincipal -Filter "AppId eq '$clientId'" # Get principal id by AppId
73
49
74
-
1. Generate a new client secret with the following lines:
50
+
$params = @{
51
+
PasswordCredential = @{
52
+
DisplayName = "NewSecret" # Replace with a friendly name.
1. The new client secret appears on the Windows PowerShell console. Copy it to a text file. You use it in the next procedure.
91
63
92
64
> [!TIP]
93
-
> By default, the add-in secret lasts one year. You can set this to a shorter or longer by using the **-EndDate** parameter on the three calls of the **New-MsolServicePrincipalCredential** cmdlet.
65
+
> By default, the secret lasts two years if you didn't specify the EndDateTime. You can customize by leveraging the example below to specify the EndDateTime.
66
+
>
67
+
> ``` powershell
68
+
> $params = @{
69
+
> PasswordCredential = @{
70
+
> DisplayName = "NewSecret" # Replace with a firendly name.
71
+
> EndDateTime = "2025-01-01T00:00:00Z" # Optional. Specify the end date you want. Using ISO 8601 format.
72
+
> }
73
+
> }
74
+
> ```
94
75
95
76
## Update the remote web application in Visual Studio to use the new secret
96
77
97
78
> [!IMPORTANT]
98
-
> 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 (or .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 file from it to the web application project of your SharePoint Add-in.
79
+
> 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.
99
80
100
-
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:
81
+
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:
101
82
102
83
```XML
103
84
<appSettings>
104
85
<add key="ClientId" value="your client id here" />
105
86
<add key="ClientSecret" value="your old secret here" />
106
-
... other settings may be here ...
87
+
... other settings may be here ...
107
88
</appSettings>
108
89
```
109
90
110
-
1. Change the name of the **ClientSecret** key to `SecondaryClientSecret` as shown in the following example:
91
+
1. Change the name of the `ClientSecret` key to `SecondaryClientSecret` as shown in the following example:
111
92
112
93
```XML
113
94
<add key="SecondaryClientSecret" value="your old secret here" />
114
95
```
115
96
116
97
> [!NOTE]
117
-
> 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**.
98
+
> 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`.
118
99
119
-
1. Add a new **ClientSecret** key and give it your new client secret. Your markup should now look like the following:
100
+
1. Add a new `ClientSecret` key and give it your new client secret. Your markup should now look like the following:
120
101
121
102
```XML
122
103
<appSettings>
@@ -128,60 +109,11 @@ Ensure the following before you begin:
128
109
```
129
110
130
111
> [!IMPORTANT]
131
-
> 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.
112
+
> 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.
132
113
133
-
1. If you changed to a new TokenHelper file, rebuild the project.
114
+
1. If you changed to a new **TokenHelper.[cs|vb]** file, rebuild the project.
134
115
1. Republish the web application.
135
116
136
-
## Create a client secret that is valid for three years
137
-
138
-
For expired client secrets, first you must delete all of the expired secrets for a given **clientId**. You then create a new one with MSO PowerShell, wait at least 24 hours, and test the app with the new **clientId** and **ClientSecret** key.
139
-
140
-
1. Connect to MSOnline using the tenant admin user with the following markup using SharePoint Windows PowerShell.
141
-
142
-
```powershell
143
-
import-module MSOnline
144
-
$msolcred = get-credential
145
-
connect-msolservice -credential $msolcred
146
-
```
147
-
148
-
1. Get **ServicePrincipals** and keys. Printing **$keys** returns three records. You also see the **EndDate** of each key. Confirm whether your expired key appears there.
149
-
150
-
> [!NOTE]
151
-
> The **clientId** needs to match your expired **clientId**. It's recommended to delete all keys, both expired and unexpired, for this **clientId**.
1. Generate a new **ClientSecret** for this **clientID**. It uses the same **clientId** as set in the preceding step. The new **ClientSecret** is valid for three years.
0 commit comments