Thursday, June 22, 2017

Managing Credential Sets and Parameters: A Simple Delphi Value List Editor Component

The Problem

I am frequently called on to develop a solution that accesses a database or cloud service. During development the best practice is to develop using a test bed or "sandbox" to avoid potentially devastating real client data. This necessarily implies at least two sets of credentials to access the needed information: test and production. Sometimes, there are more than two, depending on the project requirements.

Additionally, some of the tools I develop have a general applicability, which is to say I may be able to employ the same solution for more than one client. This means even more sets of credentials as the tool is applied to additional client data.

Add to this some of the complexity inherent in credentials—and I'm thinking specifically of something like OAuth2 that has numerous data items from client IDs, to secret keys, redirection endpoints and so forth—and just managing multiple sets of credentials becomes tedious and error prone.

Further, it would be nice if changes to credential sets (or parameters sets or any other kind of set that might be fluid) could be made a run time rather than having to modify source code and recompile an application. 

The Solution

The first thing that comes to mind is to use a Value List Editor component to make it easy to manage credential sets. This is a good start, but something more is needed to make it truly convenient to implement as well as run-time friendly.

The solution I came up with is a simple Delphi component called TGetCredentials, that displays a dialog that permits management of credential sets stored in a .ini file and allows their creation, retrieval, update and deletion (CRUD) using a set of intuitive buttons.

TGetCredentials Component

The dialog GUI looks like this example, that might be used to manage credentials for accessing a Google API:

The desired set is chosen from the Drop-down Combo Box that retrieves the set from a .ini file and displays the contents. The set can then be modified or in other ways manipulated if desired. Finally, the user may cancel the retrieval (the dialog returns mrCancel) or elect to use the current values (the dialog returns the newly selected credentials along with mrOK).

.ini File

The .ini file is a standard .ini file; i.e., a text file divided into a number of sections that are named by a section header enclosed in brackets and followed by any number of name=value pairs.

The full path and filename of the .ini file is specified by associated component properties. The file must be manually created in the specified location and it must be populated with at least one section named *model. *model is used to create new credential sets; whatever the contents of *model, those are copied to the new credential set. By basing the credential sets on a programmer specified model section you may specify any items in the set as desired.

Using the Component

The TGetCredentials component can be downloaded from GitHub:


More extensive documentation on using the component is available in the Doc folder of the project. The contents of the .chm file (MS Help) and the .pdf are identical; either may be selected.

Download the Component

You may either download a .zip file with the project or clone the project using one of the several available Git tools. If you download the .zip file, you must unzip the project to use the contents (which require compilation and installation.)

Using the Component

More comprehensive documentation about using the component is contained in either of the two documentation files in the Doc folder. In general:
  • Compile the .bpl projects.
  • Install the design time project.
  • Launch your own project that will utilize the component.
  • Drop the TGetCredentials component on a form.
  • Configure the TGetCredentials component appropriately.
  • Create the .ini file (including the *model section) to match the specification you made in the TGetCredentials component properties.
  • Use the appropriate methods in the TGetCredentials component to display the dialog, retrieve the desired credential sets, and incorporate the retrieved values into your own code.


The TGetCredentials component is offered at no charge and has no guarantees. You are responsible for ensuring correct results and I offer no guarantees of any kind.

Feel free to leave comments and corrections here.

Thanks for visiting.

Tuesday, May 23, 2017

Delphi OAuth2 Authenticator Component for Google

Delphi OAuth2 Authenticator Component for Google
Encapsulating a Perennially Irritating Task
  1. Reference

Links and comments are current as of May 23, 2017. Programming for Google is really like trying to hit a moving target with a bow and arrow. You may have to hunt around a bit to find what you’re looking for if you come across this blog a year or so from now.
  1. Component Code

The project that contains the component is available under the MIT License from Please note some caveats:
  • No guarantees. Your risk.
  • The code has only been developed and tested using a VCL 32-bit application. It should work for Windows 64-bit, but I’ve never tried it.
  • With additional work, you might get this to work for Android and OS X.
  • FireMonkey is not currently supported. This is because the component instantiates a TWebBrowser component that is VCL-only. Additional code can probably extend the component for use with FireMonkey as well.
This is pretty much alpha level code, with lots of features yet to be added. If I ever need to, I may add them but right now I don’t plan on doing more work on this.
  1. Overview

