OAuth2 Server | Refresh Token Grant

Overview

The Refresh Token grant allows a client to exchange a previously issued refresh token for a new access token without requiring user interaction. The TsgcHTTP_OAuth2_Server validates the refresh token and issues a new access token (and optionally a new refresh token).

This is useful for long-lived sessions where the access token has a short expiration but the client needs continued access to protected resources.

Flow

1. Client POSTs to the token endpoint with grant_type=refresh_token&refresh_token=...&client_id=...&client_secret=...&scope=...
2. Server validates the refresh token against its stored tokens.
3. Server fires OnOAuth2AfterRefreshToken and returns a JSON response with a new access_token, token_type, expires_in, and optionally a new refresh_token.

Configuration

Refresh tokens are enabled per application when registering the app. Set the RefreshToken parameter to True in Apps.AddApp.

Property	Description
OAuth2Options.Token.Enabled	Set to True to enable the token endpoint. Default: True.
OAuth2Options.Token.URL	The token endpoint URL path. Default: /sgc/oauth2/token
RefreshToken (AddApp parameter)	Set to True to issue refresh tokens for this application. Default: True.

App Registration

When registering the app, set the RefreshToken parameter to True so that the server issues refresh tokens alongside access tokens.

// RefreshToken = True (6th parameter)
OAuth2Server.Apps.AddApp('MyApp', 'http://127.0.0.1:8080',
  'my-client-id', 'my-client-secret', 3600, True, [auth2Code]);

Events

Event	Description
OnOAuth2AfterRefreshToken	Fired after the server successfully issues a new access token from a refresh token. Useful for logging token rotation.
OnOAuth2AfterAccessToken	Fired after the new access token is issued.

Example

OAuth2Server := TsgcHTTP_OAuth2_Server.Create(nil);
// Register app with refresh token support
OAuth2Server.Apps.AddApp('MyApp', 'http://127.0.0.1:8080',
  'my-client-id', 'my-client-secret', 3600, True, [auth2Code]);
Server.Authentication.Enabled := True;
Server.Authentication.OAuth.OAuth2 := OAuth2Server;
// Log refresh token usage
procedure TForm1.OAuth2ServerOAuth2AfterRefreshToken(Sender: TObject;
  const OldToken, NewToken, NewRefreshToken: String; ExpiresIn: Integer);
begin
  Log('Token refreshed. New token: ' + NewToken);
end;

Token Rotation

When a refresh token is used, the server may issue a new refresh token alongside the new access token. The old refresh token is invalidated. This is known as refresh token rotation and helps prevent token replay attacks.

Recovering Tokens After Restart

If the server is restarted while tokens are still valid, you can recover them using Apps.AddToken before starting the server. See OAuth2 Recover Access Tokens for details.