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 to http://+:2001/tms/sphinx.
• Config: set to SphinxConfig1.
• Dispatcher: set to SparkleHttpSysDispatcher1.

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 to AureliusConnection1.
• ModelNames: set to Biz.Sphinx.

Select SphinxServer1 component and set the following properties using the object inspector:

• Pool: set to XDataConnectionPool1.

Select XDataConnectionPool1 component and set the following properties using the object inspector:

• Connection: set to AureliusConnection1.

Select AureliusConnection1 component and set the following properties using the object inspector:

• DriverName: set to SQLite.
• Params: add a line EnableForeignKeys=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 to desktop.
• AllowedGrantTypes: set the gtAuthorizationCode item to True.
• RedirectUris: add line http://127.0.0.1.
• RequireClientSecret: set to False.
• ValidScopes: add lines openid and email.
• RequirePkce: set to False (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 to False (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 shared secret used for signing the JWT');
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 to http://localhost:2001/tms/sphinx.
• ClientId: set to desktop.
• Scope: set to openid 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.