Add a federated identity guide #41779

wbamberg · 2025-11-02T19:29:56Z

This PR adds a guide to federated identity.

an overview of what it is
a moderately close look at the main flow in OpenID Connect
a short but sufficient (I think) discussion of the use of third-party cookies in federated identity systems
an overview of FedCM
a short section on considerations around choosing IdPs
summary of strengths and weaknesses

Note that preview images are broken because of mdn/fred#904.

files/en-us/web/security/authentication/federated_identity/index.md

github-actions · 2025-11-02T19:31:33Z

Preview URLs

/en-US/docs/Web/Security/Authentication/Federated_identity

Flaws (3)

URL: /en-US/docs/Web/Security/Authentication/Federated_identity
Title: Federated identity
Flaw count: 3

macros:
- Macro produces link /en-US/docs/Glossary/hash which is a redirect
- Macro produces link /en-US/docs/Glossary/hash which is a redirect
- Can't resolve /en-US/docs/Glossary/single_sign-on

External URLs (12)

URL: /en-US/docs/Web/Security/Authentication/Federated_identity
Title: Federated identity

🚨 http://www.rfc-editor.org/rfc/rfc9700.html (1 time) (Note! This may be a new URL 👀)
https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps-25 (1 time) (Note! This may be a new URL 👀)
https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics (1 time) (Note! This may be a new URL 👀)
https://datatracker.ietf.org/doc/html/rfc6749 (2 times) (Note! This may be a new URL 👀)
https://datatracker.ietf.org/doc/html/rfc9700 (1 time) (Note! This may be a new URL 👀)
https://github.com/aaronpk/oauth-fedcm-profile (1 time) (Note! This may be a new URL 👀)
https://openid.net/developers/how-connect-works/ (2 times) (Note! This may be a new URL 👀)
https://openid.net/specs/openid-connect-backchannel-1_0.html (1 time) (Note! This may be a new URL 👀)
https://openid.net/specs/openid-connect-core-1_0.html (1 time) (Note! This may be a new URL 👀)
https://openid.net/specs/openid-connect-frontchannel-1_0.html (1 time) (Note! This may be a new URL 👀)
https://www.jwt.io/ (1 time) (Note! This may be a new URL 👀)
https://www.rfc-editor.org/rfc/rfc9700.html (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-11-29 04:14:31)

…ex.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

…ederated-identity-guide * origin/federated-identity-guide: Update files/en-us/web/security/authentication/federated_identity/index.md Update files/en-us/web/security/authentication/federated_identity/index.md

hamishwillee · 2025-11-04T06:06:22Z

I think it is most helpful to name specific providers, such as Google and GitHub and (in a slightly different way I suppose) Auth0 but I don't like the idea of seeming to pick winners or entrench monopolies.

Is there any benefit to using a particular specific provider or are they all "much of a muchness". If there is a real benefit then it is absolutely necessary to mention them.
You imply that you have to choose just one provider - I thought you could offer several (perhaps I am imagining things).
Anyway, I imagine that if nothing else, the fact that more users are likely to already be authenticated with an entrenched service would seem compelling.

So depending on the answer above you might say something like.

There are numerous identity providers, and all of them provide similar services. There is some benefit to using established providers, such as Google, Github, and Facebook, as it increase the likelihood that your users will already have an account they can authenticate with.

files/en-us/web/security/authentication/federated_identity/index.md

hamishwillee · 2025-11-04T06:28:42Z

files/en-us/web/security/authentication/federated_identity/index.md

+- The RP passes the code verifier in the _code_verifier_ parameter.
+- The IdP hashes the code verifier, and compares the result with the stored code challenge: if they do not match, then the token request is denied.
+
+This defends against two attacks: CSRF against the RP's redirect URL, and authorization code injection.


Link to attack page for CSRF

-> 412b8ef

files/en-us/web/security/authentication/federated_identity/index.md

hamishwillee · 2025-11-04T06:33:01Z