Every time I need to write code to access a Google REST API I’m faced with the same tedious and error-prone task of coding the OAuth2 Authentication routines I need to gain access. The basic steps are:
  1. Determine all of the various endpoints, URIs, and other constants that Google requires for its implementation of OAUTH2. OAUTH2 is not really a protocol, but rather an “architectural style” so Google’s ideas are generally somewhat different from those of, say, Facebook or Twitter.
  2. Set up the target Google account to accept the necessary REST calls. This involves enabling the needed APIs (if not already enabled) and registering your application to obtain needed Client ID and Client Secret.
  3. Code the requisite browser object, provision it with the proper URL (concocted of many of the things mentioned previously), allow the user to authenticate and authorize your app for access, and finally scraping the reply screen for the needed Access and Refresh Tokens along with an Access Token expiry interval.
Adding to the confusion is the Embarcadero provided REST Debugger that sort of kludges together a bunch of different “architectural styles” from a variety of websites into a single monolithic blob of code that only a mother could love.
The DocWiki for RAD Studio Berlin is a much better source of information about the REST Client Library. See REST Client Library. The DocWiki suggests with reference to TOAuth2Authenticator: “Because of the heavy dependencies to the service providers, a generic component like this can only give some support and provide the infrastructure to follow the workflow of the service provider. You might want to inherit from this class to create an authenticator class specific to a service provider.”
That sounded like a pretty good idea to me, so that’s what the rest of this post is about. It’s actually pretty easy to do once you collect all of the detritus needed for creating the code.
  1. Finding Information and Preparing Google

    1. URIs and Endpoints

The easiest part of all of this is downloading Google's Well-Known Open ID Configuration. It has a couple of things you’ll need like the authorization-endpoint and token-endpoint. You’ll also want to take a look at OAuth 2.0 for Mobile & Desktop Apps. Scroll down to the redirect-uri values section, Manual copy/paste subsection. It says simply urn:ietf:wg:oauth:2.0:oob.You’ll need that later.
    1. Scopes

You’ll also need whatever API Scopes you intend to access. Visit OAuth 2.0 Scopews for Google APIs for a dazzling array of choices. You can use one or more than one in your application. When specifying multiple scopes they are separated by a space.
    1. Create a Project or Use an Existing Project

First, you’ll need to visit Google API Manager while you’re logged on as an administrator of the target Google Account. There’s a little obscure reveal-triangle near the top left of the screen. If you click that you can choose from an existing project or create a new one. If you create a new project you’ll be asked to give it a name.
    1. Enable the API(s) You Need

Next, choose the Dashboard menu item on the left and then click Enable API. This will reveal yet another dazzlilng array of choices. Click on the API you plan on using to display more information about the API. To enable the API for your project, click Enable at the top of the screen.
    1. Obtain Your Credentials

Click on the Credentials menu item to the left. If you plan on using credentials already created, simply click on the desired name I the OAuth 2.0 client IDs column. To create a new set of credentials, click the Create credentials button.
You can also delete credential sets if you decide you want to disable all access using the deleted set. If you lose your credentials, you can always return to this page to obtain them again.
    1. What’s Missing?

You should now have all the information you need to Authenticate your Google app. What’s missing? Actually, we haven’t talked at all about the REST requests you’ll need to make to get your app to do useful work. For a list of Google APIs, visit Google APIs Explorer. The possibilities are staggering and well beyond the scope of the present post. It is assumed that you know what you want to accomplish, and it’s simply a matter of making the proper requests to the appropriate Google API.
  1. Using TOAuth2AuthenticatorGoogle

    1. Configuring the Components

Drop the following objects on a form: (A data module works well.)
  • TRESTClient
  • TRESTRequest
  • TRESTResponse
  • TOAuth2AuthenticatorGoogle
  • TRESTResponseDataSetAdapter (Optional if you want to convert the response JSON to a dataset.)
  • TFDMemTable (Optional if you want to convert the response JSON to a dataset.)
Connect the components in the customary fashion. Configure your TRESTRequest to make the appropriate request for what you intend to accomplish. The DocWiki page REST Client Library has some excellent points about TRESTClient and TRESTRequest. Give some attention to properly configuring the following properties:
  • Base URL (TRESTClient)
  • Resource (TRESTRequest)
  • URL Segment Parameters (TRESTRequest) that make “substitutions” in the query string
  • Other parameters (TRESTRequest)
  • Cookie Parameters
