window.postmessage for Interactive Auth fallback

Require that User-Interactive auth fallback pages call
`window.postMessage` to notify apps of completion.
pull/977/head
Richard van der Hoff 8 years ago
parent 42616f839c
commit e850fd718d

@ -34,6 +34,9 @@
(`#390 <https://github.com/matrix-org/matrix-doc/pull/390>`_). (`#390 <https://github.com/matrix-org/matrix-doc/pull/390>`_).
- Add "Send-to-Device messaging" module - Add "Send-to-Device messaging" module
(`#386 <https://github.com/matrix-org/matrix-doc/pull/386>`_). (`#386 <https://github.com/matrix-org/matrix-doc/pull/386>`_).
- Require that User-Interactive auth fallback pages call
``window.postMessage`` to notify apps of completion
(`#398 <https://github.com/matrix-org/matrix-doc/pull/398>`_).
- Spec clarifications: - Spec clarifications:

@ -428,7 +428,8 @@ To use this authentication type, clients should submit an auth dict as follows:
{ {
"type": "m.login.password", "type": "m.login.password",
"user": "<user_id or user localpart>", "user": "<user_id or user localpart>",
"password": "<password>" "password": "<password>",
"session": "<session ID>"
} }
Alternatively reply using a 3pid bound to the user's account on the homeserver Alternatively reply using a 3pid bound to the user's account on the homeserver
@ -441,7 +442,8 @@ follows:
"type": "m.login.password", "type": "m.login.password",
"medium": "<The medium of the third party identifier. Must be 'email'>", "medium": "<The medium of the third party identifier. Must be 'email'>",
"address": "<The third party address of the user>", "address": "<The third party address of the user>",
"password": "<password>" "password": "<password>",
"session": "<session ID>"
} }
In the case that the homeserver does not know about the supplied 3pid, the In the case that the homeserver does not know about the supplied 3pid, the
@ -460,7 +462,8 @@ To use this authentication type, clients should submit an auth dict as follows:
{ {
"type": "m.login.recaptcha", "type": "m.login.recaptcha",
"response": "<captcha response>" "response": "<captcha response>",
"session": "<session ID>"
} }
Token-based Token-based
@ -477,7 +480,8 @@ To use this authentication type, clients should submit an auth dict as follows:
{ {
"type": "m.login.token", "type": "m.login.token",
"token": "<token>", "token": "<token>",
"txn_id": "<client generated nonce>" "txn_id": "<client generated nonce>",
"session": "<session ID>"
} }
The ``nonce`` should be a random string generated by the client for the The ``nonce`` should be a random string generated by the client for the
@ -544,7 +548,8 @@ To use this authentication type, clients should submit an auth dict as follows:
"client_secret": "<identity server client secret>", "client_secret": "<identity server client secret>",
"id_server": "<url of identity server authed with, e.g. 'matrix.org:8090'>" "id_server": "<url of identity server authed with, e.g. 'matrix.org:8090'>"
} }
] ],
"session": "<session ID>"
} }
Dummy Auth Dummy Auth
@ -562,12 +567,13 @@ the type and session, if provided:
.. code:: json .. code:: json
{ {
"type": "m.login.dummy" "type": "m.login.dummy",
"session": "<session ID>"
} }
Fallback Fallback
<<<<<<<< ++++++++
Clients cannot be expected to be able to know how to process every single login Clients cannot be expected to be able to know how to process every single login
type. If a client does not know how to handle a given login type, it can direct type. If a client does not know how to handle a given login type, it can direct
the user to a web browser with the URL of a fallback page which will allow the the user to a web browser with the URL of a fallback page which will allow the
@ -577,11 +583,92 @@ should open is::
/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/<auth type>/fallback/web?session=<session ID> /_matrix/client/%CLIENT_MAJOR_VERSION%/auth/<auth type>/fallback/web?session=<session ID>
Where ``auth type`` is the type name of the stage it is attempting and Where ``auth type`` is the type name of the stage it is attempting and
``session id`` is the ID of the session given by the homeserver. ``session ID`` is the ID of the session given by the homeserver.
This MUST return an HTML page which can perform this authentication stage. This This MUST return an HTML page which can perform this authentication stage. This
page must attempt to call the JavaScript function ``window.onAuthDone`` when page must use the following JavaScript when the authentication has been
the authentication has been completed. completed:
.. code:: javascript
if (window.onAuthDone) {
window.onAuthDone();
} else if (window.opener && window.opener.postMessage) {
window.opener.postMessage("authDone", "*");
}
This allows the client to either arrange for the global function ``onAuthDone``
to be defined in an embedded browser, or to use the HTML5 `cross-document
messaging <https://www.w3.org/TR/webmessaging/#web-messaging>`_ API, to receive
a notification that the authentication stage has been completed.
Once a client receives the notificaton that the authentication stage has been
completed, it should resubmit the request with an auth dict with just the
session ID:
.. code:: json
{
"session": "<session ID>"
}
Example
<<<<<<<
A client webapp might use the following javascript to open a popup window which will
handle unknown login types:
.. code:: javascript
/**
* Arguments:
* homeserverUrl: the base url of the homeserver (eg "https://matrix.org")
*
* apiEndpoint: the API endpoint being used (eg
* "/_matrix/client/%CLIENT_MAJOR_VERSION%/account/password")
*
* loginType: the loginType being attempted (eg "m.login.recaptcha")
*
* sessionID: the session ID given by the homeserver in earlier requests
*
* onComplete: a callback which will be called with the results of the request
*/
function unknownLoginType(homeserverUrl, apiEndpoint, loginType, sessionID, onComplete) {
var popupWindow;
var eventListener = function(ev) {
if (ev.data !== "authDone" ) {
return;
}
// close the popup
popupWindow.close();
window.removeEventListener("message", eventListener);
// repeat the request
var requestBody = {
auth: {
session: sessionID,
},
};
request({
method:'POST', url:apiEndpint, json:requestBody,
}, onComplete);
};
window.addEventListener("message", eventListener);
var url = homeserverUrl +
"/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/" +
encodeURIComponent(loginType) +
"/fallback/web?session=" +
encodeURIComponent(sessionID);
popupWindow = window.open(url);
}
Login Login
~~~~~ ~~~~~

Loading…
Cancel
Save