Movatterモバイル変換

This document defines a set of ECMAScript APIs in WebIDL to allow and application using WebRTC to assert an identity, and to mark media streams as only viewable by another identity. This specification is being developed in conjunction with a protocol specification developed by the IETF RTCWEB group.

While the specification is feature complete and is expected to be stable, there are also a number ofknown substantive issues on the specification that will be addressed during the Candidate Recommendation period based on implementation experience feedback.

It might also evolve based on feedback gathered as itsassociated test suite evolves. This test suite will be used to build animplementation report of the API.

To go into Proposed Recommendation status, the group expects to demonstrate implementation of each feature in at least two deployed browsers, and at least one implementation of each optional feature. Mandatory feature with only one implementation may be marked as optional in a revised Candidate Recommendation where applicable.

Introduction

This document specifies APIs used for identity in WebRTC.

This specification is being developed in conjunction with a protocol specification developed by theIETF RTCWEB group and an API specification to get access to local media devices [[GETUSERMEDIA]]. An overview of the system can be found in [[RTCWEB-OVERVIEW]] and [[RTCWEB-SECURITY]].

This specification defines conformance criteria that apply to a single product: theuser agent that implements the interfaces that it contains.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as this specification uses that specification and terminology.

Terminology

The termmedia description is defined in [[!RFC4566]].

The termmedia transport is defined in [[!RFC7656]].

The termgeneration is defined in [[!TRICKLE-ICE]] Section 2.

The termssettled used in the context of Promises are defined in [[ECMASCRIPT-6.0]].

The termsbundle,bundle-only andbundle-policy are defined in [[!JSEP]].

TheOAuth Client andAuthorization Server roles are defined in [[!RFC6749]] Section 1.1.

Identity Provider Interaction

WebRTC offers and answers (and hence the channels established by {{RTCPeerConnection}} objects) can be authenticated by using a web-based Identity Provider (IdP). The idea is that the entity sending an offer or answer acts as the Authenticating Party (AP) and obtains an identity assertion from the IdP which it attaches to the session description. The consumer of the session description (i.e., the {{RTCPeerConnection}} on whichsetRemoteDescription is called) acts as the Relying Party (RP) and verifies the assertion.

The interaction with the IdP is designed to decouple the browser from any particular identity provider; the browser need only know how to load the IdP's JavaScript, the location of which is determined by the IdP's identity, and the generic interface to generating and validating assertions. The IdP provides whatever logic is necessary to bridge the generic protocol to the IdP's specific requirements. Thus, a single browser can support any number of identity protocols, including being forward compatible with IdPs which did not exist at the time the browser was written.

[Global=(Worker,RTCIdentityProvider), Exposed=RTCIdentityProvider]interface RTCIdentityProviderGlobalScope : WorkerGlobalScope {    readonly        attribute RTCIdentityProviderRegistrar rtcIdentityProvider;};

Registering an IdP Proxy

An IdP proxy implements theRTCIdentityProvider methods, which are the means by which the user agent is able to request that an identity assertion be generated or validated.

Once instantiated, the IdP script is executed. The IdP MUST call theregister() function on theRTCIdentityProviderRegistrar instance during script execution. If an IdP is not registered during this script execution, the user agent cannot use the IdP proxy and MUST fail any future attempt to interact with the IdP.

[Exposed=RTCIdentityProvider]interface RTCIdentityProviderRegistrar {    undefined register (RTCIdentityProvider idp);};

dictionary RTCIdentityProvider {    required GenerateAssertionCallback generateAssertion;    required ValidateAssertionCallback validateAssertion;};

          callback GenerateAssertionCallback = Promise<RTCIdentityAssertionResult>          (DOMString contents, DOMString origin, optional RTCIdentityProviderOptions options = {});

          callback ValidateAssertionCallback = Promise<RTCIdentityValidationResult>          (DOMString assertion, DOMString origin);

dictionary RTCIdentityAssertionResult {    required RTCIdentityProviderDetails idp;    required DOMString                  assertion;};

dictionary RTCIdentityProviderDetails {    required DOMString domain;             DOMString protocol = "default";};

