identity.txt (11020B)
1 Coverage is based on the following editor draft: 2 https://w3c.github.io/webrtc-pc/archives/20170605/webrtc.html 3 4 9.3 Requesting Identity Assertions 5 6 [Trivial] 7 The identity assertion request process is triggered by a call to createOffer, 8 createAnswer, or getIdentityAssertion. When these calls are invoked and an 9 identity provider has been set, the following steps are executed: 10 11 [RTCPeerConnection-getIdentityAssertion] 12 1. The RTCPeerConnection instantiates an IdP as described in Identity Provider 13 Selection and Registering an IdP Proxy. If the IdP cannot be loaded, instantiated, 14 or the IdP proxy is not registered, this process fails. 15 16 [RTCPeerConnection-getIdentityAssertion] 17 2. The RTCPeerConnection invokes the generateAssertion method on the 18 RTCIdentityProvider methods registered by the IdP. 19 20 [RTCPeerConnection-getIdentityAssertion] 21 The RTCPeerConnection generates the contents parameter to this method as 22 described in [RTCWEB-SECURITY-ARCH]. The value of contents includes the 23 fingerprint of the certificate that was selected or generated during the 24 construction of the RTCPeerConnection. The origin parameter contains the 25 origin of the script that calls the RTCPeerConnection method that triggers 26 this behavior. The usernameHint value is the same value that is provided 27 to setIdentityProvider, if any such value was provided. 28 29 [RTCPeerConnection-getIdentityAssertion] 30 3. The IdP proxy returns a Promise to the RTCPeerConnection. The IdP proxy is 31 expected to generate the identity assertion asynchronously. 32 33 [RTCPeerConnection-getIdentityAssertion] 34 If the user has been authenticated by the IdP, and the IdP is able to generate 35 an identity assertion, the IdP resolves the promise with an identity assertion 36 in the form of an RTCIdentityAssertionResult . 37 38 [RTCPeerConnection-getIdentityAssertion] 39 This step depends entirely on the IdP. The methods by which an IdP authenticates 40 users or generates assertions is not specified, though they could involve 41 interacting with the IdP server or other servers. 42 43 [RTCPeerConnection-getIdentityAssertion] 44 4. If the IdP proxy produces an error or returns a promise that does not resolve 45 to a valid RTCIdentityValidationResult (see 9.5 IdP Error Handling), then 46 identity validation fails. 47 48 [Untestable] 49 5. The RTCPeerConnection MAY store the identity assertion for use with future 50 offers or answers. If a fresh identity assertion is needed for any reason, 51 applications can create a new RTCPeerConnection. 52 53 [RTCPeerConnection-getIdentityAssertion] 54 6. If the identity request was triggered by a createOffer() or createAnswer(), 55 then the assertion is converted to a JSON string, base64-encoded and inserted 56 into an a=identity attribute in the session description. 57 58 [RTCPeerConnection-getIdentityAssertion] 59 If assertion generation fails, then the promise for the corresponding function call 60 is rejected with a newly created OperationError. 61 62 9.3.1 User Login Procedure 63 [RTCPeerConnection-getIdentityAssertion] 64 An IdP MAY reject an attempt to generate an identity assertion if it is unable to 65 verify that a user is authenticated. This might be due to the IdP not having the 66 necessary authentication information available to it (such as cookies). 67 68 [RTCPeerConnection-getIdentityAssertion] 69 Rejecting the promise returned by generateAssertion will cause the error to propagate 70 to the application. Login errors are indicated by rejecting the promise with an RTCError 71 with errorDetail set to "idp-need-login". 72 73 [RTCPeerConnection-getIdentityAssertion] 74 The URL to login at will be passed to the application in the idpLoginUrl attribute of 75 the RTCPeerConnection. 76 77 [Out of Scope] 78 An application can load the login URL in an IFRAME or popup window; the resulting page 79 then SHOULD provide the user with an opportunity to enter any information necessary to 80 complete the authorization process. 81 82 [Out of Scope] 83 Once the authorization process is complete, the page loaded in the IFRAME or popup sends 84 a message using postMessage [webmessaging] to the page that loaded it (through the 85 window.opener attribute for popups, or through window.parent for pages loaded in an IFRAME). 86 The message MUST consist of the DOMString "LOGINDONE". This message informs the application 87 that another attempt at generating an identity assertion is likely to be successful. 88 89 9.4. Verifying Identity Assertions 90 The identity assertion request process involves the following asynchronous steps: 91 92 [TODO] 93 1. The RTCPeerConnection awaits any prior identity validation. Only one identity 94 validation can run at a time for an RTCPeerConnection. This can happen because 95 the resolution of setRemoteDescription is not blocked by identity validation 96 unless there is a target peer identity. 97 98 [RTCPeerConnection-peerIdentity] 99 2. The RTCPeerConnection loads the identity assertion from the session description 100 and decodes the base64 value, then parses the resulting JSON. The idp parameter 101 of the resulting dictionary contains a domain and an optional protocol value 102 that identifies the IdP, as described in [RTCWEB-SECURITY-ARCH]. 103 104 [RTCPeerConnection-peerIdentity] 105 3. The RTCPeerConnection instantiates the identified IdP as described in 9.1.1 106 Identity Provider Selection and 9.2 Registering an IdP Proxy. If the IdP 107 cannot be loaded, instantiated or the IdP proxy is not registered, this 108 process fails. 109 110 [RTCPeerConnection-peerIdentity] 111 4. The RTCPeerConnection invokes the validateAssertion method registered by the IdP. 112 113 [RTCPeerConnection-peerIdentity] 114 The assertion parameter is taken from the decoded identity assertion. The origin 115 parameter contains the origin of the script that calls the RTCPeerConnection 116 method that triggers this behavior. 117 118 [RTCPeerConnection-peerIdentity] 119 5. The IdP proxy returns a promise and performs the validation process asynchronously. 120 121 [Out of Scope] 122 The IdP proxy verifies the identity assertion using whatever means necessary. 123 Depending on the authentication protocol this could involve interacting with the 124 IdP server. 125 126 [RTCPeerConnection-peerIdentity] 127 6. If the IdP proxy produces an error or returns a promise that does not resolve 128 to a valid RTCIdentityValidationResult (see 9.5 IdP Error Handling), then 129 identity validation fails. 130 131 [RTCPeerConnection-peerIdentity] 132 7. Once the assertion is successfully verified, the IdP proxy resolves the promise 133 with an RTCIdentityValidationResult containing the validated identity and the 134 original contents that are the payload of the assertion. 135 136 [RTCPeerConnection-peerIdentity] 137 8. The RTCPeerConnection decodes the contents and validates that it contains a 138 fingerprint value for every a=fingerprint attribute in the session description. 139 This ensures that the certificate used by the remote peer for communications 140 is covered by the identity assertion. 141 142 [RTCPeerConnection-peerIdentity] 143 9. The RTCPeerConnection validates that the domain portion of the identity matches 144 the domain of the IdP as described in [RTCWEB-SECURITY-ARCH]. If this check fails 145 then the identity validation fails. 146 147 [RTCPeerConnection-peerIdentity] 148 10. The RTCPeerConnection resolves the peerIdentity attribute with a new instance 149 of RTCIdentityAssertion that includes the IdP domain and peer identity. 150 151 [Out of Scope] 152 11. The user agent MAY display identity information to a user in its UI. Any user 153 identity information that is displayed in this fashion MUST use a mechanism that 154 cannot be spoofed by content. 155 156 [RTCPeerConnection-peerIdentity] 157 If identity validation fails, the peerIdentity promise is rejected with a newly 158 created OperationError. 159 160 [RTCPeerConnection-peerIdentity] 161 If identity validation fails and there is a target peer identity for the 162 RTCPeerConnection, the promise returned by setRemoteDescription MUST be rejected 163 with the same DOMException. 164 165 9.5. IdP Error Handling 166 [RTCPeerConnection-getIdentityAssertion] 167 - A RTCPeerConnection might be configured with an identity provider, but loading of 168 the IdP URI fails. Any procedure that attempts to invoke such an identity provider 169 and cannot load the URI fails with an RTCError with errorDetail set to 170 "idp-load-failure" and the httpRequestStatusCode attribute of the error set to the 171 HTTP status code of the response. 172 173 [Untestable] 174 - If the IdP loads fails due to the TLS certificate used for the HTTPS connection not 175 being trusted, it fails with an RTCError with errorDetail set to "idp-tls-failure". 176 This typically happens when the IdP uses certificate pinning and an intermediary 177 such as an enterprise firewall has intercepted the TLS connection. 178 179 [RTCPeerConnection-getIdentityAssertion] 180 - If the script loaded from the identity provider is not valid JavaScript or does not 181 implement the correct interfaces, it causes an IdP failure with an RTCError with 182 errorDetail set to "idp-bad-script-failure". 183 184 [TODO] 185 - An apparently valid identity provider might fail in several ways. 186 187 If the IdP token has expired, then the IdP MUST fail with an RTCError with 188 errorDetail set to "idp-token-expired". 189 190 If the IdP token is not valid, then the IdP MUST fail with an RTCError with 191 errorDetail set to "idp-token-invalid". 192 193 [Untestable] 194 - The user agent SHOULD limit the time that it allows for an IdP to 15 seconds. 195 This includes both the loading of the IdP proxy and the identity assertion 196 generation or validation. Failure to do so potentially causes the corresponding 197 operation to take an indefinite amount of time. This timer can be cancelled when 198 the IdP proxy produces a response. Expiration of this timer cases an IdP failure 199 with an RTCError with errorDetail set to "idp-timeout". 200 201 [RTCPeerConnection-getIdentityAssertion] 202 - If the identity provider requires the user to login, the operation will fail 203 RTCError with errorDetail set to "idp-need-login" and the idpLoginUrl attribute 204 of the error set to the URL that can be used to login. 205 206 [RTCPeerConnection-peerIdentity] 207 - Even when the IdP proxy produces a positive result, the procedure that uses this 208 information might still fail. Additional validation of a RTCIdentityValidationResult 209 value is still necessary. The procedure for validation of identity assertions 210 describes additional steps that are required to successfully validate the output 211 of the IdP proxy. 212 213 214 Coverage Report 215 216 Tested 29 217 Not Tested 2 218 Untestable 4 219 220 Total 35