files/en-us/web/security/authentication/federated_identity/index.md

+
+1. The RP makes a {{httpmethod("POST")}} request to the token endpoint. This request includes the following parameters:
+   - `client_id`: Identifies this RP to the IdP.
+   - `client_secret`: The secret used to authenticate the RP to the token endpoint. The RP could use some alternative mechanism for client authentication, such as TLS client authentication.


Presumably this is just a number right? Presumably this is all done via HTTPs so it can never leak?

Yeah, just an opaque value. And yes, everything over HTTPS. I didn't say that because it feels like the default. Worth spelling out do you think?

Worth implying it can be any value maybe, but not that it needs to be HTTPs.

So maybe "The secret used to authenticate the RP to the token endpoint; this can be any value agreed between the RP and IdP."

In "The RP could use some alternative mechanism for client authentication, such as TLS client authentication." The "RP could use" reads as though the RP is doing the authentication and deciding what the authentication is. If that is correct then cool, but I assumed that this was to identify the RP to the IdP - so it is the IdP doing the authentication of the client.

Does this make sense as a question/ambiguity?

I have tried using different/more words in f97f769, I'm not sure if it is clearer or not.

files/en-us/web/security/authentication/federated_identity/index.md

hamishwillee · 2025-11-04T06:45:54Z

files/en-us/web/security/authentication/federated_identity/index.md

+
+1. The attacker makes an authentication request to the IdP for themselves, and gets back an authorization code for their own tokens.
+
+2. The attacker tricks the user's browser into making an HTTP request to the RP's redirect URL, including the attacker's authorization code. To the RP, this looks like a response from the IdP to an authentication request originating from the user.


Might be worth numbering the point of injection on the preceding flow so it is easier to see what is happening (just thinking aloud)

I'm not sure exactly what change is needed here.

files/en-us/web/security/authentication/federated_identity/index.md

hamishwillee · 2025-11-04T07:01:58Z

files/en-us/web/security/authentication/federated_identity/index.md

+- Because the IdP's stored code challenge is associated with the authorization code, it will be the challenge for the user.
+- Because the `code_verifier` in the token request is part of the attacker's flow, it will be the verifier for the attacker.


What is meant by ", it will be the challenge for the user." and " it will be the verifier for the attacker.". I can tell this is "the point", but I don't get it.

I think you're saying that

when the authorization request was made for the stolen auth code it included a code_challenge, (which is a hash of the RP code verifier) is stored by the idp and associated with the code.

the auth code gets passed into the flow just before the token request. My understanding is that the RP would include the code_verifier which is a hash of its original challenge

But what happens now is a mystery, because the RP only knows its original request, so presumably that is the correct code_verifier for the original challenge.

I suspect that "t will be the challenge for the user" means that somehow the RP associated the code_verifier that it sends with the token with the user, so when the attacker injects itself into the flow it will have some (or no) code_verifier associated with it.

Whatever the case, I'm not sure the relationships are clear enough.

Perhaps it's clearer if we start earlier, with the user's flow. And lets look at how it works without PKCE, first.

the legitimate user tries to sign in

the RP makes an authentication request to the IdP

the IdP authenticates the user and sends the authorization code

BUT the user has installed a malicious extension, that steals the code, sends it to the attacker, and terminates the user's flow. The user just thinks "something went wrong".

now the attacker has the authorization code. But they can't just make a token request directly, because of client authentication (the attacker can't impersonate the RP).

so instead, the attacker starts their own authentication flow with the RP.

when the IdP sends them the authorization code, they intercept the redirect and replace their code with the the user's code that they stole. Remember, the user's code is for the user's tokens.

next, the RP processes the next step of the attacker's flow, which is the token request. But they're sending the user's code, so it returns the user's tokens to the attacker's flow. Result: the attacker is signed into the user's account

Basically the attack is just the attacker signing in, but splicing in the user's auth code.

