Skip to content

Commit 1a63838

Browse files
lw-msftlw-msft
authored
Create Set-SPOTenantPreAuthSettings.md
1 parent 7edd222 commit 1a63838

File tree

1 file changed

+301
-0
lines changed

1 file changed

+301
-0
lines changed

‎sharepoint/sharepoint-ps/sharepoint-online/Set-SPOTenantPreAuthSettings.md‎

Lines changed: 301 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,301 @@
1+
---
2+
external help file: sharepointonline.xml
3+
Module Name: Microsoft.Online.SharePoint.PowerShell
4+
online version: https://learn.microsoft.com/powershell/module/sharepoint-online/set-spotenantpreauthsettings
5+
applicable: SharePoint Online
6+
title: Set-SPOTenantPreAuthSettings
7+
schema: 2.0.0
8+
author: lw-msft
9+
ms.author: laurenwong, neilh
10+
ms.reviewer:
11+
manager: bhaveshd
12+
---
13+
14+
# Set-SPOTenantPreAuthSettings
15+
16+
## SYNOPSIS
17+
18+
Sets the configuration of pre-Authentication.
19+
20+
## SYNTAX
21+
22+
```powershell
23+
Set-SPOTenantPreAuthSettings
24+
-IsDisabled <bool> [<CommonParameters>]
25+
```
26+
27+
```powershell
28+
Set-SPOTenantPreAuthSettings
29+
-Add
30+
-Type {Allow | Deny}
31+
[-IncludedApps <string>]
32+
[-ExcludedApps <string>]
33+
[-IncludedFeatures <string>]
34+
[-ExcludedFeatures <string>]
35+
[<CommonParameters>]
36+
```
37+
38+
```powershell
39+
Set-SPOTenantPreAuthSettings
40+
-Remove
41+
-Id <string>
42+
```
43+
44+
## DESCRIPTION
45+
46+
You can use the Set-SPOTenantPreAuthSettings cmdlet to configure or disable the pre-authentication feature within SharePoint Online. The disablement can be combined with switches to support granular pre-authentication management for specific apps and features at the tenant level.
47+
48+
**What is pre-authentication?**
49+
50+
SharePoint includes self-issued tokens in URLs called pre-authentication URLs (also known as tempauth URLs) to provide temporary access to a SharePoint resource, which helps support more rich user experiences. For example, a common scenario is downloading a file using a URL that includes a token in the `tempauth` query parameter like the following:
51+
52+
`https://<tenant>.sharepoint.com/sites/samplesite/_layouts/15/download.aspx?UniqueId=<id>&tempauth=v1.ey...`
53+
54+
But this feature is currently being deprecated, so this cmdlet lets you control the use of pre-authentication in various use cases.
55+
56+
> [!NOTE]
57+
> The settings leverage an order of precedence:
58+
> 1. Deny
59+
> 2. Allow
60+
> 3. IsDisabled
61+
62+
> [!NOTE]
63+
> As the use of this cmdlet can disable functionality in your SharePoint Online Tenant, it is highly recommended to test and evaluate each change in a test tenant ahead of making changes in a production environment.
64+
65+
You must be a SharePoint Online administrator to run the cmdlet.
66+
67+
## EXAMPLES
68+
69+
### Example 1
70+
```powershell
71+
Set-SPOTenantPreAuthSettings -IsDisabled $true
72+
73+
Set-SPOTenantPreAuthSettings -Add -Type Allow -IncludedApps "029e7c27-4b9c-4f8b-ba32-b96249468d42,0ab82eba-96c7-4681-9f75-c18437e20d0e"
74+
```
75+
This example disables pre-authentication overall and adds a setting that allows two apps to use pre-authentication for all features.
76+
77+
### Example 2
78+
```powershell
79+
Set-SPOTenantPreAuthSettings -Add -Type Allow -IncludedApps "029e7c27-4b9c-4f8b-ba32-b96249468d42,0ab82eba-96c7-4681-9f75-c18437e20d0e" -ExcludedApps "" -IncludedFeatures "" -ExcludedFeatures ""
80+
```
81+
This example performs the same function as example 1 except in this case the switches for `-ExcludedApps`, `-IncludedFeatures`, and `-ExcludedFeatures` are added to the cmdlet.
82+
83+
These switches are assumed to take the default value of `""` if not used with the cmdlet and example 2 is used to demonstrate the complete set of switches only.
84+
85+
### Example 3
86+
```powershell
87+
Set-SPOTenantPreAuthSettings -Remove -Id "12345678-1234-1234-1234-123456789012"
88+
```
89+
This example will remove an existing item from the current list of items. The remove switch can remove allow or deny entries from the list.
90+
91+
### Example 4
92+
```powershell
93+
Set-SPOTenantPreAuthSettings -IsDisabled $true
94+
95+
Set-SPOTenantPreAuthSettings -Add -Type Allow -ExcludedApps "029e7c27-4b9c-4f8b-ba32-b96249468d42" -ExcludedFeatures "Download,WebRenderingEmbed"
96+
```
97+
This example disables pre-authentication overall and allows all apps apart from one to use pre-authentication for all features except for Download and WebRenderingEmbed.
98+
99+
In this case, the app 029e7c27-4b9c-4f8b-ba32-b96249468d42 will always be denied from using pre-authentication since it is excluded from the allow list setting. Any other app will be allowed to use pre-authentication for any feature apart from Download and WebRenderingEmbed.
100+
101+
### Example 5
102+
```powershell
103+
Set-SPOTenantPreAuthSettings -IsDisabled $true
104+
105+
Set-SPOTenantPreAuthSettings -Add -Type Allow -IncludedApps "029e7c27-4b9c-4f8b-ba32-b96249468d42" -IncludedFeatures "OfficeOnline,WebRenderingEmbed,Download"
106+
107+
Set-SPOTenantPreAuthSettings -Add -Type Deny -IncludedApps "029e7c27-4b9c-4f8b-ba32-b96249468d42,0ab82eba-96c7-4681-9f75-c18437e20d0e"
108+
```
109+
This example disables pre-authentication overall but contains an overlap between the settings in the Allow list and Deny list. It first allows an app to use pre-authentication for the OfficeOnline, WebRenderingEmbed, and Download features. But in the final execution of the cmdlet, it denies the same app from using pre-authentication for all features.
110+
111+
In this case, the app 029e7c27-4b9c-4f8b-ba32-b96249468d42 would not be allowed to use pre-authentication for any of the allow-listed features despite having the setting. This is because the Deny list takes precedence over the Allow list.
112+
113+
### Example 6
114+
```powershell
115+
Set-SPOTenantPreAuthSettings -IsDisabled $false
116+
117+
Set-SPOTenantPreAuthSettings -Add -Type Deny -IncludedApps "Empty"
118+
```
119+
This example enables pre-authentication overall and denies requests that are not coming from an app (e.g. requests coming via a browser) from using pre-authentication for all features.
120+
121+
> [!NOTE]
122+
> The `"Empty"` value for `-IncludedApps` or `-ExcludedApps` is different from an empty string `""`:
123+
> - `"Empty"` represents any requests that are not coming from an app (e.g. direct requests from the browser) and will not have an app ID associated with it
124+
> - `""` can mean several things:
125+
> - If you have `–IncludedApps "" -ExcludedApps ""`, it means that the setting applies to all
126+
> - If you have `–IncludedApps "" -ExcludedApps "<appid>"`, it means that the setting applies to all apps apart from <appids>.
127+
> - If you have `–IncludedApps "<appids>" and -ExcludedApps ""`, it means that the setting only applies to <appids>
128+
> - You cannot have a setting with `–IncludedApps "<appids>" –ExcludedApps "<appids>"`
129+
130+
## PARAMETERS
131+
132+
### -IsDisabled
133+
134+
This parameter allows the administrator to toggle pre-authentication for all apps and features to be either enabled or disabled.
135+
136+
PARAMVALUE: True | False
137+
138+
```yaml
139+
Type: Boolean
140+
Parameter Sets: IsDisabled
141+
Applicable: SharePoint Online
142+
Required: True
143+
Position: Named
144+
Default value: False
145+
Accept pipeline input: False
146+
Accept wildcard characters: False
147+
```
148+
149+
### -Remove
150+
151+
This parameter specifies that the operation of the cmdlet is to Remove a setting from the SPOTenantPreAuthSettings configuration.
152+
153+
```yaml
154+
Type: SwitchParameter
155+
Parameter Sets: Remove
156+
Applicable: SharePoint Online
157+
Required: True
158+
Position: Named
159+
Default value: None
160+
Accept pipeline input: False
161+
Accept wildcard characters: False
162+
```
163+
164+
### -Id
165+
166+
This parameter identifies the configuration setting to remove from the SPOTenantPreAuthSettings configuration set. It is only required with the -Remove parameter.
167+
168+
```yaml
169+
Type: String
170+
Parameter Sets: Remove
171+
Applicable: SharePoint Online
172+
Required: True
173+
Position: Named
174+
Default value: None
175+
Accept pipeline input: False
176+
Accept wildcard characters: False
177+
```
178+
179+
### -Add
180+
181+
This parameter specifies that the operation of the cmdlet is to Add a setting to the SPOTenantPreAuthSettings configuration.
182+
183+
```yaml
184+
Type: SwitchParameter
185+
Parameter Sets: Add
186+
Applicable: SharePoint Online
187+
Required: True
188+
Position: Named
189+
Default value: None
190+
Accept pipeline input: False
191+
Accept wildcard characters: False
192+
```
193+
194+
### -Type
195+
196+
This parameter indicates whether the cmdlet is interacting with the Allow list or the Deny list within the SPOTenantPreAuthSettings.
197+
198+
PARAMVALUE: Allow | Deny
199+
200+
```yaml
201+
Type: ListType
202+
Parameter Sets: Add
203+
Applicable: SharePoint Online
204+
Required: True
205+
Position: Named
206+
Default value: None
207+
Accept pipeline input: False
208+
Accept wildcard characters: False
209+
```
210+
211+
### -IncludedApps
212+
213+
This parameter value contains the app ids to configure within the SPOTenantPreAuthSettings `-IncludedApps` scope.
214+
215+
PARAMVALUE: "Empty", "", or a comma-separated list of app IDs
216+
217+
```yaml
218+
Type: String
219+
Parameter Sets: Add
220+
Applicable: SharePoint Online
221+
Required: False
222+
Position: Named
223+
Default value: ""
224+
Accept pipeline input: False
225+
Accept wildcard characters: False
226+
```
227+
228+
### -ExcludedApps
229+
230+
This parameter value contains the apps ids to configure within the SPOTenantPreAuthSettings `-ExcludedApps` scope.
231+
232+
PARAMVALUE: "Empty", "", or a comma-separated list of app IDs
233+
234+
```yaml
235+
Type: String
236+
Parameter Sets: Add
237+
Applicable: SharePoint Online
238+
Required: False
239+
Position: Named
240+
Default value: ""
241+
Accept pipeline input: False
242+
Accept wildcard characters: False
243+
```
244+
245+
### -IncludedFeatures
246+
247+
This parameter value contains the feature names to configure within the SPOTenantPreAuthSettings `-IncludedFeatures` scope.
248+
249+
PARAMVALUE: "Empty", "", or a comma-separated list of app IDs
250+
251+
```yaml
252+
Type: String
253+
Parameter Sets: Add
254+
Applicable: SharePoint Online
255+
Required: False
256+
Position: Named
257+
Default value: ""
258+
Accept pipeline input: False
259+
Accept wildcard characters: False
260+
```
261+
262+
### -ExcludedFeatures
263+
264+
This parameter value contains the feature names to configure within the SPOTenantPreAuthSettings `-ExcludedFeatures` scope.
265+
266+
PARAMVALUE: "Empty", "", or a comma-separated list of app IDs
267+
268+
```yaml
269+
Type: String
270+
Parameter Sets: Add
271+
Applicable: SharePoint Online
272+
Required: False
273+
Position: Named
274+
Default value: ""
275+
Accept pipeline input: False
276+
Accept wildcard characters: False
277+
```
278+
279+
### Feature Names
280+
281+
| Feature name | Description | Additional Information |
282+
|----------------------|--------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
283+
| DataFormWebpart | Scenarios involved with DataFormWebParts to display/interact with SharePoint data. | [DataFormWebPart Properties (Microsoft.SharePoint.WebPartPages) - Microsoft Learn ](https://learn.microsoft.com/en-us/previous-versions/office/developer/sharepoint-2010/ms369119(v=office.14)) |
284+
| Download | Scenarios for getting pre-authenticated download URLs. 3rd party application and some 1st party applications may be broken. | [OAuth 2.0 and OpenID Connect protocols on the Microsoft identity platform - Microsoft Learn ](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols) |
285+
| OfficeOnline | Office on the web scenarios. Performance might be impacted. | |
286+
| SearchPreview | Scenarios involved in generating previews/thumbnails/conversions for search query results. Experience might be broken. | |
287+
| SharePointConnector | Scenarios involved with SharePoint Connectors | [SharePoint Connectors - Microsoft Learn](https://learn.microsoft.com/en-us/connectors/sharepointonline/) |
288+
| Thumbnail | Scenarios for getting pre-authenticated thumbnail generation URLs. | |
289+
| UploadSession | Scenarios for creating upload sessions. 3rd party application and some 1st party applications may be broken | |
290+
| Video | Playing Video hosted on SharePoint might be broken | |
291+
| WebRendering | Scenarios for rendering previews of files in browser. | |
292+
| WebRenderingEmbed | Embed SharePoint files in another application. 3rd party application and some 1st party applications may be broken | [Embed Web Part](https://support.microsoft.com/en-us/office/add-content-to-your-page-using-the-embed-web-part-721f3b2f-437f-45ef-ac4e-df29dba74de8) |
293+
| Whiteboard | Teams integration with Whiteboard app will be broken for anonymous and guest users. | [Use Whiteboard in a Teams meeting - Microsoft Support](https://support.microsoft.com/en-us/office/use-whiteboard-in-a-teams-meeting-26f87802-b37f-4af0-806d-af79fbfb8ae6) |
294+
295+
### CommonParameters
296+
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
297+
298+
## RELATED LINKS
299+
300+
- [Get-SPOTenantPreAuthSettings](Get-SPOTenantPreAuthSettings.md)
301+
- [Clear-SPOTenantPreAuthSettings](Clear-SPOTenantPreAuthSettings.md)

0 commit comments

Comments
 (0)