Why add claims in OAuthAuthorizationServerProvider.GrantRefreshToken? - asp.net

Question

I'm configuring AspNet.Identity for OAuth 2 with bearer tokens and I have seen multiple examples of implementing the OAuthAuthorizationServerProvider.GrantRefreshToken method, where the author demonstrates the ability to add a claim to the new ClaimsIdentity as seen below.
I am trying to understand this in the context of my single-server (i.e. my Web API project is both Authorization + Resource server) which I may split into separate servers at a later date, if necessary.
public override Task GrantRefreshToken(OAuthGrantRefreshTokenContext context)
{
var originalClient = context.Ticket.Properties.Dictionary["as:client_id"];
var currentClient = context.ClientId;
if (originalClient != currentClient)
{
context.SetError("invalid_clientId", "Refresh token is issued to a different clientId.");
return Task.FromResult<object>(null);
}
// Change auth ticket for refresh token requests
var newIdentity = new ClaimsIdentity(context.Ticket.Identity);
// CONSIDER: I don't know why you would add a claim here, but here's an example.
//var newClaim = newIdentity.Claims.Where(c => c.Type == "newClaim").FirstOrDefault();
//if (newClaim != null)
//{
// newIdentity.RemoveClaim(newClaim);
//}
//newIdentity.AddClaim(new Claim("newClaim", "newValue"));
var newTicket = new AuthenticationTicket(newIdentity, context.Ticket.Properties);
context.Validated(newTicket);
return Task.FromResult<object>(null);
}
The documentation states:
"The application must call context.Validated to instruct the Authorization Server middleware to issue an access token based on those claims and properties."
I don't understand this. I thought we were handing out a refresh token, not an access token.
Also, "The call to context.Validated may be given a different AuthenticationTicket or ClaimsIdentity in order to control which information flows from the refresh token to the access token."
I thought all of the claims were stored in my signed and encrypted access token, which is passed as Authorization: Bearer XXXXXX. However, I have a tenuous grasp on how ClaimsIdentity and AuthenticationTicket actually relate to anything in my OAuth 2.0 flow.
My best guess is that GrantRefreshToken needs to take the already authenticated and authorized identity (context.Ticket.Identity) and validate that a refresh token should be added to it by calling context.Validated.

Answer 1

Refresh Tokens in OAuth2 are just another type of grant: an alternative method of obtaining a new access_token.
For this reason the RefreshToken must be validated in order to emit a new access_token for the user.
When persisting the refresh token to the underlying storage (e.g. a database) the entire user identity must be stored along with it (usually using SerializeTicket() method of the AuthenticationTokenCreateContext object). This means that any change in the claims acquired during the first access_token generation will not be propagated to other access_tokens emissions using the RefreshToken grant by default (you will need to reload again those claims if you need to update them in the access_token).
I believe this is the main reason why many examples shows how to add/substitute claims in the new Identity inside the GrantRefreshToken method.
I will try to further clarify what usually happens when supporting the RefreshTokenGrant:
The user authenticates himself using any kind of supported grant (e.g. ResourceOwnerCredentials);
We create an Identity bounded to this specific user (we can add Claims at this point) and use it to create a new AuthenticationTicket (that we validate by calling Validated(ticket) on the specific context object) which will be used to create the access_token;
The framework generates a new refresh token calling CreateAsync on the provided IAuthenticationTokenProvider. Inside this method we have to retrieve the ticket and store it into some kind of persistence storage (e.g. a DB) along with an unique Id and some useful metadata. This Id is the refresh_token for the user point of view.
We return to the user the access_token (which contains the serialized claims for the user) and the refresh_token (which is just a reference).
After some time the user must authenticate again (e.g. the access_token expired), so he will send a request to the Token endpoint using the refresh_token.
We retrieve the refresh_token record from the persistent storage and deserialize the ticket that will be used to create a new Identity. This ticket contains all Claims that we added on the first authentication (this is almost an exact copy of the first access_token): if any of those Claims changed during the interval between the current moment and the first authentication (e.g. a new Role is added to the user, email has changed, etc.) we have now the chance to modify the new Identity and add/substitute those Claims, so that the new access_token will reflect the changes.
The flows continues by validating the ticket (as before) and generating a pair of access_token and refresh_token to send to the user.