Finally, be sure to configure TOAUTH2AuthenticatorGoogle correctly. The properties you should already have if you have followed all of the steps above are:
  • AccessTokenEndpoint
  • ClientID
  • ClientSecret
  • LoginHint (this is a Google feature and if you know your anticipated username for the authentication, specifying it in this parameter will help speed the authentication along)
  • RedirectionEndpoint—remember urn:ietf:wg:oauth:2.0:oob? Here’s where it goes.
All other properties can be left at their default values. Please note, the AccessToken property is used by the component to decide whether OAuth2 must be used when the RESTRequest is made. Leave it blank and OAuth2 will be invoked to fill it in. To force your app to reauthenticate, set this property to blanks and it will reauthenticate at the next request.
    1. Invoking Authentication

Authentication is not a separate step using this component. It is an automatic part of making a REST Request. Thus, in order to authenticate, you must have a valid REST Request configured. For example, you might want to retrieve a list of G Suite Users. To do this, configure the Authenticator properties with the necessary endpoints for authentication and also configure the TRESTClient and TRESTRequest to make the customary API request for users. Then invoke the Request: e.g., YourRESTRequest.Execute; authentication is an automatic precursor to executing the API request.
    1. Component Code

Component code is straightforward. If you download the code from GitHub you can easily follow the explanation that follows:
      1. Procedure DoAuthenticate; override;

This is the control routine for authentication. When a REST Request is made (for example, for a list of G Suite Users) this routine handles necessary authentication. After authentication, normal processing is resumed using the inherited keyword.
      1. Procedure WebFormTitleChanged

This is an event handler for the TWebBrowser object that is instantiated to prompt the user for authorization. It scans the title string for the authorization code returned by Google. Upon finding the code, it saves the code and closes the Web Browser.
      1. ProcedureGetAuthCodeGoogle

This routine instantiates a TWebBrowser, builds the appropriate URL, and then displays the Web Browser with the URL that causes the appropriate authentication request to be made to Google. The user then interacts with the response, and if the request is approved, Google returns an authorization code that is extracted by WebFormTitleChanged.
      1. ProcedureGetTokensGoogle

This is the final step in OAuth2 Authentication. After the authorization code has been obtained successfully, DoAuthenticate invokes this routine that builds a TRESTClient object and a TRESTRequest object. The Request parameters ask to exchange the authorization code for the Access Tokens and Token Expiry. If successful, the Response contains the tokens and expiry interval in seconds. These are extracted and appropriately stored for later use. Note that it is not necessary to construct a Response object; if none is specified in the Request object, the Response is created automatically.
  1. Conclusion

For me, OAuth2 is a major distraction from actually getting an application to run. This somewhat trivial component has helped me to organize my efforts and get on with the real point of my development efforts.
I hope it helps you, as well.
Comments and corrections welcomed.

Sunday, January 22, 2017

A Guide to Implementing Multifactor Authentication
Website Design and Implementation

Overview of Multifactor Authentication

    1. General Description

Multifactor Authentication increases website security by asking the user to provide two out of three possible authentication credentials:
  1. Something the user knows. (Typically this is the password.)
  2. Something the user has. (This can be some sort of device, such as a fob or key or a cell phone. Most commonly a cell phone is the designated device and that is what this paper will address.)
  3. Something the user is. (This typically means some sort of biometric such as a finger print or retinal scan. Because these are not commonly employed except in very high security settings and because they are expensive to implement, this factor will not be discussed in the present document.)
Multifactor Authentication is commonly referred to as Two Factor Authentication (TFA or 2FA) although Facebook calls it “Login Approvals” while Google refers to it as “2-Step Verification.”
    1. User Experience

When TFA is enabled by a website the username and password are initially verified; this is followed by an additional request by the server for a six-digit access code. This code is generated using a shared secret known to both the server and the user. If the user enters the correct code, authentication succeeds and the user is granted access, otherwise the authentication fails and the user is denied access.
Access codes are valid for short time periods, generally 30 seconds. Thus the user needs a way to determine the current access code value for very small time windows. This is typically accomplished by either sending the user the current code via SMS or by using a mobile application. The mobile application approach is considered the best practice.
    1. Developer Experience

