946
edits
Services/Identity/Spec: Difference between revisions
Jump to navigation
Jump to search
no edit summary
No edit summary |
|||
| Line 22: | Line 22: | ||
;secondary authority | ;secondary authority | ||
:A 3rd party service trusted by a relying party to issue identity assertions in lieu of a service which has not yet deployed infrastructure to issue identity assertions on their own. | :A 3rd party service trusted by a relying party to issue identity assertions in lieu of a service which has not yet deployed infrastructure to issue identity assertions on their own. | ||
== Protocol Flow == | |||
There are two ways for the protocol to operate, on current-generation browsers and on smart clients. Current-generation browsers are supported by means of a JavaScript library which creates an identical DOM API as a smart client would have. Thus, it makes no difference to relying parties--but the legacy scenario creates a dependency on a live service. | |||
;Current-generation client flow | |||
A relying party includes a JavaScript library which injects new APIs into the DOM if they do not already exist (navigator.id.*). The relying party executes code like: | |||
navigator.id.onVerifiedEmail = function(identity_assertion) { | |||
/* XHR identity_assertion to relying party server */ | |||
}); | |||
And also creates a "Sign In button on their page which, when clicked by a user, invokes the ''navigator.id.getVerifiedEmail()'' method. This method will start the verified email disclosure process. | |||
Behind the scenes, the JavaScript library has created a hidden iframe to the ''secondary authority'' server (using SSL). When the getVerifiedEmail method executes, it sends a PostMessage to the hidden secondary authority iframe requesting an identity assertion for the relying party. | |||
Another JavaScript library inside the secondary authority iframe is responsible for responding to these PostMessage requests, as well as for communicating with the secondary authority's server using an internal API. | |||
This inner library first ensures the user has an active session with the secondary authority itself. If it doesn't, it opens a pop-up window for the user to sign into the secondary authority, or create a new account. | |||
After the user is signed into the secondary authority, the inner library requests a list of verified email addresses from the secondary authority. It then displays a pop-up window so the user can choose which email to disclose to the relying party. | |||
Once the user has chosen an email, the inner library requests an identity assertion from the secondary authority, scoped to the relying party, and returns the assertion via PostMessage to the relying party. | |||
The JS library included by the relying party receives the identity assertion via PostMessage, and executes the navigator.id.onVerifiedEmail callback. | |||
The relying party may then send the assertion to their own server, and either cryptographically verify the assertion (it will be signed by the secondary authority's public key), or send it to the secondary authority over SSL for on-line verification. After the assertion is verified, the relying party may consider the session with the browser it came from to be ''active'', and set a cookie in the same way it would do today after a user signs in. | |||
Client-side, the relying party may set the navigator.id.sessions array with a Session object that informs the user agent that there is an active session, how long to consider it active for, and with a method for the user agent to terminate the session (if the user wishes to do so). | |||
Note that the wrapper JS library won't inject the getVerifiedEmail() method if it already exists, and thus a native client could implement the same API calls natively in the browser. | |||
== Identity Assertions == | |||
Identity Assertions are JWT-signed JSON bundles (see Sec. 1.7) which, after disclosure to a site, can be used to verify (via signature checking, or a pingback to the assertion's issuer) that the current session has verified a given email. | |||
All Idenitity Assertions have in their JSON payload the following fields (all are required): | |||
* type: always set to "server-signed" | |||
* issuer: issuing authority, RP will use it to verify they trust the issuer as well as verify the IA (A domain, with a Well Known URL for validation) | |||
** ''rationale: having it be a domain defines the authority. If a site wishes to validate, they would do so using a well known address (TBD). This also prevents potential spoofing if a Authorize structure is presented (e.g. name:"Mozilla.com", url:"evilonastick.com")'' | |||
* audience: who the IA is intended for, RP will verify to make sure it's not being subject to a replay attack with an IA for another site | |||
* valid-until: a timestamp in the future at which point the IA will no longer be considered valid. | |||
* email: the email of the user | |||
Sample Identity Assertion Object: | |||
{ | |||
type: "server-signed", | |||
issuer: "identity.mozilla.com", | |||
audience: "destination.com", | |||
valid-until: <format TBD>, | |||
email: "alice@site.com" | |||
} | |||
== Relying Party JavaScript API == | == Relying Party JavaScript API == | ||
| Line 64: | Line 119: | ||
;verify | ;verify | ||
type: POST | * type: POST | ||
SSL: required | * SSL: required | ||
path: /1/verify | * path: /1/verify | ||
* parameters: | |||
parameters: | ** audience: relying party | ||
* audience: relying party | ** identity_assertion: encoded identity assertion block | ||
* identity_assertion: encoded identity assertion block | * returns: | ||
** *SUCCESS* if identity assertion is valid and was issued to audience | |||
** *INVALID* if identity assertion is invalid or does not match audience | |||
** *PARSE_ERROR* parameters are empty or malformed | |||
note: should look at OCSP here to see if we can re-use any part of that | |||
== | == Secondary Authority Internal API == | ||
Pages ID service must implement: | Pages ID service must implement: | ||
| Line 200: | Line 255: | ||
If there is no active session, fails with *LOGIN ERROR* | If there is no active session, fails with *LOGIN ERROR* | ||
=== Service API === | === Service API === | ||