Services/Identity/InternalSpec

Note: The Verified Email Protocol has been deprecated. Please check the BrowserID protocol.

Internal Mozilla ID API

The Mozilla ID service acts as a secondary authority, issuing identity assertions to relying parties when requested to do so by an authenticated client.

See the MozillaID/Spec document for general terms and the external API to relying parties. This document describes the API our clients will use to sign-in and request identity assertions from the Mozilla ID service

General Notes

All API endpoints are SSL only and require an HTTP POST request.

Responses

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.

Session Authentication

The Mozilla ID server uses a token to maintain session information. This token is provided by the server, and acquired by the client by providing user credentials via HTTP Basic Auth according to the Firefox Sync API.

The token is generally sent back to the server as a cookie, although it can optionally be provided as a POST parameter (when cookies are not available). Once an active session has been established, the token will be valid for a predetermined period, after which the token will continue to be sent, but the session will be considered inactive.

Returning the session to an active state requires user credentials to be re-sent, which causes the session to be replaced.

Active session timeout: TBD.

The Mozilla ID server MUST require an active session before executing any of the APIs described in this document.

API

logged_in

Is the user logged into Mozilla ID service (Is the Active_Session cookie valid)

• type: POST
• SSL: required
• path: /1/logged_in
• parameters:
  • (none)
• returns:
  • • SUCCESS* if there is an active session to the Mozilla ID server
    • LOGIN_ERROR* if there is no active session

get_default_email

Returns the default email associated with this RP (if the user has previously done so).

• type: POST
• SSL: required
• path: /1/get_default_email
• parameters:
  • audience: RP
• returns:
  • email string if there is an associated email
  •  ?? if there is no default email?
    • LOGIN_ERROR* if there is no active session with the Mozilla ID server

get_emails

(TBD) returns a JSON block of all verified email addresses. If an audience is specified, also indicates which email may have been previously used with this site and which email is "preferred".

• type: POST
• SSL: required
• path: /1/get_emails
• parameters:
  • audience: RP
• returns:
  • TBD
    • LOGIN_ERROR* if there is no active session with the Mozilla ID server

get_identity_assertion

Returns an identity assertion for the given audience and email. The client MUST ensure the user has consented to the disclosure of information to the RP before making this call. MozillaID/Spec for the format of identity assertions.

• type: POST
• SSL: required
• path: /1/get_identity_assertion
• parameters:
  • audience: RP
  • email: verified email to disclose
• returns:
  • serialized identity assertion object
    • LOGIN_ERROR* if there is no active session with the Mozilla ID server

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)

• type: POST
• SSL: required
• path: /1/remove_association
• parameters:
  • audience: RP
• returns:
  • • SUCCESS*
    • FAILURE*
    • LOGIN_ERROR* if there is no active session with the Mozilla ID server

Data flow for most common data call

Pages to be implemented

Pages ID service must implement:

• 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.
• Account creation page(s) to create a new account.
• Account recovery page to send a verification token via email
• Disclosure dialog page

(WIP. See UX mockups on MozillaID for more info.)

Return Status

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":""}}