Authenticator Class

Properties   Methods   Events   Configuration Settings   Errors  

The Authenticator class specializes in user authentication.

Syntax

class secureblackbox.Authenticator

Remarks

Authenticator provides capabilities for implementing the authenticating party (as opposed to the one being authenticated) of the authentication protocol.

Authenticator can be used in a variety of authentication scenarios, ranging from simple password checks to complicated multi-factor variants. It also supports authentication via a SBB-own DC protocol, which makes it a good pair for DCAuth control.

In default configuration the component uses the attached database of users to handle authentication requests. The authentication flow can be altered if needed to match specific authentication requirements.

In Authenticator's terms, the authentication process is divided into a sequence of atomic steps. Each step is characterized by a user providing an authentication token - such as a password or PIN - and the authenticator validating that token. Each validation step may result in one of the following outcomes:

• Authentication succeeded: the authentication has been completed with the positive outcome;
• Authentication failed: the authentication process has failed, the user didn't provide enough evidence to confirm they are who they claim they are;
• Further authentication is required: the authentication was partly successful, but the settings of the component or user details require further step(s) to be taken.

Use the following logic when integrating the Authenticator into your project:

• Whenever you receive an authentication request from a user, call the start_auth method, passing the UserID as a parameter. This initiates the authentication procedure: the Authenticator control looks up the user in the users database and picks the first authentication method. It then returns the Further authentication is required result and stores the details of the first authentication step in auth_info property. Apart from the information about the authentication method that is to be performed during this step, auth_info also contains a > value, which accumulates parameters and progress of the user's authentication flow. You can save the state value on this stage, and restore it later when a response from the user is received. With that in mind, class is stateless; you can save the current authentication state in a database, and return to it from a different context.
• Now that you have obtained Further authentication needed from start_auth, it's time to check the > and request the corresponding token from the user. For example, if the method is 'password', you may present the user with a password dialog.
• Upon receiving a password (or other kind of authentication token) from the user, pass it to the continue_auth method, together with the state object that you saved on the preceding step. The component will process the token and come up with one of the three results given above, signifying the end of the first authentication step. If Further authentication is required result is returned, another authentication step needs to be performed (either because a multi-factor authentication is configured for this user, or because an alternative authentication method was chosen following failure of the previous attempt). If that is the case, follow the guidance for start_auth-initiated step above.

  Depending on the settings, many authentication steps may need to be performed, so your code may ultimately end up calling continue_auth many times.

class can be customized to use external user information sources instead of a predefined user database. on_auth_start, on_auth_verify, and on_auth_attempt_result events provide an opportunity for your code to intervene into the authentication process by defining your own authentication procedures and validating authentication tokens manually.