-
Notifications
You must be signed in to change notification settings - Fork 22.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Normalize CredentialsContainer.get() (#35255)
* Normalize CredentialsContainer.get() * cleaner wording * simplify * Update files/en-us/web/api/credentialscontainer/get/index.md Co-authored-by: Hamish Willee <[email protected]> * Update files/en-us/web/api/credentialscontainer/get/index.md Co-authored-by: Hamish Willee <[email protected]> * Update files/en-us/web/api/publickeycredential/parserequestoptionsfromjson_static/index.md Co-authored-by: Hamish Willee <[email protected]> * Update files/en-us/web/api/identitycredentialrequestoptions/index.md * Update files/en-us/web/api/identitycredentialrequestoptions/index.md * Update files/en-us/web/api/publickeycredentialrequestoptions/index.md * Rework PublicKeyCredentialRequestOptions intro; add a glossary page for authenticator * Update files/en-us/web/api/identitycredentialrequestoptions/index.md Co-authored-by: Hamish Willee <[email protected]> * Update allowCredentials description * Update files/en-us/web/api/credentialscontainer/get/index.md * Update files/en-us/web/api/credentialscontainer/create/index.md Co-authored-by: Hamish Willee <[email protected]> * Apply suggestions from code review Co-authored-by: wbamberg <[email protected]> --------- Co-authored-by: Hamish Willee <[email protected]>
- Loading branch information
1 parent
a3c6caf
commit a8ff915
Showing
8 changed files
with
262 additions
and
278 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| --- | ||
| title: Authenticator | ||
| slug: Glossary/Authenticator | ||
| page-type: glossary-definition | ||
| --- | ||
|
|
||
| {{GlossarySidebar}} | ||
|
|
||
| An **authenticator** is an entity that can perform the cryptographic operations needed to register and authenticate users, and securely store the cryptographic keys used in these operations. | ||
|
|
||
| An authenticator might be implemented in hardware or software. It may be integrated into the device, like the [Touch ID](https://en.wikipedia.org/wiki/Touch_ID) system in Apple devices or the [Windows Hello](https://en.wikipedia.org/wiki/Windows_10#System_security) system, or it might be a removable module like a [Yubikey](https://en.wikipedia.org/wiki/YubiKey). | ||
|
|
||
| The [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API) makes authenticators available to websites as part of the [Credential Management API](/en-US/docs/Web/API/Credential_Management_API). This enables websites to use authenticators to generate {{glossary("credential", "credentials")}} based on {{glossary("public-key cryptography")}}, which can then be used to sign users into websites. | ||
|
|
||
| ## See also | ||
|
|
||
| - Related glossary terms: | ||
| - {{glossary("Authentication")}} | ||
| - {{glossary("Credential")}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
64 changes: 64 additions & 0 deletions
64
files/en-us/web/api/identitycredentialrequestoptions/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,64 @@ | ||
| --- | ||
| title: IdentityCredentialRequestOptions | ||
| slug: Web/API/IdentityCredentialRequestOptions | ||
| page-type: web-api-interface | ||
| spec-urls: https://fedidcg.github.io/FedCM/#dictdef-identitycredentialrequestoptions | ||
| --- | ||
|
|
||
| {{APIRef("FedCM API")}}{{SecureContext_Header}} | ||
|
|
||
| The **`IdentityCredentialRequestOptions`** dictionary represents the object passed to {{domxref("CredentialsContainer.get()")}} as the value of the `identity` option. | ||
|
|
||
| It is used to request an {{domxref("IdentityCredential")}} provided by a {{glossary("identity provider", "federated identity provider")}} that supports the [Federated Credential Management (FedCM) API](/en-US/docs/Web/API/FedCM_API). | ||
|
|
||
| ## Instance properties | ||
|
|
||
| - `context` {{optional_inline}} | ||
|
|
||
| - : A string specifying the context in which the user is authenticating with FedCM. The browser uses this value to vary the text in its FedCM UI to better suit the context. Possible values are: | ||
|
|
||
| - `"continue"` | ||
|
|
||
| - : Suitable for situations where the user is choosing an identity to continue to the next page in the flow, which requires a sign-in. Browsers will provide a text string similar to: | ||
|
|
||
| > _Continue to \<page-origin\> with \<IdP\>_ | ||
| - `"signin"` | ||
|
|
||
| - : Suitable for general situations where the user is signing in with an IdP account they've already used on this origin. Browsers will provide a text string similar to: | ||
|
|
||
| > _Sign in to \<page-origin\> with \<IdP\>_ | ||
| - `"signup"` | ||
|
|
||
| - : An option for situations where the user is signing in to the origin with a new IdP account they've not used here before. Browsers will provide a text string similar to: | ||
|
|
||
| > _Sign up to \<page-origin\> with \<IdP\>_ | ||
| - `"use"` | ||
|
|
||
| - : Suitable for situations where a different action, such as validating a payment, is being performed. Browsers will provide a text string similar to: | ||
|
|
||
| > _Use \<page-origin\> with \<IdP\>_ | ||
| The default value is `"signin"`. | ||
|
|
||
| - `providers` | ||
|
|
||
| - : An array containing a single object specifying details of an IdP to be used to sign in. This object can contain the following properties: | ||
|
|
||
| - `configURL` | ||
| - : A string specifying the URL of the IdP's config file. See [Provide a config file](/en-US/docs/Web/API/FedCM_API/IDP_integration#provide_a_config_file_and_endpoints) for more information. | ||
| - `clientId` | ||
| - : A string specifying the RP's client identifier. This information is issued by the IdP to the RP in a separate process that is specific to the IdP. | ||
| - `loginHint` {{optional_inline}} | ||
| - : A string providing a hint about the account option(s) the browser should provide for the user to sign in with. This is useful in cases where the user has already signed in and the site asks them to reauthenticate. Otherwise, the reauthentication process can be confusing when a user has multiple accounts and can't remember which one they used to sign in previously. The value for the `loginHint` property can be taken from the user's previous sign-in, and is matched against the `login_hints` values provided by the IdP in the array of user information returned from the IdP's [accounts list endpoint](/en-US/docs/Web/API/FedCM_API/IDP_integration#the_accounts_list_endpoint). | ||
| - `nonce` {{optional_inline}} | ||
| - : A random string that can be included to ensure the response is issued specifically for this request and prevent {{glossary("replay attack", "replay attacks")}}. | ||
|
|
||
| > [!NOTE] | ||
| > Currently FedCM only allows the API to be invoked with a single IdP, i.e. the `identity.providers` array has to have a length of 1. Multiple IdPs must be supported via different `get()` calls. | ||
| ## Specifications | ||
|
|
||
| {{Specifications}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
93 changes: 93 additions & 0 deletions
93
files/en-us/web/api/publickeycredentialrequestoptions/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,93 @@ | ||
| --- | ||
| title: PublicKeyCredentialRequestOptions | ||
| slug: Web/API/PublicKeyCredentialRequestOptions | ||
| page-type: web-api-interface | ||
| spec-urls: https://w3c.github.io/webauthn/#dictdef-publickeycredentialrequestoptions | ||
| --- | ||
|
|
||
| {{APIRef("Web Authentication API")}}{{securecontext_header}} | ||
|
|
||
| The **`PublicKeyCredentialRequestOptions`** dictionary represents the object passed to {{domxref("CredentialsContainer.get()")}} as the value of the `publicKey` option:. | ||
|
|
||
| It is used to request a {{domxref("PublicKeyCredential")}} provided by an {{glossary("authenticator")}} that supports the [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API). | ||
|
|
||
| ## Instance properties | ||
|
|
||
| - `allowCredentials` {{optional_inline}} | ||
|
|
||
| - : An array of objects used to restrict the list of acceptable credentials. An empty array indicates that any credential is acceptable. | ||
|
|
||
| Each object in the array will contain the following properties: | ||
|
|
||
| - `id` | ||
|
|
||
| - : An {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}} representing the ID of the public key credential to retrieve. This value is mirrored by the {{domxref("PublicKeyCredential.rawId", "rawId")}} property of the {{domxref("PublicKeyCredential")}} object returned by a successful `get()` call. | ||
|
|
||
| - `transports` | ||
|
|
||
| - : An array of strings providing hints as to the methods the client could use to communicate with the relevant authenticator of the public key credential to retrieve. Possible transports are: `"ble"`, `"hybrid"`, `"internal"`, `"nfc"`, and `"usb"`. | ||
|
|
||
| > [!NOTE] | ||
| > This value is mirrored by the return value of the {{domxref("AuthenticatorAttestationResponse.getTransports", "PublicKeyCredential.response.getTransports()")}} method of the {{domxref("PublicKeyCredential")}} object returned by the `create()` call that originally created the credential. | ||
| > At that point, it should be stored by the app for later use. | ||
| - `type` | ||
|
|
||
| - : A string defining the type of the public key credential to retrieve. This can currently take a single value, `"public-key"`, but more values may be added in the future. This value is mirrored by the {{domxref("Credential.type", "type")}} property of the {{domxref("PublicKeyCredential")}} object returned by a successful `get()` call. | ||
|
|
||
| This value defaults to an empty array. | ||
|
|
||
| - `challenge` | ||
|
|
||
| - : An {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}} originating from the relying party's server and used as a [cryptographic challenge](https://en.wikipedia.org/wiki/Challenge%E2%80%93response_authentication). This value will be signed by the authenticator and the signature will be sent back as part of the {{domxref("AuthenticatorAssertionResponse.signature")}} (available in the {{domxref("PublicKeyCredential.response", "response")}} property of the {{domxref("PublicKeyCredential")}} object returned by a successful `get()` call). | ||
|
|
||
| - `extensions` {{optional_inline}} | ||
|
|
||
| - : An object containing properties representing the input values for any requested extensions. These extensions are used to specific additional processing by the client or authenticator during the authentication process. Examples include dealing with legacy FIDO API credentials, and evaluating outputs from a pseudo-random function (PRF) associated with a credential. | ||
|
|
||
| Extensions are optional and different browsers may recognize different extensions. Processing extensions is always optional for the client: if a browser does not recognize a given extension, it will just ignore it. For information on using extensions, and which ones are supported by which browsers, see [Web Authentication extensions](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions). | ||
|
|
||
| - `hints` {{optional_inline}} | ||
|
|
||
| - : An array of strings providing hints as to what authentication UI the user-agent should provide for the user. | ||
|
|
||
| The values can be any of the following: | ||
|
|
||
| - `"security-key"` | ||
| - : Authentication requires a separate dedicated physical device to provide the key. | ||
| - `"client-device"` | ||
| - : The user authenticates using their own device, such as a phone. | ||
| - `"hybrid"` | ||
| - : Authentication relies on a combination of authorization/authentication methods, potentially relying on both user and server-based mechanisms. | ||
|
|
||
| - `rpId` {{optional_inline}} | ||
|
|
||
| - : A string that specifies the relying party's identifier (for example `"login.example.org"`). For security purposes: | ||
|
|
||
| - The calling web app verifies that `rpId` matches the relying party's origin. | ||
| - The authenticator verifies that `rpId` matches the `rpId` of the credential used for the authentication ceremony. | ||
|
|
||
| This value defaults to the current origin's domain. | ||
|
|
||
| - `timeout` {{optional_inline}} | ||
|
|
||
| - : A numerical hint, in milliseconds, indicating the time the relying party is willing to wait for the retrieval operation to complete. This hint may be overridden by the browser. | ||
|
|
||
| - `userVerification` {{optional_inline}} | ||
|
|
||
| - : A string specifying the relying party's requirements for user verification of the authentication process. This verification is initiated by the authenticator, which will request the user to provide an available factor (for example a PIN or a biometric input of some kind). | ||
|
|
||
| The value can be one of the following: | ||
|
|
||
| - `"required"` | ||
| - : The relying party requires user verification, and the operation will fail if it does not occur. | ||
| - `"preferred"` | ||
| - : The relying party prefers user verification if possible, but the operation will not fail if it does not occur. | ||
| - `"discouraged"` | ||
| - : The relying party does not want user verification, in the interests of making user interaction as smooth as possible. | ||
|
|
||
| This value defaults to `"preferred"`. | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters