IdP API Text

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