Renamed Delegation Token to Refresh Token. Refresh Token URL is now only used to exchange a Refresh Token for an Access Token. Makes more sense for Client to request an Access Token than a Delegation Token (Client may not need to ever use a Refresh Token)
Numerous copy changes per Brian's feedback in prior email.
Attached is PDF and PDF of changes. Word doc is on Google Group site.
Hey guys, the latest spec is looking pretty good. I do have some feedback though:
I actually liked the term Delegation Token, but Refresh Token is fine too.
In Section 5.1.5 - It's probably worthwhile to put in a very brief explanation as to why we recommend that Access Tokens should expire. Specifically, it reduces exposure in case they're compromised via MITM or other compromise.
Section 5.2.3 - would it make sense for the client to get a Refresh Token in the response, or is the client supposed to keep the original assertion and resubmit it?
General feedback - is it necessary to return wrap_access_token_expires_in? It might be sufficient to just tell developers that the Access Token is valid until it doesn't work anymore. If they want to try to optimize things and proactively refresh the access token before it expires, they can just read the SP's documentation to determine the AT's lifetime.
Secton 5.3.7 CAPTCH should be CAPTCHA. Also, echoing Brian's feedback - the captcha_url is required to be on the 2nd request so that the auth server knows what the question was. BTW - I think "CAPTCHA Puzzle" is usually called "CAPTCHA Challenge"
Section 5.3.8 - As I mentioned earlier, I'd prefer that the client_id and client_secret are also passed in to the refresh API.
Section 5.5.4 - why is wrap_display_name passed to the Access Token URL? Wouldn't it be better to pass it on the original browser redirect in Section 5.5.2? The authorization server may want to show the display name to the user when showing the approval page.
Section 6.6 - Should probably mention that intermediate proxy servers may also truncate URLs at 2KB, so even if both the client and the protected resource/auth server are able to handle large urls, an intermediate proxy may truncate the request.
On Mon, Oct 26, 2009 at 10:57 PM, Allen Tom <a...@yahoo-inc.com> wrote: > Section 5.2.3 - would it make sense for the client to get a Refresh Token in > the response, or is the client supposed to keep the original assertion and > resubmit it?
The client shouldn't get a refresh token, but they probably can't reuse the original assertion either. If the client wants to refresh their access token, they should go back to the SAML token issuer and ask for a fresh assertion.
> General feedback - is it necessary to return wrap_access_token_expires_in? > It might be sufficient to just tell developers that the Access Token is > valid until it doesn't work anymore. If they want to try to optimize things > and proactively refresh the access token before it expires, they can just > read the SP's documentation to determine the AT's lifetime.
I lean towards returning wrap_access_token_expires_in, but I could live with it either way.
> Section 5.3.8 - As I mentioned earlier, I'd prefer that the client_id and > client_secret are also passed in to the refresh API.
Yep.
> Section 5.5.4 - why is wrap_display_name passed to the Access Token URL? > Wouldn't it be better to pass it on the original browser redirect in Section > 5.5.2? The authorization server may want to show the display name to the > user when showing the approval page.
> On Mon, Oct 26, 2009 at 10:57 PM, Allen Tom <a...@yahoo-inc.com> > wrote: >> Section 5.2.3 - would it make sense for the client to get a Refresh >> Token in >> the response, or is the client supposed to keep the original >> assertion and >> resubmit it?
> The client shouldn't get a refresh token, but they probably can't > reuse the original assertion either. If the client wants to refresh > their access token, they should go back to the SAML token issuer and > ask for a fresh assertion.
Agreed. The Client would likely need to get a new SAML token to get a new Access Token. The Authorization Server is likely issuing the Access Token primarily on information in the SAML token, so a fresh one is likely required before issuing a new Access Token.
>> General feedback - is it necessary to return >> wrap_access_token_expires_in? >> It might be sufficient to just tell developers that the Access >> Token is >> valid until it doesn't work anymore. If they want to try to >> optimize things >> and proactively refresh the access token before it expires, they >> can just >> read the SP's documentation to determine the AT's lifetime.
> I lean towards returning wrap_access_token_expires_in, but I could > live with it either way.
Returning one is optional for the Authorization Server. The expiry time of the token may vary, so one could imagine it being useful to the Client's that call infrequently as they won't waste a call to the Protected Resource to learn they have an expired token.
>> Section 5.3.8 - As I mentioned earlier, I'd prefer that the >> client_id and >> client_secret are also passed in to the refresh API.
> Yep.
I'll post separately on this.
>> Section 5.5.4 - why is wrap_display_name passed to the Access Token >> URL? >> Wouldn't it be better to pass it on the original browser redirect >> in Section >> 5.5.2? The authorization server may want to show the display name >> to the >> user when showing the approval page.
> Yep.
My bad. I got rid of display name by merging it with Client Identifier. There should only be the required parameter of wrap_client_id
I think this is simpler. The client either has registered identifier or not. If not, then the identifier is the same as the display name. If it is registered, the display name and identifier may be different, or may be the same.
> In Section 5.1.5 - It's probably worthwhile to put in a very brief > explanation as to why we recommend that Access Tokens should > expire. Specifically, it reduces exposure in case they're > compromised via MITM or other compromise.
Expiry of Access Tokens is covered in 4.1. I can add some more language about MitM
> Section 5.2.3 - would it make sense for the client to get a Refresh > Token in the response, or is the client supposed to keep the > original assertion and resubmit it?
> General feedback - is it necessary to return > wrap_access_token_expires_in? It might be sufficient to just tell > developers that the Access Token is valid until it doesn't work > anymore. If they want to try to optimize things and proactively > refresh the access token before it expires, they can just read the > SP's documentation to determine the AT's lifetime.
> Secton 5.3.7 CAPTCH should be CAPTCHA. Also, echoing Brian's > feedback - the captcha_url is required to be on the 2nd request so > that the auth server knows what the question was. BTW - I think > "CAPTCHA Puzzle" is usually called "CAPTCHA Challenge"
Fixed typo of CAPTH
The url and the solution are both in the retry at the end of 5.3.7. Did you miss it or am I not understanding you?
> Section 6.6 - Should probably mention that intermediate proxy > servers may also truncate URLs at 2KB, so even if both the client > and the protected resource/auth server are able to handle large > urls, an intermediate proxy may truncate the request.
Section 5.3.8 - As I mentioned earlier, I'd prefer that the client_id and client_secret are also passed in to the refresh API.
Yep.
In 5.3 there is no Client Secret. This is a Rich App getting the Username and Password.
In 5.5, which is the Web App profile where there is a Client Secret, the Verification Code may be one time use and expires. I think those are good features as the Verification Code travels through the browser. Therefore, if the delegation code is lost (which likely means something really bad has happened at the web app), then the web app needs to ask the user permission again, which I think is a good thing if the web app lost something as important as the delegation code. If they have lost their delegation token DB, they likely have lost a whole bunch of other data about the user, including the client secret.
As currently specified, the secret only has value when you have a valid Verification Code, making it less sensitive.
There are some major implementation advantages to having the refresh URL always take just a refresh token.
The only advantage I can see of including the client_id and client_secret is that it allows a Client that has been massively compromised to recover by giving them a new secret. The Client's refresh tokens will all have been compromised though, so the value of that mechanism is greatly diminished.
What advantages of including the client_id and client_secret am I missing?
On Tue, Oct 27, 2009 at 12:17 PM, Dick Hardt <Dick.Ha...@microsoft.com> wrote: > In 5.3 there is no Client Secret. This is a Rich App getting the Username > and Password.
Agreed that resending client secret for rich apps would be useless.
> In 5.5, which is the Web App profile where there is a Client Secret, the > Verification Code may be one time use and expires. I think those are good > features as the Verification Code travels through the browser.
Sure. We should keep that.
> As currently specified, the secret only has value when you have a valid > Verification Code, making it less sensitive. > There are some major implementation advantages to having the refresh URL > always take just a refresh token. > The only advantage I can see of including the client_id and client_secret is > that it allows a Client that has been massively compromised to recover by > giving them a new secret. The Client's refresh tokens will all have been > compromised though, so the value of that mechanism is greatly diminished.
I think you've identified the main virtue of using the client secret; it creates a sort of two-factor authentication mechanism that you can leverage. It's hard to rotate refresh tokens, because there are so many of them. Rotating the other factor, the client secret, is more feasible. It can let you recover from massive token compromise.
> On Tue, Oct 27, 2009 at 12:17 PM, Dick Hardt > <Dick.Ha...@microsoft.com> wrote: >> In 5.3 there is no Client Secret. This is a Rich App getting the >> Username >> and Password.
> Agreed that resending client secret for rich apps would be useless.
>> In 5.5, which is the Web App profile where there is a Client >> Secret, the >> Verification Code may be one time use and expires. I think those >> are good >> features as the Verification Code travels through the browser.
> Sure. We should keep that.
>> As currently specified, the secret only has value when you have a >> valid >> Verification Code, making it less sensitive. >> There are some major implementation advantages to having the >> refresh URL >> always take just a refresh token. >> The only advantage I can see of including the client_id and >> client_secret is >> that it allows a Client that has been massively compromised to >> recover by >> giving them a new secret. The Client's refresh tokens will all have >> been >> compromised though, so the value of that mechanism is greatly >> diminished.
> I think you've identified the main virtue of using the client secret; > it creates a sort of two-factor authentication mechanism that you can > leverage. It's hard to rotate refresh tokens, because there are so > many of them. Rotating the other factor, the client secret, is more > feasible. It can let you recover from massive token compromise.
I don't understand how you can fully recover. The Client still needs to get a new set of refresh tokens.
On Tue, Oct 27, 2009 at 1:14 PM, Dick Hardt <Dick.Ha...@microsoft.com> wrote: >> I think you've identified the main virtue of using the client secret; >> it creates a sort of two-factor authentication mechanism that you can >> leverage. It's hard to rotate refresh tokens, because there are so >> many of them. Rotating the other factor, the client secret, is more >> feasible. It can let you recover from massive token compromise.
> I don't understand how you can fully recover. The Client still needs > to get a new set of refresh tokens.
The client doesn't need to get new refresh tokens because they aren't useful on their own. Since the attacker doesn't have the new client secret, they can't use the stolen refresh tokens.
> On Tue, Oct 27, 2009 at 1:14 PM, Dick Hardt > <Dick.Ha...@microsoft.com> wrote: >>> I think you've identified the main virtue of using the client >>> secret; >>> it creates a sort of two-factor authentication mechanism that you >>> can >>> leverage. It's hard to rotate refresh tokens, because there are so >>> many of them. Rotating the other factor, the client secret, is more >>> feasible. It can let you recover from massive token compromise.
>> I don't understand how you can fully recover. The Client still needs >> to get a new set of refresh tokens.
> The client doesn't need to get new refresh tokens because they aren't > useful on their own. Since the attacker doesn't have the new client > secret, they can't use the stolen refresh tokens.
I understand the attacker cannot get access, but the refresh tokens have no value anymore.
Back to my other point, if the web app has been compromised, I think the web app should get the user's permission again. I consider this a feature of the protocol. If you lost your key, you have to go back and ask for another one.
On Tue, Oct 27, 2009 at 1:38 PM, Dick Hardt <Dick.Ha...@microsoft.com> wrote: >> The client doesn't need to get new refresh tokens because they aren't >> useful on their own. Since the attacker doesn't have the new client >> secret, they can't use the stolen refresh tokens.
> I understand the attacker cannot get access, but the refresh tokens > have no value anymore.
I don't follow you on this point. The client secret alone is not useful. The refresh token alone is not useful. They only have value together.
> On Tue, Oct 27, 2009 at 1:38 PM, Dick Hardt > <Dick.Ha...@microsoft.com> wrote: >>> The client doesn't need to get new refresh tokens because they >>> aren't >>> useful on their own. Since the attacker doesn't have the new client >>> secret, they can't use the stolen refresh tokens.
>> I understand the attacker cannot get access, but the refresh tokens >> have no value anymore.
> I don't follow you on this point. The client secret alone is not > useful. The refresh token alone is not useful. They only have value > together.
I meant they have no added value anymore over the Verification Code since they are no longer considered to be secret.
I think the additional implementation complexity outweighs the potential benefit of a compromised web app being able to continue to obtain access tokens without going back to the user.
Having said that, if you guys think it is really important, we can add client_id and client_secret as optional parameters by the Authorization Server.
>> On Tue, Oct 27, 2009 at 1:38 PM, Dick Hardt >> <Dick.Ha...@microsoft.com> wrote: >>>> The client doesn't need to get new refresh tokens because they >>>> aren't >>>> useful on their own. Since the attacker doesn't have the new >>>> client >>>> secret, they can't use the stolen refresh tokens.
>>> I understand the attacker cannot get access, but the refresh tokens >>> have no value anymore.
>> I don't follow you on this point. The client secret alone is not >> useful. The refresh token alone is not useful. They only have value >> together.
> I meant they have no added value anymore over the Verification Code > since they are no longer considered to be secret.
> I think the additional implementation complexity outweighs the > potential benefit of a compromised web app being able to continue to > obtain access tokens without going back to the user.
> Having said that, if you guys think it is really important, we can add > client_id and client_secret as optional parameters by the > Authorization Server.
