You can extend built-in authentication systems where OpenEdge perform authentication (_oeusertable and _oslocal for example) by using either the Data Administration Console or the Data Administration tool to configure a built-in authentication system with a callback. (See the online help for each tool for more information.)

The following figure shows the Authentication Systems dialog in the Data Administration tool. It lists the available authentication systems in the Domain Type column. Note that, in this case, the built-in _oeusertable authentication system is extended by the callback, ABLcallback1 (where ABLcallback1 is a procedure in a folder included in the PROPATH).

When _oeusertable or _oslocal are configured with an authentication callback, user authentication proceeds as follows:

1. The application launches an OpenEdge-performed user authentication operation.

   For example, it executes the CONNECT statement with specified User ID (-U) and Password (-P) connection parameters. Or it executes the SECURITY-POLICY:SET-CLIENT( ) method with an unsealed client-principal object initialized with the required user credentials.

2. After user credentials are validated, the AVM executes the AuthenticateUser procedure in ABLcallback1. (see Creating an ABL authentication callback procedure for more information about AuthenticateUser.)

   If user credentials are not valid, authentication immediately fails and the AVM does not execute the AuthenticateUser procedure. The AVM raises a general authentication failure error and control returns to the application.

   Note that Enable Authentication in the above figure is selected by default because _oeusertable (as well as _oslocal) is predefined as enabled for user authentication. This enables the AuthenticateUser procedure to execute and extend the built-in authentication system. This selection cannot be disabled. (Clear the Callback field if you do not want callbacks to run.)

3. AuthenticateUser performs whatever further authentication, or other checking that you might require. For example, you could check whether a user has exceeded a set number of logins in a given time period, and generate a customized error message if that condition exists.
4. Since the client-principal object is unsealed at this point, an authentication callback procedure can add additional information (user roles, for example) to the object.
5. If the AuthenticateUser procedure returns success, the AVM seals the client-principal object in the LOGIN state. The AVM uses SSO to assign the authenticated identity to a database connection or an ABL session.
6. After using SSO to assign user identity, the AVM executes any optional actions specified in the AfterSetIdentity procedure in ABLcallback1.

   The actions specified in AfterSetIdentity extend the default SSO authentication process. However, since the client-principal object is sealed, you cannot change identity settings. You can initiate other actions, such as changing context information stored in an OpenEdge database. (See Creating an ABL authentication callback procedure for more information about AfterSetIndentity.)

If the application later uses the sealed client-principal from step 5in another successful SSO operation, AfterSetIdentity also executes as in step 6.