Normalize CredentialsContainer.create() method

[wbamberg]

This PR is an attempt to make https://developer.mozilla.org/en-US/docs/Web/API/CredentialsContainer/create more comprehensible, by making standalone pages for the three different dictionary types that are used to create each of the three credential types (password, federated, public key).

It makes https://developer.mozilla.org/en-US/docs/Web/API/CredentialsContainer/create much shorter, simpler, and consistent with the other method pages we have, and I hope exposes its high-level structure much more clearly.

I've also added glossary entries for "credential" and "authentication"- they are pretty short but a reasonable start.

Various things.

• In https://developer.mozilla.org/en-US/docs/Web/API/CredentialsContainer/create#password_object_structure, the description of how forms can be used to init password credentials seems to be wrong: it is I think the autocomplete attribute that is used to map elements to properties, and that's what the spec says as well: https://w3c.github.io/webappsec-credential-management/#construct-passwordcredential-form. I added a live sample of this although it might not work in production because of iframe/CSP nonsense.
• The create() page has a note at the start saying "This method is restricted to top-level browsing contexts", which AFAICT is also wrong, I seem to get it working fine in an iframe.
• The password credential create examples don't work in Firefox, I get "DOMException: CredentialContainer request is not supported." which is odd because the compat table doesn't mention anything. They work fine in Chrome though.
• We should probably fix up the PasswordCredential() constructor along the same lines as https://pr33360.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/PasswordCredentialInit, especially for the bits about initializing from a form.
• The preview page https://pr33360.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/PublicKeyCredentialCreationOptions redirects to CredentialsContainer/create I think because of CI: PR review companion doesn't handle redirects well #32501.

If you like this we will do the same for https://developer.mozilla.org/en-US/docs/Web/API/CredentialsContainer/get. There's a lot more scope for improving the credential management docs.

[github-actions]

Preview URLs (7 pages)

• /en-US/docs/Glossary/Authentication
• /en-US/docs/Glossary/Credential
• /en-US/docs/Web/API/CredentialsContainer/create
• /en-US/docs/Web/API/FederatedCredentialInit
• /en-US/docs/Web/API/PasswordCredentialInit
• /en-US/docs/Web/API/PublicKeyCredential/parseCreationOptionsFromJSON_static
• /en-US/docs/Web/API/PublicKeyCredentialCreationOptions

External URLs (3)

URL: /en-US/docs/Web/API/PublicKeyCredentialCreationOptions
Title: PublicKeyCredentialCreationOptions

• https://en.wikipedia.org/wiki/Challenge%E2%80%93response_authentication (1 time) (Note! This may be a new URL 👀)
• https://www.iana.org/assignments/cose/cose.xhtml (1 time) (Note! This may be a new URL 👀)
• https://www.iana.org/assignments/webauthn/webauthn.xhtml (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2024-05-15 01:50:06)

[hamishwillee]

My review list has grown out of control, but if no one else has dealt with this by Monday, I will look at it then. Feel free to ping me a reminder.

[hamishwillee]

I'm just having a scan now. Plan to look at this Monday/Tues in detail

• Should we add the dictionaries FederatedCredentialInit and so on to https://developer.mozilla.org/en-US/docs/Web/API/Credential_Management_API and the sidebar?

• The create() page has a note at the start saying "This method is restricted to top-level browsing contexts", which AFAICT is also wrong, I seem to get it working fine in an iframe.

  This doesn't seem to be defined in the spec. What I suspect is that this was true at some point for some kinds of credentials. But it isn't true or strictly true now.
  My evidence is https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy/publickey-credentials-create which shows that in at least the Web authentication case, there is a permissions-policy gating. That means you can't just embed an iframe to anywhere - you need to specify the allowed non-same-origin sites via an HTTP header, and also specify them in the frame (except on FF, which doesn't send the header ever).

  We probably need to check the specs for each type of credential. I'd water this down with something that says this may be gated by permissions and link what we know.

[hamishwillee]

PublicKeyCredential is missing from the sidebar and parent interface doc.

[wbamberg]

PublicKeyCredential is defined in the Web Authentication API, not the CM API: https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API.

[hamishwillee]

@wbamberg It fees wrong that it isn't listed on the parent interface but fair enough.

[hamishwillee]

@wbamberg Yes, this structure is vastly better - absolutely in favour of moving forward with this. How do you want to proceed. Merge and continue, or do get() and fixes to this as a follow on?

There are comments inline but here are a few more:

1. PasswordCredential, the thing returned by create() has no cross linking to the create or init dictionary, and only refers to fact that you can pass this in fetch(). The example constructs one manually - I think we should at least note that you create or get one via create/get() (and/or state when manually creating one is a good idea.
2. I have similar concerns about https://developer.mozilla.org/en-US/docs/Web/API/FederatedCredential
3. https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential is part of another API. It should at least link as a related topic for all pages, and directly link to create()
4. Init dictionaries in the sidebar.

[wbamberg]

@wbamberg Yes, this structure is vastly better - absolutely in favour of moving forward with this. How do you want to proceed. Merge and continue, or do get() and fixes to this as a follow on?

There are comments inline but here are a few more:

1. PasswordCredential, the thing returned by create() has no cross linking to the create or init dictionary, and only refers to fact that you can pass this in fetch(). The example constructs one manually - I think we should at least note that you create or get one via create/get() (and/or state when manually creating one is a good idea.

2. I have similar concerns about https://developer.mozilla.org/en-US/docs/Web/API/FederatedCredential

3. https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential is part of another API. It should at least link as a related topic for all pages, and directly link to create()

For these, I want to say they are not in scope for this PR. This PR is about improving the create() page, not about improving adjacent pages. Looking at something like https://developer.mozilla.org/en-US/docs/Web/API/PasswordCredential for example, it's pretty close to a rewrite to make it connect properly with the CM API.

I think it's more valuable to merge this and then do the same with get(), and then think about some high-level guide material for the CM API, and maybe then improve the other reference pages.

4. Init dictionaries in the sidebar.

-> f0c2d4f

[wbamberg]

Thanks for the review! I've made some changes and argued with some others :).

[hamishwillee]

I think it's more valuable to merge this and then do the same with get(), and then think about some high-level guide material for the CM API, and maybe then improve the other reference pages.

For sure. Though I'd work on the linked reference pages that are part of this API before the high level guide (just the way I roll :-).

PS, I note you also asked @pepelsbey for a review, but I am confident this is more than acceptable to merge based on the "much better than before" gate. Vadim, if you want to add notes as a post process, I'm sure Will will be happy to take them.