Developers faced with the task of either implementing a new website or upgrading an existing website with TFA are faced with some additional considerations. First, they must provide for the routes and processing of the TFA user request and response. They must also expand their current persistent data stores to accommodate additional user information needed by TFA. Determination of the current access code for validation purposes is non-trivial and a source for potential error. Finally, an enrollment process needs to be developed that will involve a number of routes and screens; this enrollment permits the user to activate TFA and exchange the secret key required to generate access codes with the server.
All of these tasks can be mitigated by using standard libraries or code examples that are readily available on the Internet.
    1. Security Considerations

Some implementations include a feature similar to Google’s “app passwords.” This is because some desktop and mobile applications cannot respond to requests for an access code; an example might be Microsoft Outlook or Mozilla Thunderbird attempting to access a Gmail account. Special passwords are provided for these kinds of applications to permit them to log on successfully. App passwords are a serious breach of security. No viable solution to this problem has yet been presented.
A serious security flaw involves the password recovery process typically implemented by websites that require a login. Since password recovery takes place completely apart from TFA, any additional security protections provided by TFA are completely bypassed providing hackers with an opportunity for successful penetration.
  1. Detailed Considerations

    1. Framework

This document makes frequent reference to Google’s implementation of TFA. It is assumed that this reflects the intended implementation by the reader. If some other implementation is envisioned, modifications may be required although the general methodology will remain the same. The general basis for this methodology is RFC 6238 ad RFC 3548 that should be used as a guide for any implementations.
    1. Logon Flow

The website logon flow is illustrated by the following diagram. It begins when the user contacts the website login page and concludes when access is granted.
User sends GET request to webserver

Webserver responds with login page
User provides username and password and sends POST request to webserver

If the user has been set up to receive six-digit codes via SMS, Webserver sends six-digit code to user via SMS. Otherwise this step is skipped.

Webserver sends page requesting six-digit code
If the user has been set up to receive six-digit codes via SMS, user retrieves code from SMS message. Otherwise, user determines correct six-digit code by using the Google Authenticator App (or another equivalent third-party app.)

User provides the six-digit code and sends POST to the webserver.

Webserver receives the six-digit code. If the code is validated, user is granted access and webserver returns appropriate web page. If the code fails validation, webserver returns the page requesting the six-digit codes decorated with an appropriate error message.
User proceeds with website access or, in the case of an error, retries the six-digit code

    1. Password Algorithm

The most common algorithm, used by Google and other major websites, is called Time-based One-time Password Algorithm (TOTP). TOTP is based on another algorithm called HOTP or HMAC-based One-time Password Algorithm. The only difference between the two is that HOTP uses a counter that is incremented and used in the generation of the key while TOTP replaces the counter by referencing the device timestamp. There is a secret key shared by the server and the client (user) that along with the current timestamp and agreed upon parameters is used to generate the six-digit code used for authentication.
The parameters are generally the following. If the implementation elects to use an application such as Google Authenticator to determine the correct codes, then both the server and the client (user) must implement the same values for authentication to succeed.
  • Secret Key
  • Epoch (Default is Unix epoch)
  • Time Interval that is the length of time a particular code remains valid. When the time interval expires the code becomes invalid and a new code is generated. (Default value is 30 seconds.)
  • Cryptographic Hash Method. This is used during code generation. (Default is SHA-1.)
  • Token Length (Default is six.)
A special note for Google implementation is that Google does not support parameters that are not defaults. Further, Google expects the secret key to be entered in base-32 encoding.
Since the six-digit code is determined by the agreed-upon parameters and the secret key, anyone can generate a currently correct code by using these parameters and assuming they know the correct time. Thus it becomes important for users who elect to use Google Authenticator or any similar app to ensure their phone has the correct time. Normally, this is handled transparently by the phone operating system. The server will likewise have access to an NTP server and know the correct time.
Regardless of the method used to receive six-digit codes (SMS or Google Authenticator) there is the possibility that a code will expire prior to the user’s ability to enter and return it. There is also a possibility for some time variance. For these reasons, most servers are programmed to accept the current value, the previous two time-period values, and the next two time period values, for a span of five time periods. Greater spans are possible with a corresponding reduction in security.
    1. Setup

