Quickstart
A typical use case for Sphinx is to have a Single Sign-On (SSO) server which you can use to authenticate users to your applications. In this section we will provide you with the basic steps to have such server running.
Note that many concepts and steps provided here are actually related to libraries that Sphinx relies on, like TMS Aurelius and TMS Sparkle. You can refer to the documentation of such libraries to better understand the concepts and steps described here.
Setting up Sphinx server
Let's just create and launch a Sphinx server:
Create a new Delphi VCL application.
In the newly created form, drop the following components:
TSparkleHttpSysDispatcher
- TSphinxServer
- TSphinxConfig
Using the object inspector, set the following properties for the TSphinxServer
component:
BaseUrl
: set tohttp://+:2001/tms/sphinx
.Config
: set toSphinxConfig1
.Dispatcher
: set toSparkleHttpSysDispatcher1
.
Double-click the form to create an OnCreate
event handler and add the following code:
procedure TForm1.FormCreate(Sender: TObject);
begin
SparkleHttpSysDispatcher1.Active := True;
end;
We can now check if our server is running. Execute the application, open your internet browser and navigate to address http://localhost:2001/tms/sphinx/.well-known/openid-configuration>. The browser should display the server response which will be a JSON similar to this one:
{
"issuer": "http://localhost:2001/tms/sphinx/",
"authorization_endpoint": "http://localhost:2001/tms/sphinx/oauth/authorize",
"token_endpoint": "http://localhost:2001/tms/sphinx/oauth/token",
"response_types_supported": [
"code",
"id_token",
"id_token token"
]
}
If you get the JSON response, congratulations! The server is running and we can now proceed to the next steps.
Note
Sphinx server is nothing more than a TMS Sparkle module. You can refer to TMS Sparkle documentation to learn more about how to create different Sparkle applications (console, Windows service, Apache) and how to properly configure and deploy it.
Creating and configuring the database
Sphinx needs a storage to persist users, roles, passwords, login sessions, clients, etc. For that it uses TMS Aurelius ORM framework to easily create a database and save data to it. By using Aurelius, Sphinx gives you plenty of choices for the database system to use: PostgreSQL, MySQL, MS SQL Server, Oracle, and many others. You can also use any of your preferred database-connection components: FireDAC, UniDAC, dbGO, etc.
In this example we will use an SQLite database file using Aurelius native driver.
Drop the following components in the form:
TAureliusConnection
TAureliusDBSchema
TXDataConnectionPool
Select AureliusDBSchema1
component and set the following properties using the object inspector:
Connection
: set toAureliusConnection1
.ModelNames
: set toBiz.Sphinx
.
Select SphinxServer1
component and set the following properties using the object inspector:
Pool
: set toXDataConnectionPool1
.
Select XDataConnectionPool1
component and set the following properties using the object inspector:
Connection
: set toAureliusConnection1
.
Select AureliusConnection1
component and set the following properties using the object inspector:
DriverName
: set toSQLite
.Params
: add a lineEnableForeignKeys=True
to the string list.
Modify the FormCreate
event handler to be as the following:
procedure TForm1.FormCreate(Sender: TObject);
begin
AureliusConnection1.Params.Values['Database'] := ChangeFileExt(ParamStr(0), '.db');
AureliusDBSchema1.UpdateDatabase;
SparkleHttpSysDispatcher1.Active := True;
end;
The first added line configured the SQLite database file location (the same folder and file name as the application executable, but with the .db
extension). The second added line updated the database structure by creating the tables and columns needed by TMS Sphinx.
The database setup is finished. When we run the application, the SQLite database file will be created (you can check it in the same folder as the application executable) and the needed tables will be created in the database.
Registering a client application
Sphinx relies on OAuth protocol, which presents the concept of a client. According to the OAuth specification, a client is "an application making protected resource requests on behalf of the resource owner and with its authorization". In other words, the client is an application that gets authorization to access something.
Usually clients are web, mobile, desktop, or even server applications. For them to interact with a Sphinx server, they need to be registered as client applications. The settings of such client will slightly vary depending exactly on the type of application that will access the server, because each of them will use a different grant type.
In this tutorial we will register a client for a desktop application. Select the SphinxConfig1
component and double click the Clients
property in the object inspector.
A new window titled Editing SphinxConfig1.Clients
is displayed. Press Ins
key or click the Add New
button to create a new client.
A new TSphinxClientApp object will be created and automatically selected in the object inspector. You can then modify the following properties:
ClientId
: set todesktop
.AllowedGrantTypes
: set thegtAuthorizationCode
item toTrue
.RedirectUris
: add linehttp://127.0.0.1
.RequireClientSecret
: set toFalse
.ValidScopes
: add linesopenid
andemail
.RequirePkce
: set toFalse
(See Warning note below).
Warning
The property RequirePkce
was set to False
to make this tutorial easier to follow. In production environment, it reduces security, therefore only disable it if you really need it.
Select the SphinxConfig1
component again and set the following properties:
LoginOptions.RequireConfirmedEmail
: set toFalse
(See Warning note below).
Warning
The property RequireConfirmedEmail
was set to False
to make this tutorial easier to follow. Only disable it if you really intend to allow new users to register themselves without confirming their e-mail address.
As a final step, double-click the OnGetSigningData
event and add the following code to the created event handler:
procedure TForm1.SphinxConfig1GetSigningData(Sender: TObject; Args: TGetSigningDataArgs);
begin
Args.Data.Key := TEncoding.UTF8.GetBytes('This is the secret for JWT signing');
end;
Warning
Never keep real secrets in source code. This is for this tutorial purpose only. In real applications you should load your secrets from different sources, like config files, system environment variables, databases...
Run the application, and try to navigate to the following URL using your internet browser: http://localhost:2001/tms/sphinx/oauth/authorize/?client_id=desktop&response_type=code&scope=openid&redirect_uri=http://127.0.0.1.
You should then see the login form being displayed:
You can play around with the login page, but to properly complete the login you will need to handle the redirect callback URL. In the next section we will do that in a desktop application with the help of TSphinxLogin
component.
Authorizing from a desktop application
Let's now create a desktop VCL application that uses our Sphinx server to allow users to login.
Create a new Delphi VCL application.
Drop the following components in the form:
TSphinxLogin
TButton
TMemo
Select SphinxLogin1
component and set the following properties using the object inspector:
Authority
: set tohttp://localhost:2001/tms/sphinx
.ClientId
: set todesktop
.Scope
: set toopenid email
.
Double-click the OnUserLoggedIn
property to create an event handler and type the following code:
procedure TForm2.SphinxLogin1UserLoggedIn(Args: TUserLoggedInArgs);
begin
Memo1.Lines.Add('User ' + Args.LoginResult.Profile.Email + ' logged in.');
end;
Finally, double-click the button and add the following code to the OnClick
event handler:
procedure TForm2.Button1Click(Sender: TObject);
begin
SphinxLogin1.Login;
end;
Run the application (make sure the server application is still running) and click the button to login. Your default internet browser should open and display the login page.
You can now register yourself as a new user, and then use such user to login. After the login the browser should display a message that authorization was successful and you could close the browser and go back to the application.
In the VCL application the memo component should now display a message informing that your user is logged in:
User foo@foo.com logged in.
Congratulations! You have built your first server and client application using TMS Sphinx.