summaryrefslogtreecommitdiffstats
path: root/testing/web-platform/tests/webrtc/coverage/identity.txt
blob: 0d1bcca7ed094ecfbc6e61d72b63fd82a6aec546 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
Coverage is based on the following editor draft:
https://w3c.github.io/webrtc-pc/archives/20170605/webrtc.html

9.3 Requesting Identity Assertions

  [Trivial]
  The identity assertion request process is triggered by a call to createOffer,
  createAnswer, or getIdentityAssertion. When these calls are invoked and an
  identity provider has been set, the following steps are executed:

    [RTCPeerConnection-getIdentityAssertion]
    1.  The RTCPeerConnection instantiates an IdP as described in Identity Provider
        Selection and Registering an IdP Proxy. If the IdP cannot be loaded, instantiated,
        or the IdP proxy is not registered, this process fails.

    [RTCPeerConnection-getIdentityAssertion]
    2.  The RTCPeerConnection invokes the generateAssertion method on the
        RTCIdentityProvider methods registered by the IdP.

        [RTCPeerConnection-getIdentityAssertion]
        The RTCPeerConnection generates the contents parameter to this method as
        described in [RTCWEB-SECURITY-ARCH]. The value of contents includes the
        fingerprint of the certificate that was selected or generated during the
        construction of the RTCPeerConnection. The origin parameter contains the
        origin of the script that calls the RTCPeerConnection method that triggers
        this behavior. The usernameHint value is the same value that is provided
        to setIdentityProvider, if any such value was provided.

    [RTCPeerConnection-getIdentityAssertion]
    3.  The IdP proxy returns a Promise to the RTCPeerConnection. The IdP proxy is
        expected to generate the identity assertion asynchronously.

        [RTCPeerConnection-getIdentityAssertion]
        If the user has been authenticated by the IdP, and the IdP is able to generate
        an identity assertion, the IdP resolves the promise with an identity assertion
        in the form of an RTCIdentityAssertionResult .

        [RTCPeerConnection-getIdentityAssertion]
        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.

    [RTCPeerConnection-getIdentityAssertion]
    4.  If the IdP proxy produces an error or returns a promise that does not resolve
        to a valid RTCIdentityValidationResult (see 9.5 IdP Error Handling), then
        identity validation fails.

    [Untestable]
    5.  The RTCPeerConnection 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 new RTCPeerConnection.

    [RTCPeerConnection-getIdentityAssertion]
    6.  If the identity request was triggered by a createOffer() or createAnswer(),
        then the assertion is converted to a JSON string, base64-encoded and inserted
        into an a=identity attribute in the session description.

    [RTCPeerConnection-getIdentityAssertion]
    If assertion generation fails, then the promise for the corresponding function call
    is rejected with a newly created OperationError.

9.3.1 User Login Procedure
  [RTCPeerConnection-getIdentityAssertion]
  An IdP MAY reject an attempt to generate an identity assertion if it is unable to
  verify that a user is authenticated. This might be due to the IdP not having the
  necessary authentication information available to it (such as cookies).

  [RTCPeerConnection-getIdentityAssertion]
  Rejecting the promise returned by generateAssertion will cause the error to propagate
  to the application. Login errors are indicated by rejecting the promise with an RTCError
  with errorDetail set to "idp-need-login".

  [RTCPeerConnection-getIdentityAssertion]
  The URL to login at will be passed to the application in the idpLoginUrl attribute of
  the RTCPeerConnection.

  [Out of Scope]
  An application can load the login URL in an IFRAME or popup window; the resulting page
  then SHOULD provide the user with an opportunity to enter any information necessary to
  complete the authorization process.

  [Out of Scope]
  Once the authorization process is complete, the page loaded in the IFRAME or popup sends
  a message using postMessage [webmessaging] to the page that loaded it (through the
  window.opener attribute for popups, or through window.parent for pages loaded in an IFRAME).
  The message MUST consist of the DOMString "LOGINDONE". This message informs the application
  that another attempt at generating an identity assertion is likely to be successful.

