Internal Mozilla ID API
The Mozilla ID service acts as a secondary authority, issuing identity assertions
Pages ID service must implement:
- Provide a login page to the user sets a cookie which allows the page to make an XHR request to return an Identity Assertion for that user.
- Provide account creation page(s) to create a new account.
- Provide an account recovery page to send a verification token via email
- Provide disclosure dialog page
ID Server Cookies:
ID Server cookies are used by the service.js (see Sec. 41.5.2) script inside of the server provided frame to allow for continuous end-customer service. These cookies are permanent and contains and interal "freshness date" for when to become "passive"
ID Active Session:
User has actively logged in to id.moz
provides the ability for JS Library contained in secured iframe to request an Identity Assertion
TTL: (TBD)
ID Passive Session:
(Active cookie freshness expired. Need to re-auth)
Active Session has expired
Requires user action before setting to Acitve Session
TTL: (TBD)
Server API Endpoints
General
All API endpoints are SSL only and require a POST. All calls are made XMLHTTPRequest POST and return JSON objects unless otherwise specified.
Unless a callback is specified, the request will use standard HTTP status codes to indicate errors.
JSON responses (unless otherwise specified) follow the format of:
{"success":True|False,
"error": { // Only present if "success" is false
"code": Numeric Code (reflecting the HTTP Status code),
"reason": Human Readable error reason },
Data}
"error" only exists if there was an error with the transaction.
"Data" is short-hand for the function specific data elements returned. See individual functions for return results.
Service APIs
The following API calls are made by the service.js (see Sec. 41.5.2) code inside the trusted iframe back to the ID Server. The API calls shall check the origin of the requests to ensure that they are from the mozilla.com served iframe. See Status (Sec. 1.8) for a description of the return status types.
https://servername/1/logged_in
Is the user logged into Mozilla ID service (Is the Active_Session cookie valid)
Parameters:
none.
Returns:
returns *SUCCESS*
Errors:
If there is no Active Session, returns *LOGIN ERROR*
https://server/1/get_default_email
Parameters:
audience: RP
Returns:
Return the default email associated with this RP
Errors:
If there is no active session, fails with *LOGIN ERROR*
https://servername/1/get_emails
Parameters:
audience: RP
Returns:
(TBD) returns a JSON block of candidate email addresses indicating which email may have been previously used with this site and which email is "preferred"
Errors:
If there is no active session, fails with *LOGIN ERROR*
https://servername/1/get_identity_assertion
This is the Identity Assertion Request (IAR). It returns an Identity Assertion for the given audience and email.
Parameters:
audience: requesting site (to come from trusted iframe)
email: user email address to use for this assertion.
Returns:ver
Returns Identity Assertion. (as decribed in Sec 1.3)
Errors:
If there is no Active Session, the IAR will fail with a *LOGIN ERROR*, and the JS Library should prompt for login.
https://server/1/remove_association
removes the "automatic" flag, requiring user to confirm access to the site, and specify the preferred email (if more than one is available)
Parameter:
audience: RP
Returns:
*SUCCESS*, FAILURE*
Errors:
If there is no active session, fails with *LOGIN ERROR*
Service API
*** PostMessage API ***
see: jschannel
...
- how does it open a popup? does it need to talk to the wrapper to request a popup?
- how does it report failure to the wrapper API?
- how does it communicate with a popup?
1. page calls wrapper::getVerifiedEmail(cb)
2. wrapper::getVerifedEmail() calls service js to determine the current user's email
if customer
3. service js determines if user has active session
if no, then get an active session by use of a pop-up
(if service js fails to establish an active session, then return a failure)
4. service js determines if there is a default email already set to be disclosed to this RP
if no, then
make an API call to the ID server to fetch the list of possible email addresses to use, and show a pop-up to let the user decide if/what to disclose to the RP
if user cancels, return a failure (the same failure!)
5. once the service js has established the desired email to be disclosed, make an IAR (identity assertion request) to the ID server to obtain an IA that will be returned to the page
6. the wrapper gets back the IA from the service JS and calls the callback with status and IA.
Identity Assertion Request (IAR)
An IAR is the call the JS library does, from a trusted and authenticated iframe, to acquire an Identity Assertion (IA) for a given email address and requesting site (RP). The JS library must ensure the user has consented to the disclosure of information to the RP before making this call. See below for the IA format.
Note that:
- IAs are returned only if authorized by cookie (in a trusted iframe).
- IAs should be requested by the JS library only after it has determined that the user wishes to disclose their email to the site.
States:
Samples of the following return status messages.
SUCCESS
{"success": True,
Data...}
LOGIN ERROR
{"success": False,
"error": {"code": 401,
"reason": TBD}}
PARSE_ERROR
{"success": False,
"error": {"code": 400,
"reason": TBD}}
INVALID (server to server)
{"success": False,
"error": { "code": 403,
"reason":""}}