First stab at documenting dynamic well known changes #28

wants to merge 2 commits into


None yet
3 participants

ozten commented Oct 22, 2012

With mozilla/browserid#2078 we give IdPs more context about who they are authorizing, during the discovery phase.

@@ -724,6 +729,8 @@ A domain that includes the standard port, of 80 for HTTP and 443 for HTTPS, SHOU
The expected issuer is either the domain of the certified email address in the last certificate, or the issuer listed in the first certificate if the email-address domain does not support BrowserID.
6. If the expected issuer was designated by the certificate rather than discovered given the user's email address, then the issuer SHOULD be ``, otherwise reject the assertion.
+See User-Agent Compliance for verification discovery details.

ozten Oct 22, 2012


I was looking for a Verifier Compliance section. Since we don't have one... added a note to point the reader to the more normaitive Compliance section.

@@ -447,6 +447,9 @@ The User Agent MUST follow these steps:
* for the given Identity, e.g. ``, determine the domain portion of the identifier, e.g. ``
* look up the BrowserID configuration at `https://<DOMAIN>/.well-known/browserid`, e.g. in this case ``.
If this lookup fails, use the Fallback IdP.
+* if the domain portion of the identifier does not match the domain name being used for lookup, append a query string parameter domain=<EMAIL_DOMAIN>

ozten Oct 22, 2012


As our description is recursive, seems like an okay place to stick this.

I also considered splitting the first step out of the recursive aspect, or defining more terms which are redundant in the case of the initial primary lookup.

This seems the least horrible ;)


callahad commented Oct 22, 2012

From chatting with @warner: Let's make the domain= query arg explicitly optional for the first lookup. Subsequent lookups MUST have it, the first one MAY have it. IdPs are not obligated to behave any differently based on its presence or absence, but it at least creates more capability if they want to do something like that.


ozten commented Oct 22, 2012

the first one MAY have it

Good call, updated.


djc commented on 61f31e8 Oct 23, 2012

First of all, fallback mode isn't really described very well (I filed #30 for that).

Finally, it might help readability if name of the query string parameter ("domain") is quoted or formatted differently somehow.


ozten commented Nov 1, 2012

Line 659 domain is treated like a technical term. That is the only new mention of domain which should be called out, as far as I can tell.

Do you have specific references of domain? Maybe make a pull request off this PR? Thanks!

@ozten ozten referenced this pull request in mozilla/persona Mar 6, 2013


dynamic well-known #2078

@ghost ghost assigned callahad Mar 7, 2013


ozten commented Mar 7, 2013

Thanks for the review @callahad

@djc djc referenced this pull request Nov 20, 2013


merge beta1 into prod #26

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment