OAuth2 Server

Overview

This component provides the OAuth2 protocol implementation in Server Side Components.

At a glance

Features

• Native Delphi implementation with full ANSI/Unicode support.

Technical specification

Main properties

The principal published / public properties used to configure and drive the component. Consult the online help for the full list.

Main methods

The principal public methods exposed by the component.

Public events

The component exposes the following published events; consult the online help for full event-handler signatures.

Quick Start

Drop the component on a form, configure the properties below and activate it. The snippet that follows shows the typical Authorization Code Grant configuration sourced from the online help.

Delphi (VCL / FireMonkey)

// Create and configure OAuth2 server
OAuth2Server := TsgcHTTP_OAuth2_Server.Create(nil);

// Register an application
OAuth2Server.Apps.AddApp('MyApp', 'http://127.0.0.1:8080',
  'my-client-id', 'my-client-secret', 3600, True, [auth2Code]);

// Attach to HTTP server
Server.Authentication.Enabled := True;
Server.Authentication.OAuth.OAuth2 := OAuth2Server;

// Handle authentication
procedure TForm1.OAuth2ServerOAuth2Authentication(Sender: TObject;
  const User, Password: String; var Authenticated: Boolean);
begin
  Authenticated := (User = 'admin') and (Password = 'secret');
end;

// Handle token issuance
procedure TForm1.OAuth2ServerOAuth2AfterAccessToken(Sender: TObject;
  const Token, RefreshToken: String; ExpiresIn: Integer);
begin
  Log('Access token issued: ' + Token);
end;

C++ Builder

// Create and configure OAuth2 server
TsgcHTTP_OAuth2_Server *OAuth2Server = new TsgcHTTP_OAuth2_Server(this);

// Register an application
OAuth2Server->Apps->AddApp("MyApp", "http://127.0.0.1:8080",
  "my-client-id", "my-client-secret", 3600, true,
  TsgcOAuth2GrantTypes() << auth2Code);

// Attach to HTTP server
Server->Authentication->Enabled = true;
Server->Authentication->OAuth->OAuth2 = OAuth2Server;

void __fastcall TForm1::OAuth2ServerOAuth2Authentication(TObject *Sender,
  const UnicodeString User, const UnicodeString Password, bool &Authenticated)
{
  Authenticated = (User == "admin") && (Password == "secret");
}

void __fastcall TForm1::OAuth2ServerOAuth2AfterAccessToken(TObject *Sender,
  const UnicodeString Token, const UnicodeString RefreshToken, int ExpiresIn)
{
  Log("Access token issued: " + Token);
}

.NET (C#)

// Create and configure OAuth2 server
var OAuth2Server = new TsgcHTTP_OAuth2_Server();

// Register an application
OAuth2Server.Apps.AddApp("MyApp", "http://127.0.0.1:8080",
  "my-client-id", "my-client-secret", 3600, true,
  new TsgcOAuth2GrantType[] { TsgcOAuth2GrantType.auth2Code });

// Attach to HTTP server
Server.Authentication.Enabled = true;
Server.Authentication.OAuth.OAuth2 = OAuth2Server;

OAuth2Server.OnOAuth2Authentication += (sender, user, password, ref authenticated) =>
{
  authenticated = (user == "admin") && (password == "secret");
};

OAuth2Server.OnOAuth2AfterAccessToken += (sender, token, refreshToken, expiresIn) =>
{
  Console.WriteLine("Access token issued: " + token);
};

Common scenarios

The following scenarios are lifted verbatim from the online help. Each shows the configuration and method calls needed to drive the component through a specific real-world flow.

1 · OAuth2 | None Authenticate URLs

By default, when OAuth2 is enabled on Server Side, all the HTTP Requests require Authentication using Bearer Tokens.

procedure OnOAuth2BeforeRequest(Sender: TObject; aConnection: TsgcWSConnection; aHeaders: TStringList; 
 var Cancel: Boolean);
begin
if DecodeGETFullPath(aHeaders) = '/Public.html' then
Cancel := True
else if DecodePOSTFullPath(aHeaders) = '/Form.html' then
Cancel := True; 
end;

procedure OnOAuth2BeforeRequest(TObject *Sender; TsgcWSConnection *aConnection; TStringList *aHeaders; 
 ref bool Cancel)
{
if (DecodeGETFullPath(aHeaders) == "/Public.html")
{
Cancel = true;
}
}

procedure OnOAuth2BeforeRequest(TObject Sender; TsgcWSConnection aConnection; TStringList aHeaders; 
  ref bool Cancel)
{
if (DecodeGETFullPath(aHeaders) == "/Public.html")
{
Cancel = true;
}
}

2 · OAuth2 | Server Authentication

When an OAuth2 client requests a new Authorization, the server shows a web page where the user must allow the connection and then login. This page is provided by sgcWebSockets library and is dispatched automatically when a client requests an Authorization.

procedure OnAuth2Authentication(Connection: TsgcWSConnection; OAuth2: TsgcHTTPOAuth2Request; aUser, 
 aPassword: string; var Authenticated: Boolean);
begin
if ((aUser = 'user') and (aPassword = 'secret')) then
Authenticated := True;
end;

void OnOAuth2Authentication(TsgcWSConnection *Connection, TsgcHTTPOAuth2Request *OAuth2, string aUser, 
 string aPassword, ref bool Authenticated)
{
if ((aUser == "user") and (aPassword == "secret"))
{
Authenticated = true;
}
}

void OnOAuth2Authentication(TsgcWSConnection Connection, TsgcHTTPOAuth2Request OAuth2, string aUser, 
  string aPassword, ref bool Authenticated)
{
if ((aUser == "user") and (aPassword == "secret"))
{
Authenticated = true;
}
}

3 · App Registration

Before clients can use the Authorization Code flow, you must register the application on the server. Use Apps.AddApp and ensure the AllowedGrantTypes includes auth2Code.

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

OAuth2Server->Apps->AddApp("MyApp", "http://127.0.0.1:8080",
  "my-client-id", "my-client-secret", 3600, true,
  TsgcOAuth2GrantTypes() << auth2Code);

OAuth2Server.Apps.AddApp("MyApp", "http://127.0.0.1:8080",
  "my-client-id", "my-client-secret", 3600, true,
  new TsgcOAuth2GrantType[] { TsgcOAuth2GrantType.auth2Code });

4 · DPoP Validation (RFC 9449)

DPoP (Demonstrating Proof of Possession) per RFC 9449 enables the TsgcHTTP_OAuth2_Server to require sender-constrained tokens. When DPoP is enabled, the server validates DPoP proof JWTs, binds tokens to the client's JWK thumbprint, and returns token_type: DPoP instead of Bearer.

OAuth2Server := TsgcHTTP_OAuth2_Server.Create(nil);
// Enable DPoP
OAuth2Server.OAuth2Options.DPoP := True;
// Register app
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;
// Custom DPoP validation
procedure TForm1.OAuth2ServerOAuth2ValidateDPoP(Sender: TObject;
  const DPoPProof, AccessToken, Method, URL: String; var Valid: Boolean);
begin
  // Additional custom checks
  Log('DPoP proof validated for: ' + Method + ' ' + URL);
  Valid := True; // Set to False to reject the request
end;

TsgcHTTP_OAuth2_Server *OAuth2Server = new TsgcHTTP_OAuth2_Server(this);
OAuth2Server->OAuth2Options->DPoP = true;
OAuth2Server->Apps->AddApp("MyApp", "http://127.0.0.1:8080",
  "my-client-id", "my-client-secret", 3600, true,
  TsgcOAuth2GrantTypes() << auth2Code);
Server->Authentication->Enabled = true;
Server->Authentication->OAuth->OAuth2 = OAuth2Server;
void __fastcall TForm1::OAuth2ServerOAuth2ValidateDPoP(TObject *Sender,
  const UnicodeString DPoPProof, const UnicodeString AccessToken,
  const UnicodeString Method, const UnicodeString URL, bool &Valid)
{
  Log("DPoP proof validated for: " + Method + " " + URL);
  Valid = true;
}

var OAuth2Server = new TsgcHTTP_OAuth2_Server();
OAuth2Server.OAuth2Options.DPoP = true;
OAuth2Server.Apps.AddApp("MyApp", "http://127.0.0.1:8080",
  "my-client-id", "my-client-secret", 3600, true,
  new TsgcOAuth2GrantType[] { TsgcOAuth2GrantType.auth2Code });
Server.Authentication.Enabled = true;
Server.Authentication.OAuth.OAuth2 = OAuth2Server;
OAuth2Server.OnOAuth2ValidateDPoP += (sender, dpopProof, accessToken, method, url, ref valid) =>
{
  Console.WriteLine("DPoP proof validated for: " + method + " " + url);
  valid = true;
};

5 · Device Authorization Grant (RFC 8628)

The Device Authorization Grant is designed for input-constrained devices (smart TVs, IoT devices, CLI tools) that cannot easily display a browser or accept keyboard input. The TsgcHTTP_OAuth2_Server provides a device authorization endpoint and a verification page so that users can authorize the device from a secondary device such as a phone or computer.

OAuth2Server := TsgcHTTP_OAuth2_Server.Create(nil);
// Enable device authorization
OAuth2Server.OAuth2Options.DeviceAuthorization.Enabled := True;
OAuth2Server.OAuth2Options.DeviceAuthorization.ExpiresIn := 600;
OAuth2Server.OAuth2Options.DeviceAuthorization.Interval := 5;
// Register app
OAuth2Server.Apps.AddApp('DeviceApp', '',
  'device-client-id', 'device-client-secret', 3600, True,
  [auth2Code]);
Server.Authentication.Enabled := True;
Server.Authentication.OAuth.OAuth2 := OAuth2Server;
// Handle device code verification
procedure TForm1.OAuth2ServerOAuth2DeviceCodeVerification(Sender: TObject;
  const UserCode: String; var Authorized: Boolean);
begin
  // Validate the user code and authorize the device
  Authorized := True;
end;
procedure TForm1.OAuth2ServerOAuth2AfterAccessToken(Sender: TObject;
  const Token, RefreshToken: String; ExpiresIn: Integer);
begin
  Log('Device authorized. Token: ' + Token);
end;

TsgcHTTP_OAuth2_Server *OAuth2Server = new TsgcHTTP_OAuth2_Server(this);
OAuth2Server->OAuth2Options->DeviceAuthorization->Enabled = true;
OAuth2Server->OAuth2Options->DeviceAuthorization->ExpiresIn = 600;
OAuth2Server->OAuth2Options->DeviceAuthorization->Interval = 5;
OAuth2Server->Apps->AddApp("DeviceApp", "",
  "device-client-id", "device-client-secret", 3600, true,
  TsgcOAuth2GrantTypes() << auth2Code);
Server->Authentication->Enabled = true;
Server->Authentication->OAuth->OAuth2 = OAuth2Server;
void __fastcall TForm1::OAuth2ServerOAuth2DeviceCodeVerification(TObject *Sender,
  const UnicodeString UserCode, bool &Authorized)
{
  Authorized = true;
}
void __fastcall TForm1::OAuth2ServerOAuth2AfterAccessToken(TObject *Sender,
  const UnicodeString Token, const UnicodeString RefreshToken, int ExpiresIn)
{
  Log("Device authorized. Token: " + Token);
}

var OAuth2Server = new TsgcHTTP_OAuth2_Server();
OAuth2Server.OAuth2Options.DeviceAuthorization.Enabled = true;
OAuth2Server.OAuth2Options.DeviceAuthorization.ExpiresIn = 600;
OAuth2Server.OAuth2Options.DeviceAuthorization.Interval = 5;
OAuth2Server.Apps.AddApp("DeviceApp", "",
  "device-client-id", "device-client-secret", 3600, true,
  new TsgcOAuth2GrantType[] { TsgcOAuth2GrantType.auth2Code });
Server.Authentication.Enabled = true;
Server.Authentication.OAuth.OAuth2 = OAuth2Server;
OAuth2Server.OnOAuth2DeviceCodeVerification += (sender, userCode, ref authorized) =>
{
  authorized = true;
};
OAuth2Server.OnOAuth2AfterAccessToken += (sender, token, refreshToken, expiresIn) =>
{
  Console.WriteLine("Device authorized. Token: " + token);
};

6 · OAuth2 | Customize Sign-In HTML

When an OAuth2 client do a request to get a new Access Token, a Web-Page is shown in a web-browser to Allow this connection and login with an User and Password.

procedure OnOAuth2BeforeDispatchPage(Sender: TObject; OAuth2: TsgcHTTPOAuth2Request; var HTML: string);
begin
HTML := 'your custom html';
end;

void OnOAuth2BeforeDispatchPage(TObject *Sender; TsgcHTTPOAuth2Request *OAuth2; ref string HTML)
{
HTML = "your custom html";
}

void OnOAuth2BeforeDispatchPage(TObject Sender; TsgcHTTPOAuth2Request OAuth2; ref string HTML)
{
HTML = "your custom html";
}

Sources used to build this document

Every external claim links back to a primary source. The online-help references decode the canonical deep-link the company maintains for this component.