Exec SERVER$CTRL API
7.4. AUTH_USER Password Authentication
This authentication API supports authenticating a [domain\]user-id/password against a centralized security database (domain) or against the local 2200 security database. It also supports the return of an authentication handle on a successful authentication, which is used for activity impersonation through CALL SEC$SWITCH$.
This function does not require privilege unless the option to request an
authentication handle is requested or the system security environment specifies NONPRIVILEGED_AUTHENTICATION_API = DISABLED. Default = ENABLED.
Function Prototype
cid_struct_t AUTH_USER(authUserPkt_t * pkt);
Packet (authUserPkt_t)
0 version reserved/aux status
1 options target_AM
2 - 81 user_credentials
82 - 88 origin_info
89 - 91 userID
92 network_userid_length
93 - 230 network_userid
231- 232 authentication_handle
233 options_status actual_AM
where:
version (I) is the authentication packet version, 0 or 1. Use version 1 to indicate the calling program is prepared to handle an aux status in H2 of word 0.
reserved (I) / aux status (O) for packet version 0, is a reserved field, and must be zero; for packet version 1, must be zero on input and may contain an aux status on return from
AUTH_USER. This might be an Exec SEC$USERID$
CALL status that caused a 04033 or 04034 status to be returned, or an Exec SEC$USERID$ CALL status returned by AM0 on a failed password change.
The field name in the authUserPkt_t structure defined in FLEXAUTHAPI/H remains
verAuth.reserved for compatibility.
options (I) are optional settings that control the authentication;
can be any of the following constants OR’d together:
• REQUEST_AUTH_HANDLE—return an authentication handle on successful authentication.
• REQUEST_LOCAL_AUTH—authenticate user-id/password against the local 2200 database.
• REQUEST_NETWORK_AUTH—authenticate user_credentials using the centralized security database (domain).
• REQUEST_AM_NUM_SPECIFIED—if specified, use the AM specified in target_AM to perform the authentication; otherwise, allow ASIS to determine the authentication module to perform the authentication.
If neither REQUEST_LOCAL_AUTH nor
REQUEST_NETWORK_AUTH is specified, ASIS routes the request to AMs based on its normal selection algorithm. This causes network
authentication to be attempted first if the network authentication AM is installed, followed by local authentication. If both REQUEST_LOCAL_AUTH and REQUEST_NETWORK_AUTH are specified, an error status is returned.
target_AM (I) allows you to specify the AM number to perform the authentication. Used only if the
REQUEST_AM_NUM_SPECIFIED option is specified.
user_credentials (I) is an ASCII string (must be NULL-terminated) with the following format:
[domain-name\]user-name/password[/newpassword]
domain-name is not used for
REQUEST_LOCAL_AUTH and is optional for REQUEST_NETWORK_AUTH (default = the domain in which the 2200 computer account resides).
If newpassword is specified, the new password must meet all password constraints.
The order of operations for processing user_credentials is as follows:
• Verify existing password.
• Check password expiration if a new password was not supplied.
• Check new password for legality if specified.
• Change password if a legal new password was specified.
origin_info (I) is information giving the origin of the request in the form of an ATI structure. If known, it should contain the IP address of the requestor. This field is passed to AMs and placed in log entries to help identify the origin of the authentication request. See Appendix A for the format of the ATI structure.
userID (O) on a successful authentication, contains the authenticated 2200 user-id.
network_userid_length (O) on a successful network authentication, if user_credentials contains a network user-id, contains the length of the network user-id in bytes.
network_userid (O) on a successful network authentication, if user_credentials contains a network user-id, contains the network user-id in Unicode.
authentication_handle (O) if an authentication handle was requested, is the opaque object that may be passed to CALL SEC$SWITCH$ to prove authentication.
options_status (O) are status bits reporting the options used in the request; can be any of the following constants OR’d together:
• STATUS_LOCAL_AUTH—authentication against the local 2200 database was performed.
• STATUS_NETWORK_AUTH—authentication against the centralized security database (domain) was performed.
• STATUS_AM_NUM_USED—AM specified in target_AM was used.
actual_AM (O) is the number of the AM that performed the authentication.
Statuses Returned
Status is returned in a cid_struct_t structure defined in the header file global/h, defined as follows:
typedef struct
{"""""""""" /*This format is for the ELMS identifier word used on returns from
""""""""""""" ASIS administrative and Authentication API function calls."""""""" */
"
"" unsigned int"""""""""""" severity_code""" : 3;
"" unsigned int"""""""""""" component_id"""" :15;
"" short unsigned int"""" message_number;
} cid_struct_t;
The message numbers are defined in APIMESSAGE/H.
Table 7–1 lists the AUTH_USER status codes.
Table 7–1. AUTH_USER Status Codes
Severity Code
Message
Number Explanation
0 0 Normal authentication completion.
7 01 Unsupported packet version.
7 02 Reserved fields nonzero.
7 010 ASIS unavailable.
7 020 ASIS internal error.
7 04000 AM specified is not configured, or AM number is out of range.
Table 7–1. AUTH_USER Status Codes
Severity Code
Message
Number Explanation
7 04001 REQUEST_NETWORK_AUTH is specified, but network authentication is not configured.
7 04002 REQUEST_LOCAL_AUTH is specified, but no local authentication AM is configured.
7 04003 REQUEST_AUTH_HANDLE is specified, but the caller does not possess the SSAUTHNTICAT privilege.
7 04004 Both REQUEST_LOCAL_AUTH and
REQUEST_NETWORK_AUTH are specified.
7 04005 Authentication failed. This status is returned to nonprivileged callers for all authentication failures if the system is not configured to provide more detailed failure information. See 7.3.
7 04006 Authentication failed due to an undefined user-id.
This status is returned only to privileged callers or if the system is configured to provide detailed failure information. See 7.3.
7 04007 Authentication failed due to an invalid password. This status is returned only to privileged callers or if the system is configured to provide detailed failure information. See 7.3.
7 04010 Authentication was successful, but the user-id is marked disabled.
7 04011 REQUEST_LOCAL_AUTH is specified, but the user-id record does not contain a password. This status is returned only to privileged callers or if the system is configured to provide detailed failure information.
See 7.3.
7 04020 Invalid user_credentials format.
7 04021 REQUEST_LOCAL_AUTH is specified, but the user-id record has network-only authentication specified in the user-id record.
7 04022 Authentication failed due to an environmental problem outside ASIS, for example, a time-out occurred trying to communicate with a Windows server.
7 04023 Authentication failed because a password change was specified and password change is not supported by the authentication module used.
7 04024 Authentication failed because all authentication modules declined to process the authentication request.
Table 7–1. AUTH_USER Status Codes
Severity Code
Message
Number Explanation
7 04025 Authentication failed because Messaging Integration Services for ClearPath OS 2200 was unable to match the network user-id to a 2200 user-id.
7 04026 The system security environment specifies nonprivileged callers are not allowed to use AUTH_USER and AUTH_CONTEXT APIs.
7 04033 Authentication was successful but the requested authentication handle could not be allocated.
7 04034 Authentication was successful but the requested authentication handle could not be allocated because the Exec version is too low.
7 04035 Authentication failed because the supplied password has expired. This status is returned only to privileged callers or if the system is configured to provide detailed failure information. See 7.3.
7 04041 Attempt to change the password but the new password specified is too short.
7 04042 Attempt to change the password but the new password specified is too long.
7 04043 Attempt to change the password but the new password specified contains invalid characters.
7 04044 Attempt to change the password but the new password specified may not be the same as the user-id.
7 04045 Attempt to change the password but the new password specified may not be the same as the old password.
7 04046 Attempt to change the password but the new password specified may not yet be changed.
7 04047 Attempt to change the password but the password change of machine-generated passwords via API is not supported.
7 04050 Attempt to change the password but a SEC$USERID$ error occurred.
7 04051 Attempt to change the password but a SEC$USERID$ timestamp lock error occurred.
0 04052 The AM acknowledges successful password change.
Password Expiration
AM0 detects password expiration and returns a 04035 status to ASIS. This status is returned only to privileged callers or if the system is configured to provide detailed failure information. For more information, see 7.3. Nonprivileged callers receive a 04005 status if the system security environment does not specify “Display Message on User Terminal” for both undefined user-ids and invalid passwords.