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
encrypted value of the user's account password. For information on setting an encrypted
password value, see ENCRYPT-AUDIT-MAC-KEY( ) method and the topics on encrypted passwords in OpenEdge Programming Interfaces.
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:
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 encrypted 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.
