Skip to content

Add use case details for approved_clients field #41496

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+8 −3
Open

Add use case details for approved_clients field #41496

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions files/en-us/web/api/fedcm_api/idp_integration/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,7 +167,9 @@ This includes the following information where `name`, `email`, `username`, and `
- `picture` {{optional_inline}}
- : The URL of the user's avatar image.
- `approved_clients` {{optional_inline}}
- : An array of RP clients that the user has registered with.
- : An array of RP clients that the user has registered with. When an RP user tries to sign in with an IdP account, that IdP's `approved_clients` array is checked. If the RP's `clientId` is found in the array, no disclosure text is displayed to them. In addition, [auto-reauthentication](/en-US/docs/Web/API/FedCM_API/RP_sign-in#auto-reauthentication) won't work unless the RP `clientId` is present in the `approved_clients` array.
> [!NOTE]
> The disclosure text is the information shown to the user (which can include the terms of service and privacy policy links, if provided) if they are signed in to the IdP but don't have an account specifically with the current RP. In such a case, they'd need to choose "Continue as..." to continue with their IdP identity and then create a corresponding account on the RP.
Comment on lines +171 to +172
Copy link
Collaborator

@wbamberg wbamberg Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure this is the best place to put the definition of disclosure. AIUI this page is really about what the IdP has to do to support FedCM. So in a sense, they don't really care about disclosure - all they need to know is what they put in known_clients. What the browser is going to do with that is really up to the browser.

It would be better IMO to talk about disclosure in https://pr41496.review.mdn.allizom.net/en-US/docs/Web/API/FedCM_API/RP_sign-in#fedcm_sign-in_flow, maybe somewhere around step 8?

Also as an IdP, I want to know: when do I add a client to known_clients. What does "registered" mean for me? Is it in https://pr41496.review.mdn.allizom.net/en-US/docs/Web/API/FedCM_API/IDP_integration#the_id_assertion_endpoint, if authentication is successful and disclosure_text_shown was true?

Conversely, when should I remove the client from known_clients?

- `domain_hints` {{optional_inline}}
- : An array of domains the account is associated with. The RP can make a `get()` call that includes a [`domainHint`](/en-US/docs/Web/API/IdentityCredentialRequestOptions#domainhint) property to filter the returned accounts by domain.
- `label_hints` {{optional_inline}}
Expand Down Expand Up @@ -274,7 +276,9 @@ The request payload contains the following params:
- `nonce` {{optional_inline}}
- : The request nonce, provided by the RP.
- `disclosure_text_shown`
- : A string of `"true"` or `"false"` indicating whether the disclosure text was shown or not. The disclosure text is the information shown to the user (which can include the terms of service and privacy policy links, if provided) if the user is signed in to the IdP but doesn't have an account specifically on the current RP (in which case they'd need to choose to "Continue as..." their IdP identity and then create a corresponding account on the RP).
- : A string of `"true"` or `"false"` indicating whether the disclosure text was shown or not. The disclosure text is not shown if:
- The RP's `clientId` was found inside the [`approved_clients`](#approved_clients) array contained in the JSON returned from the [accounts list endpoint](#the_accounts_list_endpoint).
- The browser has observed a sign-up by the same user in the recent past in the absence of `approved_clients`.
- `is_auto_selected`
- : A string of `"true"` or `"false"` indicating whether the authentication validation request has been issued as a result of [auto-reauthentication](/en-US/docs/Web/API/FedCM_API/RP_sign-in#auto-reauthentication), i.e., without user mediation. This can occur when the {{domxref("CredentialsContainer.get", "get()")}} call is issued with a [`mediation`](/en-US/docs/Web/API/CredentialsContainer/get#mediation) option value of `"optional"` or `"silent"`. It is useful for the IdP to know whether auto reauthentication occurred for performance evaluation and in case higher security is desired. For example, the IdP could return an error code telling the RP that it requires explicit user mediation (`mediation="required"`).

Expand Down
3 changes: 2 additions & 1 deletion files/en-us/web/api/fedcm_api/rp_sign-in/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,9 +163,10 @@ With these `mediation` options, auto-reauthentication will occur under the follo
- FedCM is available to use. For example, the user has not disabled FedCM either globally or in the RP's settings.
- The user has only used one account to sign into the RP website on this browser via FedCM. If accounts exist for multiple IdPs, the user won't be automatically re-authenticated.
- The user is signed into the IdP with that account.
- The RP's `clientId` was found inside the [`approved_clients`](/en-US/docs/Web/API/FedCM_API/IDP_integration#approved_clients) array contained in the JSON returned from the [accounts list endpoint](/en-US/docs/Web/API/FedCM_API/IDP_integration#the_accounts_list_endpoint).
- Auto-reauthentication didn't happen within the last 10 minutes. This restriction is put into place to stop users being auto-reauthenticated immediately after they sign out — which would make for a pretty confusing user experience.
- The RP hasn't called {{domxref("CredentialsContainer.preventSilentAccess", "preventSilentAccess()")}} after the previous sign in. This can be used by an RP to explicitly disable auto-reauthentication if desired.
- The UI mode is [passive]().
- The UI mode is [passive](#active_versus_passive_mode).

When these conditions are met, an attempt to automatically reauthenticate the user starts as soon as the `get()` is invoked. If auto-reauthentication is successful, the user will log into the RP site again, without being shown a confirmation prompt, using the same IdP account and validated token as they did before.

Expand Down