Authorizing web applications

This chapter explains with more details the process of configuring Sphinx server to authenticate/authorize web applications.

First things first, make sure you have followed the Quickstart chapter thoroughly. It describes the common procedures to setup Sphinx. This chapter just extends what's explained there, with more information that targets web applications specifically.

Registering a client application

After the server component is setup and database is created, you need to register the client application in Sphinx configuration.

Client applications should be added to TSphinxConfig component using the TSphinxConfig.​Clients property. You can do it at design-time, by double-clicking the Clients property, or from code, calling Clients.Add. In either case, a new TSphinxClientApp will be created.

Fill in the properties of the added TSphinxClientApp object to properly configure the client application. Please refer to TSphinxClientApp reference for a full list of available properties.

At the very least, for any type of client application you create, you should set the TSphinxClient​App.​ClientId property. It uniquely identifies the client, and it is used from the client applications to identify themselves when invoking Sphinx authorization server.

Other commonly used properties are TSphinxClient​App.​Display​Name and TSphinxClient​App.​Valid​Scopes.

The following is an example of how to register a web client application from code. The same properties can be set using the object inspector at design-time.

  Client := SphinxConfig1.Clients.Add;
  Client.ClientId := 'web';
  Client.DisplayName := 'My web app';
  Client.RedirectUris.Add('http://localhost:2001/tms/WebClient/');
  Client.RequireClientSecret := False;
  Client.AllowedGrantTypes := [TGrantType.gtAuthorizationCode];
  Client.ValidScopes.Add('openid');
  Client.ValidScopes.Add('email');

Properties ClientId and DisplayName simply identify the client application.

The URL http://localhost:2001/tms/WebClient/ is added to the RedirectUris property. This is the URL of the web application itself. It's the responsibility of the web application to properly handle the redirect URL parameters sent by the Sphinx server.

A web application is a public application, that's why RequireClientSecret should be set to false. No client credentials should be available from the web application.

The grant type used should be gtAuthorizationCode. Another option would be gtImplicit, but the former is a newer, more secure method that should be preferred over implicit grant type. By default Sphinx uses authorization code with PKCE so it will require PKCE for the authentication.

Finally, OpenID Connect scopes openid and email are added to the ValidScopes property, so information about the logged user is provided back to the web application when the login is finished.

Authenticating from web applications

Now the server is prepared to authenticate any type of web application, written in any language. With the above client configuration, you can authorize your web application by using the OAuth 2.0 Authorization Code Flow with Proof Key for Code Exchange (PKCE).

The Sphinx server will publish the authorization endpoint at <base_url>/oauth/authorize URL, and the token endpoint at <base_url>/oauth/token URL. Send an OAuth 2 authorization request to the authorization endpoint to obtain an authorization code, and then send a token request to the token endpoint to obtain the identity and access tokens upon the provide of the authorization code.

Authenticating from TMS Web Core applications

If your web application is built with TMS Web Core, then TMS Sphinx already provides a high level component TSphinxWebLogin that will abstract all the grant flow for you and make it even easier to authenticate.

Drop the TSphinxWebLogin component in any form or data module in your application so that it's accessible when the application starts.

You should then configure it setting the following key properties:

  • Authority: Should have the base URL of the Sphinx server. For example, http://localhost:2001/tms/sphinx.
  • ClientId: The id of the client you've just previously registered.
  • RedirectUri: The URL of the web application itself.
  • Scope: Spaced-separated list of scope tokens. At the very least, you should include openid email. If your web application also communicates with a XData server that needs access tokens, then you should also include the needed scopes for the API, if needed.

Once the component is configured with the above properties, you can use some of its methods to implement the login workflow:

  • Use the IsLoggedIn method to check if the user is already logged in the application.
  • Use the Login method to initiate the login. User will be redirected to the Sphinx login page, where he should authenticate. Once the authentication is completed successfully, user will be send again to the URL specified in the RedirectUri (the web application itself) and the login component will continue the authorization process by requesting the identity and access tokens. The TSphinxWebLogin.​OnUser​LoggedIn event will be fired when the login is successful.
  • Use the Logout method to clean the existing credentials and log out the user from the application.

If the user is logged in, you can check the TSphinxWebLogin.​Auth​Result property to retrieve detailed information about the logged user, like e-mail, name, among other information.

Installing in Web Designer

TMS Web Core provides a new WYSIWYG web designer that you can optionally enable/disable to use it. If you don't use (i.e., use the regular Delphi designer), all the Sphinx components for Web Core will be already available in the component palette to be used.

But if you have enabled the Web Core Web Designer, you need extra steps to install Sphinx components to it and made them available in component palette.

To do that, you need to open, build and install the package files of BIZ products created specifically for Web Core. The package files are available in the product folder, under the subfolder packages\webcore.

You need to install the packages for the following products, in this order:

  • TMS BCL (package bclweb.dproj)
  • TMS Sparkle (package sparkleweb.dproj)
  • TMS XData (package xdataweb.dproj)
  • TMS Sphinx (package sphinxweb.dproj)

For example, suppose you have installed BIZ products using TMS Smart Setup, and your Smart Setup root folder is at C:\SmartSetup. The package files you need to build and install would be:

  • C:\SmartSetup\Products\tms.biz.bcl\packages\webcore\bclweb.dproj
  • C:\SmartSetup\Products\tms.biz.sparkle\packages\webcore\sparkleweb.dproj
  • C:\SmartSetup\Products\tms.biz.xdata\packages\webcore\xdataweb.dproj
  • C:\SmartSetup\Products\tms.biz.sphinx\packages\webcore\sphinxweb.dproj

Once you install those packages in Web Core environment, the Sphinx components for Web Core will be available in the Web Designer.