9.4.  Verifying Identity Assertions
  The identity assertion request process involves the following asynchronous steps:

    [TODO]
    1.  The RTCPeerConnection awaits any prior identity validation. Only one identity
        validation can run at a time for an RTCPeerConnection. This can happen because
        the resolution of setRemoteDescription is not blocked by identity validation
        unless there is a target peer identity.

    [RTCPeerConnection-peerIdentity]
    2.  The RTCPeerConnection loads the identity assertion from the session description
        and decodes the base64 value, then parses the resulting JSON. The idp parameter
        of the resulting dictionary contains a domain and an optional protocol value
        that identifies the IdP, as described in [RTCWEB-SECURITY-ARCH].

    [RTCPeerConnection-peerIdentity]
    3.  The RTCPeerConnection instantiates the identified IdP as described in 9.1.1
        Identity Provider Selection and 9.2 Registering an IdP Proxy. If the IdP
        cannot be loaded, instantiated or the IdP proxy is not registered, this
        process fails.

    [RTCPeerConnection-peerIdentity]
    4.  The RTCPeerConnection invokes the validateAssertion method registered by the IdP.

        [RTCPeerConnection-peerIdentity]
        The assertion parameter is taken from the decoded identity assertion. The origin
        parameter contains the origin of the script that calls the RTCPeerConnection
        method that triggers this behavior.

    [RTCPeerConnection-peerIdentity]
    5.  The IdP proxy returns a promise and performs the validation process asynchronously.

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

    [RTCPeerConnection-peerIdentity]
    6.  If the IdP proxy produces an error or returns a promise that does not resolve
        to a valid RTCIdentityValidationResult (see 9.5 IdP Error Handling), then
        identity validation fails.

    [RTCPeerConnection-peerIdentity]
    7.  Once the assertion is successfully verified, the IdP proxy resolves the promise
        with an RTCIdentityValidationResult containing the validated identity and the
        original contents that are the payload of the assertion.

    [RTCPeerConnection-peerIdentity]
    8.  The RTCPeerConnection decodes the contents and validates that it contains a
        fingerprint value for every a=fingerprint attribute in the session description.
        This ensures that the certificate used by the remote peer for communications
        is covered by the identity assertion.

    [RTCPeerConnection-peerIdentity]
    9.  The RTCPeerConnection 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.

    [RTCPeerConnection-peerIdentity]
    10. The RTCPeerConnection resolves the peerIdentity attribute with a new instance
        of RTCIdentityAssertion that includes the IdP domain and peer identity.

    [Out of Scope]
    11. The user 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.

  [RTCPeerConnection-peerIdentity]
  If identity validation fails, the peerIdentity promise is rejected with a newly
  created OperationError.

  [RTCPeerConnection-peerIdentity]
  If identity validation fails and there is a target peer identity for the
  RTCPeerConnection, the promise returned by setRemoteDescription MUST be rejected
  with the same DOMException.

9.5.  IdP Error Handling
  [RTCPeerConnection-getIdentityAssertion]
  - A RTCPeerConnection 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 with errorDetail set to
    "idp-load-failure" and the httpRequestStatusCode attribute of the error set to the
    HTTP status code of the response.

  [Untestable]
  - If the IdP loads fails due to the TLS certificate used for the HTTPS connection not
    being trusted, it fails with an RTCError with errorDetail 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.

  [RTCPeerConnection-getIdentityAssertion]
  - 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 with
    errorDetail set to "idp-bad-script-failure".

  [TODO]
  - An apparently valid identity provider might fail in several ways.

    If the IdP token has expired, then the IdP MUST fail with an RTCError with
    errorDetail set to "idp-token-expired".

    If the IdP token is not valid, then the IdP MUST fail with an RTCError with
    errorDetail set to "idp-token-invalid".

  [Untestable]
  - The user agent SHOULD limit the time that it allows for an IdP to 15 seconds.
    This includes both the loading of the IdP 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 with errorDetail set to "idp-timeout".

  [RTCPeerConnection-getIdentityAssertion]
  - If the identity provider requires the user to login, the operation will fail
    RTCError with errorDetail set to "idp-need-login" and the idpLoginUrl attribute
    of the error set to the URL that can be used to login.

  [RTCPeerConnection-peerIdentity]
  - Even when the IdP proxy produces a positive result, the procedure that uses this
    information might still fail. Additional validation of a RTCIdentityValidationResult
    value is still necessary. The procedure for validation of identity assertions
    describes additional steps that are required to successfully validate the output
    of the IdP proxy.


Coverage Report

  Tested        29
  Not Tested     2
  Untestable     4

  Total         35