In an ABL authentication callback, the AuthenticateUser and the AfterSetIdentity procedures must be implemented with the following signatures:

PROCEDURE AuthenticateUser:
DEFINE  INPUT    PARAMETER  hCP             AS HANDLE.
DEFINE  INPUT    PARAMETER  cSystemOptions  AS CHARACTER EXTENT.
DEFINE  OUTPUT   PARAMETER  iPAMStatus      AS INTEGER INIT ?.
DEFINE  OUTPUT   PARAMETER  cErrorMsg       AS CHARACTER.
END.

PROCEDURE AfterSetIdentity:
DEFINE  INPUT    PARAMETER  hCP             AS HANDLE.
DEFINE  INPUT    PARAMETER  cSystemOptions  AS CHARACTER EXTENT.
END.

Note that AfterSetIdentity is optional. Include it only if you intend to extend the default SSO operation.

The following is a description of the parameters in the signatures:

  • hCP — A handle to the client-principal object containing the user's identity information. The client-principal object is passed to the SET-DB-CLIENT( ) function or SECURITY-POLICY:SET-CLIENT( ) method. OpenEdge creates a client-principal for user authentication in response to a CONNECT( ) statement that executes with the User ID (-U) and Password (-P) connection parameters.
  • cSytemOptions — A character array containing any system options defined in the OpenEdge security domain that is pointed to by the client-principal object. System options are set when you configure a domain in the Data Administration tool or in the Data Administration Console.
    Note: Each authentication system implements its own unique set of system options. Refer to the authentication system's documentation to determine which options are supported.

    The value specified in cSytemOptions is user-defined but must follow the correct syntax. They must follow the startup parameter syntax, where a parameter is always precede by a dash (-) and each token must be separated by a space character (for example, -myparam1 -myparam2 value2). Each element of the array will contain a single parameter followed by an argument (if one was specified). The parameters are defined in _sec-authentication-domain, a meta-schema table used by the Data Administration tool and the Data Administration Console to store domain configuration information.

    OpenEdge reserves two options to indicate whether the application is authenticating the user for a session (-setClient) or for an OpenEdge database connection (-dblogical-db-name). The -setClient option is present in the array when the application is executing SECURITY-POLICY:SET-CLIENT( ) during authentication, and if OpenEdge is setting the credentials for the session during the AfterSetIdentity operation. The -dblogical-db-name is present in the array when SET-DB-CLIENT( ) or the CONNECT statement, or if OpenEdge is trying to set the credentials for a database connection while executing SECURITY-POLICY:SET-CLIENT( ). AfterSetIndentity can use these options to determine whether the operation is for a session or for an OpenEdge database connection.l

    If the value specified in cSytemOptions is syntactically incorrect, a configuration error occurs when you try to authenticate the user using that domain.

  • iPAMStatus — An integer status code that you return to the AVM to indicate whether user authentication succeeded or not. This must be one of the values implemented as static properties of the Progress.Security.PAMStatus. (See ABL Reference for more information.) If a status code other than Success is returned from AuthenticateUser, the user authentication operation ends with failure, and the AVM takes no further action except to seal the client-principal object in the FAILED state and return the error to the application.
    Note: When extending a built-in user authentication operation for _osusertable or _oslocal, AuthenticateUser runs only if the built-in user authentication is successful. Otherwise, the operation ends without running AuthenticateUser and returns a general authentication failure error to the application.
  • cErrorMsg — An error message that you create. It is used as the error message generated by SET-DB-CLIENT( )or SECURITY-POLICY:SET-CLIENT( ), if the returned status (iPAMStatus) is Custom.