(It's the inverse of CSRF, because with CSRF it's the user signing in, but splicing in the attacker's auth code.)

Ah, so in the token request the code_verifier cannot be hashed to the code challenge, because the code challenge was produced in the users original authoriseation flow thingy?

Thanks you. Makes sense.

Now you're going to have to think "did Hamish need me to go through that because it was unclear or because he is an idiot". I think there is room for improvement. But if you want me to suggest something might need to wait until Friday.

With PKCE:

the legitimate user tries to sign in

the RP makes an authentication request to the IdP. -> the RP generates a code verifier, and sends the hashed verifier (i.e. the challenge) to the IdP.

the IdP authenticates the user and sends the authorization code ->the IdP stores the code challenge with the user's code

BUT the user has installed a malicious extension, that steals the code, sends it to the attacker, and terminates the user's flow. The user just thinks "something went wrong".

now the attacker has the authorization code.

the attacker starts their own authentication flow with the RP. ->the RP generates a new code verifier, and the IdP stores this new code challenge next to the attacker's code

When the IdP sends them the authorization code, they intercept the redirect and replace their code with the the user's code that they stole. Remember, the user's code is for the user's tokens.

next, the RP processes the next step of the attacker's flow, which is the token request. ->the RP sends the attacker's code verifier and the user's code. The IdP looks up the user's code, finds the user's verifier, and it doesn't match the code verifier it was passed. So it returns an error.

Why can't the attacker steal the user's code verifier too? Because it's never exposed to the front end, it only ever lives in the RP, server-side.

"did Hamish need me to go through that because it was unclear or because he is an idiot"

It's hard. It took me a while. One challenge is that using more words and taking it step by step helps, but I don't want to spend too many words on this. Another is that once you understand it, it makes sense, and it's hard to know if your explanation makes sense to someone else who doesn't understand it yet! I do think I have probably tried to compress it too much here.

However, I'm pretty sure that omitting the user's initial flow is a mistake, and perhaps including that is enough for this to make sense?

OK I have tried in 412b8ef to clarify the auth code injection attack and defense.

BTW there is a great presentation on this attack here: https://www.youtube.com/watch?v=moQidjdV5cw , probably I should include this too. But I'd appreciate if you can see if the words make sense before watching this :).

I've made some whiny comments, that don't take away from the fact that this is IMO crystal clear now.

hamishwillee · 2025-11-07T04:32:42Z

files/en-us/web/security/authentication/federated_identity/index.md

 - The RP generates a value that is hard to guess and is specific to this authentication request. This value is called the _code verifier_.
 - The RP creates a {{glossary("hash", "cryptographic hash")}} of the code verifier, and uses it as the `code_challenge` parameter in the authentication request.
- The IdP stores the code challenge, and associates it with the access code that it returns to the RP.
+- The IdP stores the code challenge, and associates it with the authorization code that it returns to the RP.


Mabye "user's authorization code" or similar. Just so that later we already have in our minds that this is associated with the user

hamishwillee · 2025-11-07T05:12:13Z

files/en-us/web/security/authentication/federated_identity/index.md

+- In step 1, the RP generates a code verifier for the attacker's request, and sends the hashed code verifier (the code challenge) to the IdP.
+- In step 2, the IdP stores the code challenge alongside the attacker's authorization code.
+- In step 5, the RP won't be able to find a code verifier for the user that matches the challenge the IdP stored, so the token request will fail.



If possible, it might be nice to capture a flavour of your comment below here:

Why can't the attacker steal the user's code verifier too? Because it's never exposed to the front end, it only ever lives in the RP, server-side.

chrisdavidmills · 2025-11-13T08:38:58Z

I've removed my review flag and requested a review from Hamish, as it looks like he is handling this nicely. Let me know if you do, in fact, need input from me.

files/en-us/web/security/authentication/federated_identity/index.md

hamishwillee · 2025-11-20T23:02:52Z

files/en-us/web/security/authentication/federated_identity/index.md

+
+In general, when an RP decides to use a particular IdP for federated login, the RP will register with the IdP, and as part of this process the IdP should explain to the RP exactly which arguments it expected to be given, how it should handle the objects that the IdP returns, and any other behavior it expects the RP to implement.
+
+## Choosing IdPs


I accidentally added some comments to one of your linked commits - so linking in case that doesn't notify properly 443cec7#r171001071

The main useful point was to consider adding info about the costs of having more idps.

files/en-us/web/security/authentication/federated_identity/index.md

hamishwillee · 2025-11-21T00:03:21Z

files/en-us/web/security/authentication/federated_identity/index.md

+
+The [Federated Credential Management API (FedCM API)](/en-US/docs/Web/API/FedCM_API) provides built-in browser support for federated identity. The API does not yet have cross-browser support and is still being actively developed, so we can't fully recommend its use, but it promises several benefits over implementing a protocol like OpenID Connect directly:
+
+- In the OIDC flow we've previously described, the website using OIDC (that is, the RP) has to coordinate the interactions between itself, the user, and the IdP. As we've seen, this is complicated and error-prone. With FedCM, the browser takes care of this interaction: as an RP, you call a browser API, and the browser locates the IdP, asks the user to authenticate, and returns a token from the IdP that the RP can use to sign the user in.


This means the token itself is available in the browser before being returned to the RP. Do we need to worry about the token be stolen or otherwise being misused?

Ah, I see further down the token is not "the token" we already discussed - it might be the authentication code. This overloading of terms feels a bit confusing.

Yeah it is confusing. These are unfortunately the terms used in the spec (I feel like when the spec was written it was assumed that this might be an actual ID token). We could use something other than "token" here though - 'object", "value". I don't think we have to use the spec language.

FWIW the spec says:

The content of the token is opaque to the user agent and can contain anything that the IDP would like to pass to the RP to facilitate the login.

see also my related complaints at #42025.

Yuck. I'd be tempted to keep token but make it clear that it is not the same token - because the terminology is both accurate and also is probably used in the API description and would be hard to purge. So "something like"

Suggested change

- In the OIDC flow we've previously described, the website using OIDC (that is, the RP) has to coordinate the interactions between itself, the user, and the IdP. As we've seen, this is complicated and error-prone. With FedCM, the browser takes care of this interaction: as an RP, you call a browser API, and the browser locates the IdP, asks the user to authenticate, and returns a token from the IdP that the RP can use to sign the user in.

- In the OIDC flow we've previously described, the website using OIDC (that is, the RP) has to coordinate the interactions between itself, the user, and the IdP. As we've seen, this is complicated and error-prone. With FedCM, the browser takes care of this interaction: as an RP, you call a browser API, and the browser locates the IdP, asks the user to authenticate, and returns an opaque token from the IdP that the RP can use to sign the user in. In an OIDC implementation this token might be the authentication code from the IdP.

Got to get onto my queue, so pretending I didn't see your FWIW in #41779 (comment)

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

hamishwillee · 2025-11-22T05:49:26Z

That last round of fixes LGTM. Who else are you going to get look at this?

wbamberg · 2025-11-22T07:48:03Z

That last round of fixes LGTM. Who else are you going to get look at this?

Thank you Hamish! I'm hoping to get some SWAG CG-affiliated people to have a look.

Josh-Cena · 2025-11-23T05:24:08Z

files/en-us/web/security/authentication/federated_identity/index.md

+
+- The next most secure pattern is one in which the website uses a web server to handle all OAuth/OIDC interactions, but then returns the access token to the front end, and the front end then makes API requests directly. In this scenario the website can be a confidential client but malicious code running in the browser (for example, through an XSS attack) can potentially steal access tokens. However, the front end doesn't have to store access tokens long-term: it can retrieve them from the backend when it needs them.
+
+- The least secure pattern is one in which OAuth/OIDC interactions and interactions with APIs both take place in the front end. This, for example, would be the natural architecture for a {{glossary("SPA", "Single-page app")}}, where the entire application executes in the browser. In this architecture the RP can't be a confidential client, because it can't reliably keep a client secret. This means that it can't authenticate itself to the IdP. It also has to persistently store tokens, which increases the risk of malicious code stealing them.


This, for example, would be the natural architecture for a {{glossary("SPA", "Single-page app")}}

I would avoid making this claim, because a lot of SPAs, if they have user data at all, do have a server side, in the form of REST APIs. SPA, CSR, etc., exclusively refer to the frontend architecture and don't really say much beyond "how the page is rendered". Perhaps: "This, for example, would be the natural architecture for an application that executes entirely in the browser."

-> 8e7a48f

Elchi3

Amazing work, thank you @wbamberg! 👍

wbamberg · 2025-11-29T04:15:28Z

This has been open for a while and has had some review, so I'm merging it. Happy to handle any more comments in follow-ups. Thanks for your work on the review @hamishwillee , much appreciated.

* Draft a federated identity guide * Update files/en-us/web/security/authentication/federated_identity/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/web/security/authentication/federated_identity/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * back-channel logout example sentence * OP->IdP * Clearer language * ... * ... * Clarify authorization code injection * Reword client id preamble * Update CSRF description * Add a section on FedCM * Link to BCP * Mention PKCE downgrade attacks * Recommend client auth based on public-key crypto * Add sections on choosing idps and a summary * Update wording for client secret * clarify that PKCE is not used when the attacks work * Apply suggestions from code review Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Hint that client===RP * Review feedback --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

Draft a federated identity guide

802ce2b

github-actions bot added Content:Security Security docs size/m [PR only] 51-500 LoC changed labels Nov 2, 2025

github-actions bot reviewed Nov 2, 2025

View reviewed changes

files/en-us/web/security/authentication/federated_identity/index.md Outdated Show resolved Hide resolved

files/en-us/web/security/authentication/federated_identity/index.md Outdated Show resolved Hide resolved

wbamberg and others added 2 commits November 2, 2025 11:35

Update files/en-us/web/security/authentication/federated_identity/ind…

28a2dac

…ex.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update files/en-us/web/security/authentication/federated_identity/ind…

e513788

…ex.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

wbamberg requested review from Elchi3 and hamishwillee November 2, 2025 19:49

wbamberg added 2 commits November 2, 2025 11:59

back-channel logout example sentence

6f066e0

Merge remote-tracking branch 'origin/federated-identity-guide' into f…

918cd07

…ederated-identity-guide * origin/federated-identity-guide: Update files/en-us/web/security/authentication/federated_identity/index.md Update files/en-us/web/security/authentication/federated_identity/index.md

wbamberg mentioned this pull request Nov 2, 2025

Update third-party cookies page #41778

Closed

wbamberg added 4 commits November 2, 2025 16:27

OP->IdP

a32d048

Clearer language

e2047a8

...

2c3f68f

...

ea59a88

hamishwillee reviewed Nov 4, 2025

View reviewed changes

files/en-us/web/security/authentication/federated_identity/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Nov 4, 2025

View reviewed changes

files/en-us/web/security/authentication/federated_identity/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Nov 4, 2025

View reviewed changes

files/en-us/web/security/authentication/federated_identity/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Nov 4, 2025

View reviewed changes

files/en-us/web/security/authentication/federated_identity/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Nov 4, 2025

View reviewed changes

wbamberg added 3 commits November 4, 2025 10:20

Clarify authorization code injection

412b8ef

Reword client id preamble

e84a7dc

Update CSRF description

8570f9b

hamishwillee reviewed Nov 7, 2025

View reviewed changes

wbamberg requested a review from chrisdavidmills November 13, 2025 03:33

chrisdavidmills requested review from hamishwillee and removed request for chrisdavidmills November 13, 2025 08:38

wbamberg added 2 commits November 20, 2025 12:31

Update wording for client secret

f97f769

clarify that PKCE is not used when the attacks work

7f542f3

hamishwillee reviewed Nov 20, 2025

View reviewed changes