-
Notifications
You must be signed in to change notification settings - Fork 7
/
authentication.yml
267 lines (233 loc) · 10.3 KB
/
authentication.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
### YamlMime:TSPackage
uid: '@microsoft/teams-js.authentication'
name: authentication
summary: ''
type: module
typeAliases:
- '@microsoft/teams-js.authentication.AuthenticateParameters'
- '@microsoft/teams-js.authentication.AuthTokenRequest'
interfaces:
- '@microsoft/teams-js.authentication.AuthenticatePopUpParameters'
- '@microsoft/teams-js.authentication.AuthTokenRequestParameters'
- '@microsoft/teams-js.authentication.LegacyCallBacks'
package: '@microsoft/teams-js'
functions:
- name: authenticate(AuthenticateParameters)
uid: '@microsoft/teams-js.authentication.authenticate_1'
package: '@microsoft/teams-js'
summary: ''
remarks: ''
isDeprecated: true
customDeprecatedMessage: >-
As of TeamsJS v2.0.0, please use
[authentication.authenticate(authenticateParameters:
AuthenticatePopUpParameters):
Promise\<string\>](xref:@microsoft/teams-js.authentication.authenticate_1)
instead.
The documentation for [authentication.authenticate(authenticateParameters:
AuthenticatePopUpParameters):
Promise\<string\>](xref:@microsoft/teams-js.authentication.authenticate_1)
applies
to this function.
The one difference is that instead of the result being returned via the
`Promise`, the result is returned to the callback functions provided in
the
`authenticateParameters` parameter.
syntax:
content: 'function authenticate(authenticateParameters?: AuthenticateParameters)'
parameters:
- id: authenticateParameters
type: >-
<xref
uid="@microsoft/teams-js.authentication.AuthenticateParameters" />
description: >-
Parameters describing the authentication window used for executing
the authentication flow and callbacks used for indicating the result
- name: authenticate(AuthenticatePopUpParameters)
uid: '@microsoft/teams-js.authentication.authenticate'
package: '@microsoft/teams-js'
summary: >-
Initiates an authentication flow which requires a new window.
There are two primary uses for this function:
1. When your app needs to authenticate using a 3rd-party identity provider
(not Microsoft Entra ID)
2. When your app needs to show authentication UI that is blocked from
being shown in an iframe (e.g., Microsoft Entra consent prompts)
For more details, see [Enable authentication using third-party OAuth
provider](https://learn.microsoft.com/microsoftteams/platform/tabs/how-to/authentication/auth-flow-tab)
This function is *not* needed for "standard" Microsoft Entra SSO usage.
Using
[getAuthToken](xref:@microsoft/teams-js.authentication.getAuthToken_1) is
usually sufficient in that case. For more, see
[Enable SSO for tab
apps](https://learn.microsoft.com/microsoftteams/platform/tabs/how-to/authentication/tab-sso-overview))
remarks: >-
The authentication flow must start and end from the same domain, otherwise
success and failure messages won't be returned to the window that
initiated the call.
The [Teams authentication
flow](https://learn.microsoft.com/microsoftteams/platform/tabs/how-to/authentication/auth-flow-tab)
starts and ends at an endpoint on
your own service (with a redirect round-trip to the 3rd party identity
provider in the middle).
isDeprecated: false
syntax:
content: >-
function authenticate(authenticateParameters:
AuthenticatePopUpParameters): Promise<string>
parameters:
- id: authenticateParameters
type: >-
<xref
uid="@microsoft/teams-js.authentication.AuthenticatePopUpParameters"
/>
description: >-
Parameters describing the authentication window used for executing
the authentication flow
return:
description: >-
`Promise` that will be fulfilled with the result from the
authentication pop-up, if successful. The string in this result is
provided in the parameter
passed by your app when it calls
[authentication.notifySuccess(result?: string):
void](xref:@microsoft/teams-js.authentication.notifySuccess) in the
pop-up window after returning from the identity provider redirect.
type: Promise<string>
- name: getAuthToken(AuthTokenRequest)
uid: '@microsoft/teams-js.authentication.getAuthToken_1'
package: '@microsoft/teams-js'
summary: ''
remarks: ''
isDeprecated: true
customDeprecatedMessage: >-
As of TeamsJS v2.0.0, please use
[authentication.getAuthToken(authTokenRequest:
AuthTokenRequestParameters):
Promise\<string\>](xref:@microsoft/teams-js.authentication.getAuthToken_1)
instead.
The documentation [authentication.getAuthToken(authTokenRequest:
AuthTokenRequestParameters):
Promise\<string\>](xref:@microsoft/teams-js.authentication.getAuthToken_1)
applies to this
function as well. The one difference when using this function is that the
result is provided in the callbacks in the `authTokenRequest` parameter
instead of as a `Promise`.
syntax:
content: 'function getAuthToken(authTokenRequest?: AuthTokenRequest)'
parameters:
- id: authTokenRequest
type: <xref uid="@microsoft/teams-js.authentication.AuthTokenRequest" />
description: |-
An optional set of values that configure the token request.
It contains callbacks to call in case of success/failure
- name: getAuthToken(AuthTokenRequestParameters)
uid: '@microsoft/teams-js.authentication.getAuthToken'
package: '@microsoft/teams-js'
summary: >-
Requests an Microsoft Entra token to be issued on behalf of your app in an
SSO flow.
The token is acquired from the cache if it is not expired. Otherwise a
request is sent to Microsoft Entra to
obtain a new token.
This function is used to enable SSO scenarios. See [Enable SSO for tab
apps](https://learn.microsoft.com/microsoftteams/platform/tabs/how-to/authentication/tab-sso-overview)
for more details.
remarks: ''
isDeprecated: false
syntax:
content: >-
function getAuthToken(authTokenRequest?: AuthTokenRequestParameters):
Promise<string>
parameters:
- id: authTokenRequest
type: >-
<xref
uid="@microsoft/teams-js.authentication.AuthTokenRequestParameters"
/>
description: An optional set of values that configure the token request.
return:
description: '`Promise` that will be resolved with the token, if successful.'
type: Promise<string>
- name: notifyFailure(string)
uid: '@microsoft/teams-js.authentication.notifyFailure'
package: '@microsoft/teams-js'
summary: >-
When using [authentication.authenticate(authenticateParameters:
AuthenticatePopUpParameters):
Promise\<string\>](xref:@microsoft/teams-js.authentication.authenticate_1),
the
window that was opened to execute the authentication flow should call this
method after authentiction to notify the caller of
[authentication.authenticate(authenticateParameters:
AuthenticatePopUpParameters):
Promise\<string\>](xref:@microsoft/teams-js.authentication.authenticate_1)
that the
authentication request failed.
remarks: |-
This function is usable only on the authentication window.
This call causes the authentication window to be closed.
isDeprecated: false
syntax:
content: 'function notifyFailure(result?: string)'
parameters:
- id: result
type: string
description: >-
Specifies a result for the authentication. If specified, the frame
that initiated the authentication pop-up receives
this value in its callback or via the `Promise` return value
- name: notifySuccess(string)
uid: '@microsoft/teams-js.authentication.notifySuccess'
package: '@microsoft/teams-js'
summary: >-
When using [authentication.authenticate(authenticateParameters:
AuthenticatePopUpParameters):
Promise\<string\>](xref:@microsoft/teams-js.authentication.authenticate_1),
the
window that was opened to execute the authentication flow should call this
method after authentiction to notify the caller of
[authentication.authenticate(authenticateParameters:
AuthenticatePopUpParameters):
Promise\<string\>](xref:@microsoft/teams-js.authentication.authenticate_1)
that the
authentication request was successful.
remarks: |-
This function is usable only from the authentication window.
This call causes the authentication window to be closed.
isDeprecated: false
syntax:
content: 'function notifySuccess(result?: string)'
parameters:
- id: result
type: string
description: >-
Specifies a result for the authentication. If specified, the frame
that initiated the authentication pop-up receives
this value in its callback or via the `Promise` return value
- name: registerAuthenticationHandlers(AuthenticateParameters)
uid: '@microsoft/teams-js.authentication.registerAuthenticationHandlers'
package: '@microsoft/teams-js'
summary: ''
remarks: ''
isDeprecated: true
customDeprecatedMessage: >-
As of TeamsJS v2.0.0, this function has been deprecated in favor of a
Promise-based pattern using
[authentication.authenticate(authenticateParameters:
AuthenticatePopUpParameters):
Promise\<string\>](xref:@microsoft/teams-js.authentication.authenticate_1)
Registers handlers to be called with the result of an authentication flow
triggered using [authentication.authenticate(authenticateParameters?:
AuthenticateParameters):
void](xref:@microsoft/teams-js.authentication.authenticate_1)
syntax:
content: >-
function registerAuthenticationHandlers(authenticateParameters:
AuthenticateParameters)
parameters:
- id: authenticateParameters
type: >-
<xref
uid="@microsoft/teams-js.authentication.AuthenticateParameters" />
description: Configuration for authentication flow pop-up result communication