Skip to content

Commit efb8473

Browse files
pepelsbeychrisdavidmills
pepelsbey
and
chrisdavidmills
authored
Document RTCIdentityAssertion idp/name and RTCPeerConnection.idpLoginUrl (mdn#43735)
* Document RTCIdentityAssertion idp/name and RTCPeerConnection.idpLoginUrl * Apply suggestions from code review Co-authored-by: Chris Mills <chrisdavidmills@gmail.com> --------- Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>
1 parent 8c4ef12 commit efb8473

File tree

5 files changed

+200
-2
lines changed

5 files changed

+200
-2
lines changed

‎files/en-us/web/api/rtcidentityassertion/idp/index.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: "RTCIdentityAssertion: idp property"
3+
short-title: idp
4+
slug: Web/API/RTCIdentityAssertion/idp
5+
page-type: web-api-instance-property
6+
status:
7+
- experimental
8+
browser-compat: api.RTCIdentityAssertion.idp
9+
---
10+
11+
{{APIRef("WebRTC")}}{{SeeCompatTable}}
12+
13+
The **`idp`** property of the {{domxref("RTCIdentityAssertion")}} interface indicates the domain name of the {{Glossary("Identity provider", "identity provider")}} (IdP) that validated the identity assertion (a verified claim of the remote peer's identity).
14+
15+
## Value
16+
17+
A string containing the domain name of the identity provider that validated this identity.
18+
19+
## Examples
20+
21+
### Displaying the identity provider domain
22+
23+
In this example, the {{domxref("RTCPeerConnection.peerIdentity")}} promise resolves with an {{domxref("RTCIdentityAssertion")}} whose `idp` property is logged to the console.
24+
25+
```js
26+
const pc = new RTCPeerConnection();
27+
28+
// …
29+
30+
async function getIdentityProvider() {
31+
try {
32+
const identity = await pc.peerIdentity;
33+
console.log(`Identity provider: ${identity.idp}`);
34+
} catch (err) {
35+
console.error("Failed to get peer identity:", err);
36+
}
37+
}
38+
39+
getIdentityProvider();
40+
```
41+
42+
## Specifications
43+
44+
{{Specifications}}
45+
46+
## Browser compatibility
47+
48+
{{Compat}}
49+
50+
## See also
51+
52+
- {{domxref("RTCIdentityAssertion.name")}}
53+
- {{domxref("RTCPeerConnection.peerIdentity")}}
54+
- [WebRTC API](/en-US/docs/Web/API/WebRTC_API)

‎files/en-us/web/api/rtcidentityassertion/index.md‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,33 @@ The **`RTCIdentityAssertion`** interface of the [WebRTC API](/en-US/docs/Web/API
1414
## Instance properties
1515

1616
- {{domxref("RTCIdentityAssertion.idp")}} {{Experimental_Inline}}
17-
- : Indicates the provider of the identity assertion.
17+
- : Indicates the domain name of the {{Glossary("Identity provider", "identity provider")}} (IdP) that validated the identity.
1818
- {{domxref("RTCIdentityAssertion.name")}} {{Experimental_Inline}}
19-
- : Indicates the name of the identity assertion provider.
19+
- : Indicates the verified peer identity as a string in an email address-like format.
20+
21+
## Examples
22+
23+
### Accessing the remote peer's identity
24+
25+
In this example, a function asynchronously waits for the remote peer's identity to be verified via {{domxref("RTCPeerConnection.peerIdentity")}}, then logs the {{Glossary("Identity provider", "identity provider")}} domain and the peer's identity name.
26+
27+
```js
28+
const pc = new RTCPeerConnection();
29+
30+
// …
31+
32+
async function logPeerIdentity() {
33+
try {
34+
const identity = await pc.peerIdentity;
35+
console.log(`IdP domain: ${identity.idp}`);
36+
console.log(`Peer name: ${identity.name}`);
37+
} catch (err) {
38+
console.error("Could not verify peer identity:", err);
39+
}
40+
}
41+
42+
logPeerIdentity();
43+
```
2044

2145
## Specifications
2246

@@ -25,3 +49,9 @@ The **`RTCIdentityAssertion`** interface of the [WebRTC API](/en-US/docs/Web/API
2549
## Browser compatibility
2650

2751
{{Compat}}
52+
53+
## See also
54+
55+
- {{domxref("RTCPeerConnection.peerIdentity")}}
56+
- {{domxref("RTCPeerConnection.getIdentityAssertion()")}}
57+
- [WebRTC API](/en-US/docs/Web/API/WebRTC_API)

‎files/en-us/web/api/rtcidentityassertion/name/index.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: "RTCIdentityAssertion: name property"
3+
short-title: name
4+
slug: Web/API/RTCIdentityAssertion/name
5+
page-type: web-api-instance-property
6+
status:
7+
- experimental
8+
browser-compat: api.RTCIdentityAssertion.name
9+
---
10+
11+
{{APIRef("WebRTC")}}{{SeeCompatTable}}
12+
13+
The **`name`** property of the {{domxref("RTCIdentityAssertion")}} interface indicates the verified peer identity. It is a string in an email address-like format (for example, `user@example.com`), as defined by {{RFC(5322)}}.
14+
15+
## Value
16+
17+
A string containing the verified peer identity in an {{RFC(5322)}} email address-like format (for example, `alice@identity.example.com`).
18+
19+
## Examples
20+
21+
### Logging the verified peer identity name
22+
23+
In this example, the {{domxref("RTCPeerConnection.peerIdentity")}} promise is awaited to obtain the identity assertion, and then the peer's verified identity name is logged.
24+
25+
```js
26+
const pc = new RTCPeerConnection();
27+
28+
// …
29+
30+
async function logPeerName() {
31+
try {
32+
const identity = await pc.peerIdentity;
33+
console.log(`Peer identity: ${identity.name}`);
34+
} catch (err) {
35+
console.error("Could not verify peer identity:", err);
36+
}
37+
}
38+
39+
logPeerName();
40+
```
41+
42+
## Specifications
43+
44+
{{Specifications}}
45+
46+
## Browser compatibility
47+
48+
{{Compat}}
49+
50+
## See also
51+
52+
- {{domxref("RTCIdentityAssertion.idp")}}
53+
- {{domxref("RTCPeerConnection.peerIdentity")}}
54+
- [WebRTC API](/en-US/docs/Web/API/WebRTC_API)

‎files/en-us/web/api/rtcpeerconnection/idploginurl/index.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: "RTCPeerConnection: idpLoginUrl property"
3+
short-title: idpLoginUrl
4+
slug: Web/API/RTCPeerConnection/idpLoginUrl
5+
page-type: web-api-instance-property
6+
browser-compat: api.RTCPeerConnection.idpLoginUrl
7+
---
8+
9+
{{APIRef("WebRTC")}}
10+
11+
The **`idpLoginUrl`** read-only property of the {{domxref("RTCPeerConnection")}} interface returns a string containing the URL endpoint the application can open to log users in to the {{Glossary("Identity provider", "identity provider")}} (IdP). This value is `null` until the IdP indicates that login is needed.
12+
13+
When a call to {{domxref("RTCPeerConnection.getIdentityAssertion()")}} fails because the IdP requires user authentication, the resulting promise is rejected with an {{domxref("RTCError")}} whose {{domxref("RTCError.errorDetail", "errorDetail")}} is `"idp-need-login"`. The browser then sets this property to the login URL provided by the IdP. The application can open this URL (for example, in a pop-up window or `<iframe>`) to allow the user to complete the login process before retrying the identity assertion.
14+
15+
## Value
16+
17+
A string containing the IdP login URL, or `null` if no login is needed.
18+
19+
## Examples
20+
21+
### Handling an IdP login requirement
22+
23+
In this example, the application attempts to gather an identity assertion. If the IdP rejects the attempt because the user is not authenticated, the application opens the login URL provided in `idpLoginUrl`.
24+
25+
```js
26+
const pc = new RTCPeerConnection();
27+
pc.setIdentityProvider("login.example.com");
28+
29+
pc.getIdentityAssertion().catch((error) => {
30+
if (pc.idpLoginUrl) {
31+
console.log(`IdP login required at: ${pc.idpLoginUrl}`);
32+
// Open the login page in a popup window
33+
const loginWindow = window.open(
34+
pc.idpLoginUrl,
35+
"idp-login",
36+
"width=500,height=600",
37+
);
38+
} else {
39+
console.error("Identity assertion failed:", error);
40+
}
41+
});
42+
```
43+
44+
## Specifications
45+
46+
{{Specifications}}
47+
48+
## Browser compatibility
49+
50+
{{Compat}}
51+
52+
## See also
53+
54+
- [WebRTC API](/en-US/docs/Web/API/WebRTC_API)
55+
- {{domxref("RTCPeerConnection.peerIdentity")}}
56+
- {{domxref("RTCPeerConnection.getIdentityAssertion()")}}
57+
- {{domxref("RTCPeerConnection.setIdentityProvider()")}}
58+
- {{domxref("RTCIdentityAssertion")}}

‎files/en-us/web/api/rtcpeerconnection/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ _Also inherits properties from {{DOMxRef("EventTarget")}}._
3838
- : Returns a string that describes connection's ICE gathering state.
3939
This lets you detect, for example, when collection of ICE candidates has finished.
4040
Possible values are: `new`, `gathering`, or `complete`.
41+
- {{DOMxRef("RTCPeerConnection.idpLoginUrl", "idpLoginUrl")}} {{ReadOnlyInline}}
42+
- : Returns a string containing the endpoint the application can navigate to, to log users in to the {{Glossary("Identity provider", "identity provider")}} (IdP). May be `null` if no login is needed.
4143
- {{DOMxRef("RTCPeerConnection.localDescription", "localDescription")}} {{ReadOnlyInline}}
4244
- : Returns an {{DOMxRef("RTCSessionDescription")}}
4345
describing the session for the local end of the connection.

0 commit comments

Comments
 (0)