dictionary RTCIdentityValidationResult {    required DOMString identity;    required DOMString contents;};

Requesting Identity Assertions

The identity assertion request process is triggered by a call tocreateOffer,createAnswer, orgetIdentityAssertion. When these calls are invoked and an identity provider has been set, the following steps are executed:

1. TheRTCPeerConnection instantiates an IdP as described inIdentity Provider Selection andRegistering an IdP Proxy. If the IdP cannot be loaded, instantiated, or the IdP proxy is not registered, this process fails.

2. If theRTCPeerConnection was not constructed with a set of certificates, and one has not yet been generated, wait for it to be generated.

3. TheRTCPeerConnection invokes thegenerateAssertion method on theRTCIdentityProvider methods registered by the IdP.

   TheRTCPeerConnection generates thecontents parameter to this method as described in [[!RTCWEB-SECURITY-ARCH]]. The value ofcontents includes the fingerprint of the certificate that was selected or generated during the construction of theRTCPeerConnection. Theorigin parameter contains the origin of the script that calls theRTCPeerConnection method that triggers this behavior. TheusernameHint value is the same value that is provided tosetIdentityProvider, if any such value was provided.

4. The IdP proxy returns a Promise to theRTCPeerConnection. The IdP proxy is expected to generate the identity assertion asynchronously.

   If the user has been authenticated by the IdP, and the IdP is able to generate an identity assertion, the IdPresolves the promise with an identity assertion in the form of anRTCIdentityAssertionResult.

   This step depends entirely on the IdP. The methods by which an IdP authenticates users or generates assertions is not specified, though they could involve interacting with the IdP server or other servers.

5. If the IdP proxy produces an error or returns a promise that does notresolve to a validRTCIdentityAssertionResult (see), then assertion generation fails.

6. TheRTCPeerConnection MAY store the identity assertion for use with future offers or answers. If a fresh identity assertion is needed for any reason, applications can create a newRTCPeerConnection.

7. If the identity request was triggered by acreateOffer() orcreateAnswer(), then the assertion is converted to a JSON string, base64-encoded and inserted into ana=identity attribute in the session description.

If assertion generation fails, then the promise for the corresponding function call is [= reject | rejected =] with a newly [= exception/created =]OperationError.

Verifying Identity Assertions

Identity assertion validation happens when {{RTCPeerConnection/setRemoteDescription()}} is invoked on {{RTCPeerConnection}}. The process runs asynchronously, meaning that validation of an identity assertion might not block the completion ofsetRemoteDescription.

The identity assertion request process involves the following asynchronous steps:

1. TheRTCPeerConnection awaits any prior identity validation. Only one identity validation can run at a time for anRTCPeerConnection. This can happen because the resolution ofsetRemoteDescription is not blocked by identity validation unless there is atarget peer identity.

2. TheRTCPeerConnection loads the identity assertion from the session description and decodes the base64 value, then parses the resulting JSON. Theidp parameter of the resulting dictionary contains adomain and an optionalprotocol value that identifies the IdP, as described in [[!RTCWEB-SECURITY-ARCH]].

3. If the identity assertion is malformed, or ifprotocol includes the character'/' or'\', this process fails.

4. TheRTCPeerConnection instantiates the identified IdP as described in and. If the IdP cannot be loaded, instantiated or the IdP proxy is not registered, this process fails.

5. TheRTCPeerConnection invokes thevalidateAssertion method registered by the IdP.

   Theassertion parameter is taken from the decoded identity assertion. Theorigin parameter contains the origin of the script that calls theRTCPeerConnection method that triggers this behavior.

6. The IdP proxy returns a promise and performs the validation process asynchronously.

   The IdP proxy verifies the identity assertion using whatever means necessary. Depending on the authentication protocol this could involve interacting with the IdP server.

7. If the IdP proxy produces an error or returns a promise that does notresolve to a validRTCIdentityValidationResult (see), then identity validation fails.

8. Once the assertion is successfully verified, the IdP proxyresolves the promise with anRTCIdentityValidationResult containing the validated identity and the original contents that are the payload of the assertion.

