Credential Validation Plug-ins

The DirX Access authentication service supports callouts during the initial user authentication process and allows for the deployment of credential validation handlers through a plug-in interface. This design allows externalizing certain tasks during initial user authentication. This chapter describes in detail the validation scenarios that can be externalized using the validation callout handler.

About Initial User Authentication Callouts

The following tasks can be externalized in initial user authentication processes:

  • One-time password (OTP) callback authentication

  • Validation of username/password credentials

The next sections describe these use cases.

OTP Callback Authentication

DirX Access supports OTP authentication based on callbacks to users who wish to be authenticated. This is a specific OTP authentication scheme where secondary communication channels are used to authenticate the user through a randomly-generated OTP supplied and managed/validated by DirX Access. The underlying assumption is that it is hard to impossible for intruders to attack the primary and secondary communication channel simultaneously in a given timeframe of (for example) 60 seconds.

DirX Access natively supports such OTP authentication scheme but considers the callout handler that provides the secondary communication channel to be external to DirX Access. It supports a plug-in interface to deploy providers for arbitrary callback means; for example, e-mail, voice, SMS, or Mobile Push authentication.

It is at the discretion of a specific solution to decide whether a specific OTP callback authentication is appropriate for a given scenario, to select the secondary communication channel for this solution and to assess the presumed authentication quality for this solution-specific callout authentication in a ranking.

Validation of Username/Password Credentials

By default, DirX Access internally validates username/password1 credentials during the initial authentication processes. The internal validation of these credentials uses reference data from LDAP-based persistence.

To support specific constraints such as proprietary validation algorithms, user populations not maintained in LDAP-based persistence, external credential validation services can be plugged into the DirX Access authentication service that performs the initial authentication process.

Use cases for this scenario include:

  • Validation of user credentials on the basis of Windows domain account names and passwords. This use case externalizes validation to Kerberos KDCs on Windows domain controllers.

  • Validation of user credentials on the basis of externalizing validation to RADIUS servers.

  • Validation of user credentials on the basis of externalizing validation to custom validation servers such as an RSA ACE/Server checking credentials belonging to RSA SecurID tokens.

DirX Access supports a callout handler plug-in interface to deploy providers for external password credential validation. This interface also supports password-based authentication protocols that depend on looking up a challenge value from the external validation service in a first pass before providing related (password) values in a subsequent pass.

Callout Handlers for OTP Callback Authentication

This section describes the creation and deployment of callout handlers for the OTP callback authentication use case.

Developing an OTP Challenge Callback Handler

This section describes how to develop a custom validation callout handler for the OTP callback authentication use case.

Externalizing OTP Challenge Distribution from the DirX Access Server

The DirX Access Server externalizes OTP challenge distribution through a plug-in interface. This operation requires creating a callout handler that implements the ValidationCallout interface (net.atos.dirx.access.authn.api.callout.ValidationCallout). This interface allows the sending of challenges through the sendChallenge method.

Employing an OTP Challenge Callback Handler

The steps needed to employ the custom callout handler are outlined in the section Employing External Plug-in Modules.

Using the OTP Challenge Callback Handler

The following tasks need to be performed to use a custom validation callout handler. Before starting to configure the DirX Access Server, make sure to run through all the steps in the section Employing External Plug-in Modules.

Prerequisites

To successfully employ the custom validation callout handler, the OSGi bundle exporting the package containing the callout implementation must be installed on the DirX Access Server. To accomplish this task, make sure you have performed all of the steps described in the section Employing External Plug-in Modules.

Configuring the OTP Challenge Callback Handler at the DirX Access Server

To configure the OTP Challenge Callback Handler at the DirX Access Server:

  • In DirX Access Manager, go to Configuration | Extension modules.

  • Create the callout handler <CalloutIdentifier>:

    • Go to Callout handlers and then click the “add” icon to create a new callout handler.

    • Identifier: <CalloutIdentifier>.

    • Description: arbitrary.

    • Type: select ValidationEvents.

    • Class name: enter the fully-qualified Java class name of the callout implementation.

    • Click Save.

Custom attributes can be defined to pass setup parameters to the callout handler code (for example, the URL for an SMS gateway or a mobile push authentication provider).

Creating Authentication Methods for the OTP Challenge Callback Handler at the DirX Access Server

The provided setting consists of method-specific parameters that are needed for callout handler usability. The description of other manageable parameters can be found in the section Administrative Tasks.

In DirX Access Manager, go to Configuration | Authentication and then create the authentication method configuration <AuthnMethodIdentifier>:

  • Click the blank “add” icon to create a new authentication method.

  • Authentication name: <AuthnMethodIdentifier>.

  • Authentication type: One time password - Callback.

  • Assurance level: arbitrary.

  • Look ahead value: 60.

  • Throttling value: 10.

  • Validation callout handler identifier: <CalloutIdentifier>.

  • Click Save.

Using Google Firebase for Mobile Push Authentication

The sample application PushCalloutHandler needs a mobile application based on Google Firebase as a receiver for the push authentication messages. To add Firebase to an existing iOS or Android app, follow the instructions at https://firebase.google.com/docs/. Your application gets a Firebase Server API key which must be passed by the DirX Access callback handler when calling the Google API. The provided sample uses the attribute “firebaseApiKey” to pass the attribute from the DirX Access configuration to the callback handler. Each device using this app gets from Google a unique Firebase registration token which must be added to the user repository as the communication address for delivering the OTP challenge to the corresponding device. The name of the attribute must be set in the Callout configuration in DirX Access.

Callout Handlers for Validation of Username/Password Credentials

This section describes the creation and deployment of callout handlers for the external username/password credential validation use case.

Developing a Password Credential Validation Handler

This section describes how to develop a custom validation callout handler for the external username/password credential validation use case.

Externalizing Password Credential Validation from the DirX Access Server

The DirX Access Server can externalize username/password validation through a plug-in concept. This method requires creating a callout handler that implements the ValidationCallout interface (net.atos.dirx.access.authn.api.callout.ValidationCallout). This simple interface performs validation of username/password credentials through the verifyCredentials method.

Employing a Password Validation Callout Handler

The steps needed to employ a validation callout handler are outlined in the section Employing External Plug-in Modules.

Using the Password Credential Validation Handler

The following tasks need to be performed to use this custom validation callout handler. Before starting to configure the DirX Access Server, make sure to run through the steps the section Employing External Plug-in Modules.

Prerequisites

To successfully employ the custom validation callout handler, the OSGi bundle exporting the package containing the callout implementation must be installed on the DirX Access Server. To accomplish this task, make sure you perform all of the steps described in the section Employing External Plug-in Modules.

Configuring the Password Credential Validation Handler at the DirX Access Server

To configure the password credential validation handler at the DirX Access Server:

  • In DirX Access Manager, go to Configuration | Extension modules.

  • Create the callout handler <CalloutIdentifier>:

    • Go to Callout handlers and then click the “add” icon to create a new callout handler.

    • Identifier: <CalloutIdentifier>.

    • Description: arbitrary.

    • Type: select ValidationEvents.

    • Class name: enter the fully-qualified Java class name of the callout implementation.

    • Click Save.

  • In DirX Access Manager, go to Configuration | Authentication. Select an authentication method that supports password-based authentication and then configure the callout handler <CalloutIdentifier> as an externalization module.