The setup for a user enrolling in TFA is similar to the Logon Flow above. However, the process begins with the user requesting enrollment by enabling TFA at the website. If the user indicates that he wishes to use the Google Authenticator app, the website presents a QR code that can be read by the app to complete the exchange of the secret key and establish an entry in the Google Authenticator database on the user’s cell phone. If the user has elected to receive codes via SMS the Authenticator steps are bypassed. The website requests that the user enter a current six-digit code in order to test the setup. (An incorrect setup can lock a user out of the system, so it is important to test the setup prior to actual activation.) The correct code is either sent to the user via SMS (if SMS has been elected) or the user launches the Authenticator application to obtain the currently correct access code. If the user returns the correct code the enrollment process is completed and further logons will be performed using TFA. An error in the test validation will result in additional opportunities for the user to correctly enroll.
    1. Enforcement

Enforcement of TFA is a function of website programming. If TFA is being implemented by a website where the source code is under the control of your developers, then suitable design will ensure that users must always employ TFA or be denied access.
Google users must enroll themselves in TFA. Google recommends a two to four week period to give all users time to enroll themselves in TFA. By using the administrator setting Turn on enforcement from date, Google will remind users they need to enroll each time they log in and they will receive periodic reminder emails. On the ending date specified, users who are not enrolled will be denied access until they enroll.
It is also possible to place users in groups so that some G Suite users are required to enroll while others may not be. Google presents a comprehensive guide to setting up 2-Step Verification at
    1. Google Exceptions

Desktop and mobile applications that access G Suite resources are not able to enter six-digit codes. A primary example of this might be Outlook attempting to access a Gmail account. To accommodate this circumstance, users can set up special App Passwords to be used in place of their regular passwords on the impacted desktop or mobile application.
In some cases Google may determine that the application is not secure enough and may block login attempts from the Mail app on iPhone or iPad with iOS 6 or below. Also some instances of Microsoft Outlook and Mozilla Thunderbird.
Google presents a more complete discussion of this topic at
Note: Application Specific Passwords (ASP) severely compromise the security of G Suite since they completely bypass TFA. ASP in fact do not provide application limited access (since Google has no idea which desktop or mobile app you may be using for access.) In fact, ASP provide access to nearly all G Suite functionality.
    1. Salesforce

Salesforce also implements TFA. The details of the Salesforce implementation are different from Google. Salesforce also has its own Salesforce Authenticator. Details of the Salesforce approach can be found at There are also three Trailheads (Salesforce tutorials) listed that provide training for Administrators in User Authentication, Security Basics and Identity Basics.
    1. Two Factor Authentication on User Developed Websites

Any website can implement TFA. From the preceding discussion it can be seen that this is a nontrivial task. The website will have to implement authentication routines that require a username and password at bare minimum. These will have to be stored persistently (e.g. in a database) to be useful. Adding TFA entails the initialization functions of enrollment, the exchange of a secret key, preferably by QR code (if an app like Google Authenticator is planned) or provision for the automatic transmission of the access code by SMS if that is chosen. Also the persistent store will require expansion to accommodate these additional items. Finally, the second level of authentication must be implemented to request and process the six-digit code from the user.
Details of this kind of implementation are beyond the scope of this present discussion, however the following comments can be made:
  • Developers should avoid “reinventing the wheel.” The code required to generate six-digit keys is complex and error-prone. If a package is available that is already proven and that supports the site stack in use, then that should be chosen.
  • For websites developed using PHP, visit and search for TFA, 2TF or Two Factor Authentication. Over fifty entries are available.
  • For websites developed using node.JS, visit and examine the file. The package is a very comprehensive library for implementing two factor authentication as well as generating both HOTP and TOTP passcodes.
  • The vendor website has examples of code required for C#, Java, Node.js, PHP, Python, Ruby (Rails), and Ruby (Sinatra). Another set of examples covers similar material for using SMS authentication rather than a local app.
    1. Security Issues

Several general comments can be made about the efficacy of TFA.

  • While TFA improves security it is not perfect. Google “Two Factor Authentication Hacks.” This query recently returned nearly two million results.
  • Using SMS as a method to transmit authorization keys to users is definitely not a best practice. Using the Google Authenticator is far safer. Authenticator is available in both Android and iPhone versions.
  • No technology, no matter how sophisticated, can withstand clever social engineering attacks. One of the more famous attacks seems to be This kind of attack, by the way, can be mitigated by simply not using SMS to transmit authorization keys.
  • Password recovery is a gaping hole in TFA. This is because password recovery completely bypasses TFA, allowing hackers to gain control of the user’s account.
  • An educated, vigilant user is always an asset when trying to improve security. Spending some time educating users about common threats and how to avoid them can pay handsome dividends.