Add a federated identity guide #41779
Conversation
github-actions
bot
added
Content:Security
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
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
|
Preview URLs Flaws (3)URL:
External URLs (12)URL:
(comment last updated: 2025-11-20 20:44:07) |
…ex.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
…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
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. So depending on the answer above you might say something like.
|
files/en-us/web/security/authentication/federated_identity/index.md
Outdated
Show resolved
Hide resolved
| - 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. |
There was a problem hiding this comment.
Link to attack page for CSRF
files/en-us/web/security/authentication/federated_identity/index.md
Outdated
Show resolved
Hide resolved
|
|
||
| 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. |
There was a problem hiding this comment.
Presumably this is just a number right? Presumably this is all done via HTTPs so it can never leak?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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
Outdated
Show resolved
Hide resolved
|
|
||
| 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. |
There was a problem hiding this comment.
Might be worth numbering the point of injection on the preceding flow so it is easier to see what is happening (just thinking aloud)
There was a problem hiding this comment.
I'm not sure exactly what change is needed here.
files/en-us/web/security/authentication/federated_identity/index.md
Outdated
Show resolved
Hide resolved
| - 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.)
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
"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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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 :).
There was a problem hiding this comment.
I've made some whiny comments, that don't take away from the fact that this is IMO crystal clear now.
| - 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. |
There was a problem hiding this comment.
Mabye "user's authorization code" or similar. Just so that later we already have in our minds that this is associated with the user
| - 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. | ||
|
|
There was a problem hiding this comment.
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.
|
Recommend public-key crypto for client authentication -> ad5a597 |
|
Choosing IdPs, and a summary listing strengths and weaknesses -> 443cec7 |
wbamberg
requested review from
chrisdavidmills
and removed request for
a team
chrisdavidmills
requested review from
hamishwillee
and removed request for
chrisdavidmills
|
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. |
|
|
||
| ##### Ensuring that PKCE is used | ||
|
|
||
| Although PKCE provides effective protection against the attacks described here, it's an optional part of the protocol. This means that an RP must ensure that its chosen IdP not only supports PKCE, but that it mandates the use of PKCE, refusing the token request if a valid code verifier is not included. |
There was a problem hiding this comment.
I very much like this section.
- Are there any major IdP that unexpectedly do/do not mandate the use of PKCE? It might be good to hint if there are particular concerns or "no concerns for the major players'.
- Very nittish, but maybe even more direct - the fact that it is optional is interesting, but the most important bit here is that they need to check that it is mandatory - worth a highlight.
| Although PKCE provides effective protection against the attacks described here, it's an optional part of the protocol. This means that an RP must ensure that its chosen IdP not only supports PKCE, but that it mandates the use of PKCE, refusing the token request if a valid code verifier is not included. | |
| To ensure that PKCE is used, the RP must confirm that its chosen IdP not only supports PKCE, but that it also _mandates_ the use of PKCE — refusing the token request if a valid code verifier is not included. |
There was a problem hiding this comment.
Are there any major IdP that unexpectedly do/do not mandate the use of PKCE? It might be good to hint if there are particular concerns or "no concerns for the major players'.
I'm not familiar enough with OIDC providers to know this unfortunately - and I expect that this is the kind of information that would go out of date quickly.
One very interesting and relevant difference between PKCE and state/nonce is that with PKCE it's the IdP that does the checking, so as an RP you must trust them to do it, and do it properly. Whereas with state/nonce it's the RP that does the checking, so you are more in control of your own destiny.
In some ways that makes PKCE better, because as a rule IdPs are probably going to be more security-minded than random websites. On the other hand it opens this up downgrade attack.
I considered adding this, but I've already spent a lot of words on PKCE.
There was a problem hiding this comment.
That's cool. Leaving this unresolved in case you want to consider my suggestion in 2.
|
|
||
| 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 |
There was a problem hiding this comment.
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.
|
|
||
| For web developers, the biggest benefit of using federated identity is reducing sign-up friction for those users who already have an account with one of the chosen IdPs. Additionally, their chosen IdPs can help websites to securely implement federated identity. | ||
|
|
||
| From a security perspective, the biggest benefit is that because users don't have to create new credentials for each account, there's a lower risk of them choosing passwords that are easy to remember (that is, weak) or of them reusing passwords across sites. |
There was a problem hiding this comment.
| From a security perspective, the biggest benefit is that because users don't have to create new credentials for each account, there's a lower risk of them choosing passwords that are easy to remember (that is, weak) or of them reusing passwords across sites. | |
| From a security perspective, the biggest benefit is that because users don't have to create new credentials for each account, there's a lower risk of them choosing weak passwords that are easier to remember, or of them reusing passwords across sites. |
|
|
||
| From a security perspective, the biggest benefit is that because users don't have to create new credentials for each account, there's a lower risk of them choosing passwords that are easy to remember (that is, weak) or of them reusing passwords across sites. | ||
|
|
||
| We can say that federated identity is a more secure option than just passwords, but it still has problems: |
There was a problem hiding this comment.
| We can say that federated identity is a more secure option than just passwords, but it still has problems: | |
| Using federated identity is a more secure option than just passwords, but it still has problems: |
|
|
||
| In the token request: | ||
|
|
||
| 1. The RP makes a {{httpmethod("POST")}} request to the token endpoint. This request includes the following parameters: |
There was a problem hiding this comment.
| 1. The RP makes a {{httpmethod("POST")}} request to the token endpoint. This request includes the following parameters: | |
| 1. The RP makes a {{httpmethod("POST")}} request to the IdP's token endpoint. This request includes the following parameters: |
| - `code_verifier`: This is the original secret that was used to produce the `code_challenge` parameter in the authentication request. | ||
|
|
||
| 2. The IdP validates the request: | ||
| - It authenticates the RP using client authentication. |
There was a problem hiding this comment.
Perhaps something along the lines of
| - It authenticates the RP using client authentication. | |
| - It authenticates that the request is from the particular RP using the client secret or some other form of client authentication. |
| - `response_type`: Always `"code"` if we are using the two-part flow described here, which is the recommended option. | ||
| - `redirect_uri`: The URL in the RP, that the IdP should redirect to once it has attempted to authenticate the user. This is the URL to which the IdP will deliver the authorization code. | ||
| - `code_challenge`: A cryptographic {{glossary("hash")}} of a secret specific to this authorization request, which will be used by the token endpoint to ensure that the token request is really the counterpart of this authorization request. | ||
| - `scope`: A list of strings that specify which sets of user data the RP wishes to access. |
There was a problem hiding this comment.
"Practically" what might be in the scope is not clear. I assume this perhaps means email addresses and such. Not sure whether it matters.
|
|
||
| The specification considers that clients running on the user's browser are public clients, for the same reason we've already encountered: it's too easy for an attacker to access secrets in a browser via attacks such as XSS. Clients running on a web _server_ are confidential clients. | ||
|
|
||
| In OIDC, only confidential clients may use client authentication, because only confidential clients can be trusted to maintain the security of the client's credentials. |
There was a problem hiding this comment.
I believe here we are using the term client authentication to mean "RP authenticating its identity to the IdP. It feels like at this point we're using the term client without having ever defined what a client is in this context.
This is kind of what I was getting to in https://github.com/mdn/content/pull/41779/files#r2548032506
I don't know if you agree this needs to be f"ixed", but perhaps here.
| In OIDC, only confidential clients may use client authentication, because only confidential clients can be trusted to maintain the security of the client's credentials. | |
| In OIDC, only confidential clients, such as the RP server, may can authenticate themselves as clients of the IdP, because only confidential clients can be trusted to maintain the security of the client's credentials. |
There was a problem hiding this comment.
Yes, in OAuth/OIDC, "client" always means RP.
Maybe I could extend the note at the start of https://pr41779.review.mdn.allizom.net/en-US/docs/Web/Security/Authentication/Federated_identity#authentication_flow, to mention this as well as IdP->OP. And maybe in this section, when I say:
The OAuth specification distinguishes between confidential and public clients. Confidential clients are essentially clients that can keep a secret, and public clients are those that can't.
I could instead say
The OAuth specification distinguishes between confidential and public clients. Confidential clients are essentially RPs that can keep a secret, and public clients are those that can't.
...just to reinforce the usage in this section.
I don't particularly want to say things like "client (which means the RP) everywhere", it will get tortured.
There was a problem hiding this comment.
Maybe add it just once in the first sentence - styled as code to highlight
In the flow we have described, the RP
("client")authenticates itself to theIdP'stoken endpoint when it makes the token request. This means that if an attacker does manage to steal the authorization code, it still has to successfully impersonate the RP to get the tokens from the IdP.
That makes it very clear what the client is for client authentication. I would also be happy with "as well", your suggestion:
The OAuth specification distinguishes between confidential and public clients. Confidential clients are essentially RPs that can keep a secret, and public clients are those that can't.
| - 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](#csrf_against_the_redirect_url), and [authorization code injection](#authorization_code_injection). |
There was a problem hiding this comment.
"This" in "This defends against", is associated with the text above not the feature.
| This defends against two attacks: [CSRF against the RP's redirect URL](#csrf_against_the_redirect_url), and [authorization code injection](#authorization_code_injection). | |
| PKCE defends against two attacks: [CSRF against the RP's redirect URL](#csrf_against_the_redirect_url), and [authorization code injection](#authorization_code_injection). |
|
|
||
| #### Proof Key for Code Exchange (PKCE) | ||
|
|
||
| The `code_challenge` and `code_verifier` values that the RP provides in the authentication request and token request, respectively, are part of a mechanism called _Proof Key for Code Exchange_ (PKCE), specified in {{rfc("7636")}}. |
There was a problem hiding this comment.
Perhaps pull the sentence from the end https://github.com/mdn/content/pull/41779/files#r2548065911 to be clear up front why users should care about PKCE.
| The `code_challenge` and `code_verifier` values that the RP provides in the authentication request and token request, respectively, are part of a mechanism called _Proof Key for Code Exchange_ (PKCE), specified in {{rfc("7636")}}. | |
| The `code_challenge` and `code_verifier` values that the RP provides in the authentication request and token request, respectively, are part of a mechanism called _Proof Key for Code Exchange_ (PKCE), specified in {{rfc("7636")}}. | |
| This mechanism defends against two attacks: [CSRF against the RP's redirect URL](#csrf_against_the_redirect_url), and [authorization code injection](#authorization_code_injection). |
You might then have to have "In the PKCE authentication request"
|
|
||
| 8. The RP signs the attacker into the user's account. | ||
|
|
||
| Note that the `state` parameter doesn't help here, because the authentication request and response really do belong to the same flow - the attacker's. |
There was a problem hiding this comment.
Maybe "using the OIDC state..." or
| Note that the `state` parameter doesn't help here, because the authentication request and response really do belong to the same flow - the attacker's. | |
| Note that using a `state` parameter doesn't help in this case, because the authentication request and response really do belong to the same flow - the attacker's. |
|
|
||
| ## The FedCM API | ||
|
|
||
| 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: |
There was a problem hiding this comment.
Maybe chop up a little
| 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: | |
| The [Federated Credential Management API (FedCM API)](/en-US/docs/Web/API/FedCM_API) provides built-in browser support for federated identity. We can't fully recommend its use, because the API does not yet have cross-browser support and is still being actively developed. However it promises several benefits over implementing a protocol like OpenID Connect directly: |
|
|
||
| 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. |
There was a problem hiding this comment.
| - 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 hence 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. |
|
|
||
| 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. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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"
| - 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. |
There was a problem hiding this comment.
Got to get onto my queue, so pretending I didn't see your FWIW in #41779 (comment)
3 participants
This PR adds a guide to federated identity.
Note that preview images are broken because of mdn/fred#904.