9. TheRTCPeerConnection decodes thecontents and validates that it contains a fingerprint value for everya=fingerprint attribute in the session description. This ensures that the certificate used by the remote peer for communications is covered by the identity assertion.

   Auser agent is required to fail to communicate with peers that offer a certificate that doesn't match ana=fingerprint line in the negotiated session description.

   The user agent decodescontents using the format described in [[!RTCWEB-SECURITY-ARCH]]. However the IdP MUST treatcontents as opaque and return the same string to allow for future extensions.

10. TheRTCPeerConnection validates that the domain portion of the identity matches the domain of the IdP as described in [[!RTCWEB-SECURITY-ARCH]]. If this check fails then the identity validation fails.

11. TheRTCPeerConnection resolves thepeerIdentity attribute with a new instance ofRTCIdentityAssertion that includes the IdP domain and peer identity.

12. Theuser agent MAY display identity information to a user in its UI. Any user identity information that is displayed in this fashion MUST use a mechanism that cannot be spoofed by content.

If identity validation fails, thepeerIdentity promise is [= reject | rejected =] with a newly [= exception/created =]OperationError if it is notsettled. Then, if there is notarget peer identity, setpeerIdentity to a new unresolved promise. This permits the use of renegotiation (or a subsequent answer, if the session description was a provisional answer) to resolve or reject the identity.

If identity validation fails and there is atarget peer identity for theRTCPeerConnection, the promise returned bysetRemoteDescription is [= reject | rejected =] with the sameDOMException.

IdP Error Handling

Errors in IdP processing will - in most cases - result in the failure of the procedure that invoked the IdP proxy. This will result in the [= reject | rejection =] of the promise returned by {{RTCPeerConnection/getIdentityAssertion()}}, {{RTCPeerConnection/createOffer()}}, or {{RTCPeerConnection/createAnswer()}}. An IdP proxy error causes a {{RTCPeerConnection/setRemoteDescription()}} promise to be [= reject | rejected =] if there is atarget peer identity; IdP errors in calls to {{RTCPeerConnection/setRemoteDescription()}} where there is notarget peer identity cause the {{RTCPeerConnection/peerIdentity}} promise to be [= reject | rejected =] instead.

If an error occurs these promises are [= reject | rejected =] with an {{RTCError}} if an error occurs in interacting with the IdP proxy. The following scenarios result in errors:

• AnRTCPeerConnection might be configured with an identity provider, but loading of the IdP URI fails. Any procedure that attempts to invoke such an identity provider and cannot load the URI fails with an {{RTCError}} witherrorDetail set to "idp-load-failure" and the httpRequestStatusCode attribute of the error set to the HTTP status code of the response.

• If the IdP loads fails due to the TLS certificate used for the HTTPS connection not being trusted, it fails with an {{RTCError}} witherrorDetail set to "idp-tls-failure". This typically happens when the IdP uses certificate pinning and an intermediary such as an enterprise firewall has intercepted the TLS connection.

• If the script loaded from the identity provider is not valid JavaScript or does not implement the correct interfaces, it causes an IdP failure with an {{RTCError}} witherrorDetail set to "idp-bad-script-failure".

• An apparently valid identity provider might fail in several ways. If the IdP token has expired, then the IdP MUST fail with an {{RTCError}} witherrorDetail set to "idp-token-expired". If the IdP token is not valid, then the IdP MUST fail with an {{RTCError}} witherrorDetail set to "idp-token-invalid". If an identity provider throws an exception or returns a promise that is ultimately [= reject | rejected =], then the procedure that depends on the IdP MUST also fail. These types of errors will cause an IdP failure with an {{RTCError}} witherrorDetail set to "idp-execution-failure".

• Theuser agent SHOULD limit the time that it allows for an IdP to 15 seconds. This includes both the loading of theIdP proxy and the identity assertion generation or validation. Failure to do so potentially causes the corresponding operation to take an indefinite amount of time. This timer can be cancelled when the IdP proxy produces a response. Expiration of this timer cases an IdP failure with an {{RTCError}} witherrorDetail set to "idp-timeout".

