Simplifies initialization of client-principal object attributes that are required and commonly used to assert a given identity for user authentication. This method can be called on any client-principal object, whether it is sealed or unsealed. Each time the method is called, it returns the object to the INITIAL state (see the LOGIN-STATE attribute entry) initialized with values from the parameter list.

Return type: LOGICAL

Applies to: Client-principal object handle

Syntax

INITIALIZE ( qualified-user-id [ , session-id [ , expiration
                               [ , primary-passphrase]]] )
qualified-user-id
A character expression that evaluates to a fully qualified user ID (user name and domain name delimited by the '@' character), which is equivalent to setting the USER-ID attribute and the DOMAIN-NAME attribute on the object. For more information on valid values, see the reference entry for this attribute.
session-id
An optional character expression that evaluates to the user's application login session ID. This value sets the SESSION-ID attribute on the object. If not specified or the parameter evaluates to the Unknown value (?), OpenEdge generates a 22-character Base64-encoded UUID value that is suitable for use in OpenEdge auditing.
expiration
An optional DATETIME-TZ expression that evaluates to a date and time value that specifies the expiration of the client-principal user credentials. A valid value sets the LOGIN-EXPIRATION-TIMESTAMP attribute on the object. If not specified or the parameter evaluates to the Unknown value (?), no expiration is set for the client-principal.
primary-passphrase
An optional character expression that evaluates to the cleartext or encoded value of the user's account password. For information on setting an encoded password value, see ENCRYPT-AUDIT-MAC-KEY( ) method and Password encoding.

This value sets the PRIMARY-PASSPHRASE attribute on the object, which is used in any OpenEdge-performed user authentication operation. If not specified or the parameter evaluates to the Unknown value (?), the PRIMARY-PASSPHRASE attribute is not set.

Note: A passphrase is a sequence of words that is typically easy to remember but significantly harder to crack through brute-force attacks due to its length and the entropy introduced by using multiple words. Because a passphrase offers stronger protection for verifying the authenticity of the client-principal, it is the recommended password strategy for the INITIALIZE() method.

The ENCRYPT-AUDIT-MAC-KEY() method accepts either a complex password—one that includes a mix of letters, numbers, and symbols—or a passphrase made up of a sequence of words. Both options can be used for the primary-passphrase parameter in the INITIALIZE() method. They simply represent different approaches to achieving cryptographic strength.

Note: This value has no relation to the domain access code used to seal a client-principal object.

OpenEdge does not store the primary-passphrase value. Once the client-principal object is sealed, OpenEdge removes all trace of this value from the client-principal.

Use an encoded primary-passphrase value especially when you export the unsealed client-principal to a remote authentication service, or to any other ABL session prior to sealing the object. For more information on exporting a client-principal, see EXPORT-PRINCIPAL( ) method.

You can change these (and other writeable) attribute settings at any time after invoking this method until the client-principal object is sealed.

ABL raises ERROR if:

  • The qualified-user-id parameter evaluates to the Unknown value (?)
  • The expiration parameter does not evaluate to a valid DATETIME-TZ value
  • The session-id parameter evaluates to a blank character string
Note: If an error occurs when invoking this method, the existing client-principal object remains unchanged.

See also

PRIMARY-PASSPHRASE attribute, QUALIFIED-USER-ID attribute, SESSION-ID attribute