AUTHENTICATION-FAILED( ) method

AUTHENTICATION-FAILED( ) method

Indicates that an unsealed Client-principal object could not be authenticated. This authentication failure signifies that the application or database user identity from the registered authentication domain is not authentic. Once invalidated, the Client-principal object’s properties cannot be changed and the object cannot be sealed.

Note: An application can use this method to invalidate an unsealed Client-principal object for any reason.

Return type: LOGICAL

Applies to: Client-principal object handle
Syntax
AUTHENTICATION-FAILED( [ reason ] ) 
reason

An optional character expression that specifies the reason for the authentication failure. For example, “Invalid user name or password”. The AVM sets the STATE-DETAIL attribute to this value.

If you call this method for a sealed Client-principal object, the AVM generates a run-time error.

If successful, this method returns TRUE. Otherwise, it returns FALSE.

Calling this method generates an audit event and creates an audit record for the event in all connected audit-enabled databases according to each database’s current audit policy settings.

The AVM also sets the LOGIN-STATE attribute for the Client-principal object to “FAILED”.

Use the LOGOUT( ) method to invalidate, or terminate access to, a sealed Client-principal object.

The following code fragment illustrates how to use the AUTHENTICATION-FAILED( ) method:
DEFINE VARIABLE hCP    AS HANDLE  NO-UNDO. 
DEFINE VARIABLE val-ok AS LOGICAL NO-UNDO. 
. . . 
CREATE CLIENT-PRINCIPAL hCp. 
. . .  
val-ok = hCP:AUTHENTICATION-FAILED(“Invalid username or password”). 
See also: LOGIN-STATE attribute, LOGOUT( ) method, STATE-DETAIL attribute

Syntax
AUTHENTICATION-FAILED( [ `reason` ] )

DEFINE VARIABLE hCP AS HANDLE NO-UNDO. DEFINE VARIABLE val-ok AS LOGICAL NO-UNDO. . . . CREATE CLIENT-PRINCIPAL hCp. . . . val-ok = hCP:AUTHENTICATION-FAILED(“Invalid username or password”).

OpenEdge Release 10.2B