- From: Eric Rescorla <ekr@rtfm.com>
- Date: Sun, 26 Aug 2012 20:12:59 -0700
- To: public-webrtc@w3.org
As promised, here is the new text for the IdP API. For your reading convenience, I have rendered this in ASCII. -Ekr NEW TYPE: RTCIdentityAssertion ### RTCIdentityAssertion Type DOMString idp -- The identity provider, identified as a domain name. DOMString name -- An RFC822-conformant [TODO: REF] representation of the verified peer identity. This identity will have been verified via the procedures described in [RTCWEB- SECURITY-ARCH]. ADDITIONS TO PeerConnection: void setIdentityProvider(DOMString provider, optional DOMString protocol, optional DOMString username) Sets the identity provider to be used for a given `PeerConnection` object. Applications need not make this call; if the browser is already configured for an IdP, then that configured IdP will be used to get an assertion. When the `setidentityprovider()` method is invoked, the user agent MUST run the following steps: 1. Set the current identity values to the triplet `provider`, `protocol`, `username`. 2. If the `PeerConnection` object's `PeerConnection` readiness state is `active`, and any of the identity settings have changed, queue a task to run the following substeps: 1. If the connection’s `PeerConnection` readiness state is `CLOSED` (3), abort these steps. 2. Instantiate a new IdP proxy and request an identity assertion. 3. If/when the assertion is obtained, fire a renegotiationneeded event. -- void getIdentityAssertion() Initiates the process of obtaining an identity assertion. Applications need not make this call. It is merely intended to allow them to start the process of obtaining identity assertions before a call is initiated. If an identity is needed, either because the browser has been configured with a default identity provider or because `setidentityprovider()` method was called, then an identity will be automatically requested when an offer or answer is created. Queue a task to run the following substeps. 1. If the connection’s `PeerConnection` readiness state is `CLOSED` (3), abort these steps. 2. Instantiate a new IdP proxy and request an identity assertion. -- readonly attribute RTCIdentityAssertion peeridentity nullable Contains the peer identity assertion information if an identity assertion was provided and verified. -- RequestIdentity This is a enum type constraint that can take the values "yes", "no", and "ifconfigured". The default is a non mandatory "ifconfigured". This constraint indicates whether an identity should be be requested. The value "yes" means that an identity must be requested. The value "no" means that no identity is to be requested. The value "ifconfigured" means that an identity will be requested if either the user has configured an identity in the brower or if the `setIdentityProvider()` call has been made by the JS. -- attribute EventHandler onidentityresult This event handler, of event handler event type `identityresult`, MUST be fired by all objects implementing the `RTCPeerConnection` interface. It is called any time an identity verification succeeds or fails. NEW SECTION EXPLAINING IdP Behavior ## Identity Provider Interaction WebRTC offers and answers (and hence the channels established by PeerConnection objects) can be authenticated by using web-based Identity Providers. The idea is that the entity sending the offer/answer acts as the Authenticating Party (AP) and obtains an identity assertion from the IdP which it attaches to the offer/answer. The consumer of the offer/answer (i.e., the `PeerConnection` on which `setRemoteDescription()` 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--which is deterministic from the IdP's identity--and the generic protocol for requesting and verifying 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. The generic protocol details are described in [RTCWEB-SECURITY-ARCH]. This document specifies the procedures required to instantiate the IdP proxy, request identity assertions, and consume the results. ### Peer-Connection/IdP Communications In order to communicate with the IdP, the browser must instantiate an isolated interpreted context [TODO: What's the technical term?], such as an invisible IFRAME. The initial contents of the context are loaded from a URI derived from the IdP's domain name. [RTCWEB-SECURITY-ARCH; Section XXX]. For purposes of generating assertions, the IdP shall be chosen as follows: 1. If the `setIdentityProvider()` method has been called, the IdP provided shall be used.` 2. If the `setIdentityProvider()` method has not been called, then the browser shall use an IdP configured into the browser. If more than one such IdP is configured, the browser should provide the user with a chooser interface. In order to verify assertions, the IdP domain name and protocol shall be equal to the "domain" and "protocol" fields of the identity assertion. Together these are used to construct the URL of the IdP proxy, which is of the form: https://<domain>/.well-known/idp-proxy/<protocol> The context MUST have a MessageChannel named `window.TBD` which is "entangled" to the `PeerConnection` and is unique to that subcontext. This channel is used for messaging between the `PeerConnection` and the IdP. All messages sent via this channel are strings, specifically the JSONified versions of JS structs. Note that we do not specify the name of the PeerConnection's end of the MessageChannel since it can keep track of it on its own. All messages sent from the `PeerConnection` to the IdP context MUST have an `origin` of `rtcweb://peerconnection/`. The fact that ordinary Web pages cannot set their origin values arbitrarily is an essential security feature, as it stops attackers from requesting WebRTC-compatible identity assertions from IdPs. IdP JS MUST check the origin of all apparent messages from `PeerConnections`. ### Requesting Assertions The identity assertion request process involves the following steps. 1. The `PeerConnection` instantiates an IdP context as described in the previous section. 2. The IdP serves up the IdP JS code to the IdP context. 3. Once the IdP is loaded and ready to receive messages it sends a "READY" message ([RTCWEB-SECURITY-ARCH; Section 5.6.5.2]. Note that this does not imply that the user is logged in, merely that enough IdP state is booted up to be ready to handle PostMessage calls. 4. The IdP sends a "SIGN" message (Section 5.6.5.2.2) to the IdP proxy context. This message includes the material the `PeerConnection` desires to be bound to the user's identity. 5. If the user is not logged in, at this point the IdP will initiate the login process. For instance, it might pop up a dialog box inviting the user to enter their (IdP) username and password. 6. Once the user is logged in (potentially after the previous step), the IdP proxy generates an identity assertion (depending on the authentication protocol this may involve interacting with the IDP server). 7. Once the assertion is generated, the IdP proxy sends a response (Section 5.6.5.2.2) containing the assertion to the `PeerConnection` over the message channel. 8. The `PeerConnection` stores the assertion for use with future offers or answers. If the identity request was triggered by a `createOffer()` or `createAnswer()`, then the assertion is inserted in the offer/answer. ### Verifying Assertions The identity assertion request process involves the following steps. 1. The `PeerConnection` instantiates an IdP context as described in the previous section. 2. The IdP serves up the IdP JS code to the IdP context. 3. Once the IdP is loaded and ready to receive messages it sends a "READY" message ([RTCWEB-SECURITY-ARCH; Section 5.6.5.2]. Note that this does not imply that the user is logged in, merely that enough IdP state is booted up to be ready to handle PostMessage calls. 4. The IdP sends a "VERIFY" message (Section 5.6.5.2.2) to the IdP proxy context. This message includes assertion from the offer/answer which is to be verified. 5. The IdP proxy verifies the identity assertion (depending on the authentication protocol this may involve interacting with the IDP server). 6. Once the assertion is verified the IdP proxy sends a response containing the verified assertion results (Section 5.6.5.2.3) to the `PeerConnection` over the message channel. 7. The `PeerConnection` displays the assertion information in the browser UI and stores the assertion in the peeridentity attribute for availability to the JS application. The assertion information to be displayed shall contain the domain name of the IdP and the identity returned by the IdP and must be displayed via some mechanism which cannot be spoofed by content. [[OPEN ISSUE: The identity information should also be available in the inspector interface defined in [RTCWEB-SECURITY-ARCH; Section 5.5]. ### 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 with to exercise tighter control over the identity system as shown by the following examples. This example shows how to configure the identity provider and protocol. pc.setIdentityProvider("example.com", "example-protocol","alice@example.com"); This example shows how to consume identity assertions inside a Web application. pc.onidentityresult = function(result) { console.log("IdP= " + pc.peeridentity.idp + " identity=" + pc.peeridentity.name); };
Received on Monday, 27 August 2012 03:14:10 UTC