• If the identity provider requires the user to login, the operation will fail {{RTCError}} witherrorDetail set to "idp-need-login" and theidpLoginUrl attribute of the error set to the URL that can be used to login.

• Even when the IdP proxy produces a positive result, the procedure that uses this information might still fail. Additional validation of anRTCIdentityValidationResult value is still necessary. The procedure forvalidation of identity assertions describes additional steps that are required to successfully validate the output of the IdP proxy.

Any error generated by the IdP MAY provide additional information in theidpErrorInfo attribute. The information in this string is defined by the IdP in use.

RTCPeerConnection Interface Extensions

The Identity API extends the {{RTCPeerConnection}} interface as described below.

partial interface RTCPeerConnection {    undefined               setIdentityProvider (DOMString provider, optional RTCIdentityProviderOptions options = {});    Promise<DOMString> getIdentityAssertion ();    readonly        attribute Promise<RTCIdentityAssertion> peerIdentity;    readonly        attribute DOMString?                    idpLoginUrl;    readonly        attribute DOMString?                    idpErrorInfo;};

partial dictionary RTCConfiguration {  DOMString peerIdentity;};

dictionary RTCIdentityProviderOptions {    DOMString protocol = "default";    DOMString usernameHint;    DOMString peerIdentity;};

[Exposed=Window]interface RTCIdentityAssertion {    constructor(DOMString idp, DOMString name);    attribute DOMString idp;    attribute DOMString name;};

RTCError Interface Extensions

partial interface RTCError {  readonly attribute long? httpRequestStatusCode;};

RTCErrorInit Dictionary

partial dictionary RTCErrorInit {  long httpRequestStatusCode;};

// This is an extension of RTCErrorDetailType from [[WEBRTC-PC]]// Unfortunately, WebIDL does not support partial enums (yet).//// partial enum RTCErrorDetailType {enum RTCErrorDetailTypeIdp {  "idp-bad-script-failure",  "idp-execution-failure",  "idp-load-failure",  "idp-need-login",  "idp-timeout",  "idp-tls-failure",  "idp-token-expired",  "idp-token-invalid",};

Media Stream API Extensions for Network Use

partial dictionary MediaStreamConstraints {             DOMString peerIdentity;};

partial interface MediaStreamTrack {    readonly        attribute boolean      isolated;                    attribute EventHandler onisolationchange;};

Identity Examples

The identity system is designed so that applications need not take any special action in order for users to generate and verify identity assertions; if a user has configured an IdP into their browser, then the browser will automatically request/generate assertions and the other side will automatically verify them and display the results. However, applications may wish to exercise tighter control over the identity system as shown by the following examples.

pc.setIdentityProvider('example.com');

pc.setIdentityProvider('example.com', {  usernameHint: 'alice@example.com',  peerIdentity: 'bob@example.net'});

async function consumeIdentityAssertion() {  const identity = await pc.peerIdentity;  console.log('IdP = ', identity.idp, 'identity =', identity.name);}

Event summary

The following events fire on {{MediaStreamTrack}} objects:

Privacy and Security Considerations

This section is non-normative; it specifies no new behaviour, but instead summarizes information already present in other parts of the specification. The overall security considerations of the general set of APIs and protocols used in WebRTC Identity are described in [[RTCWEB-SECURITY-ARCH]].

Change Log

This section will be removed before publication.

Changes since June 21, 2018

1. This document was split from the [[WEBRTC]] specification.
2. Editors were changed to Cullen Jennings and Martin Thomson.

Acknowledgements

The editors wish to thank the Working Group chairs and Team Contact, Harald Alvestrand, Stefan Håkansson, Erik Lagerway and Dominique Hazaël-Massieux, for their support. Substantial text in this specification was provided by many people including Martin Thomson, Harald Alvestrand, Justin Uberti, Eric Rescorla, Peter Thatcher, Jan-Ivar Bruaroey and Peter Saint-Andre. Dan Burnett would like to acknowledge the significant support received from Voxeo and Aspect during the development of this specification.