Re: IdP API Text

Thank you, Eric!

Quick questions (technicall contributor hat):

- The RequestIdentity constraint does not state which call it's going to 
be used with. Where is it supposed to go? (If it's a constraint as the 
term is currently used in Media TF, does it give meaning to have it as 
an optional constraint? If not, can you make the text say that?)

- Is it true that if an identity provider is not provisioned in the UA, 
and the setIdentityProvider is not called by the application, 
self-asserted identities will be used for DTLS? (This will make 
applications that, for one reason or another, don't care about identity 
continue to run).

- Is the special "rtcweb:" URI scheme gone, or has that interaction been 
delegated to another document?





On 08/27/2012 05:12 AM, Eric Rescorla wrote:
> 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 08:13:34 UTC