DB2 Version 9.7 for Linux, UNIX, and Windows

db2secGetAuthIDs API - Get authentication IDs

Returns an SQL authid for an authenticated user. This API is called during database connections for both user ID/password and GSS-API authentication methods.

API and data structure syntax

     SQL_API_RC ( SQL_API_FN *db2secGetAuthIDs)
                           ( const char *userid,
                             db2int32 useridlen,
                             const char *usernamespace,
                             db2int32 usernamespacelen,
                             db2int32 usernamespacetype,
                             const char *dbname,
                             db2int32 dbnamelen,
                             void      **token,                             
                             char SystemAuthID[DB2SEC_MAX_AUTHID_LENGTH],
                             db2int32 *SystemAuthIDlen,
                             char InitialSessionAuthID[DB2SEC_MAX_AUTHID_LENGTH],
                             db2int32 *InitialSessionAuthIDlen,
                             char username[DB2SEC_MAX_USERID_LENGTH],
                             db2int32 *usernamelen,
                             db2int32 *initsessionidtype,
                             char      **errormsg,
                             db2int32 *errormsglen );

db2secGetAuthIDs API parameters

userid

Input. The authenticated user. This is usually not used for GSS-API authentication unless a trusted context is defined to permit switch user operations without authentication. In those situations, the user name provided for the switch user request is passed in this parameter.

useridlen

Input. Length in bytes of the userid parameter value.

usernamespace

Input. The namespace from which the user ID was obtained.

usernamespacelen

Input. Length in bytes of the usernamespace parameter value.

usernamespacetype

Input. Namespacetype value. currently, the only supported namespace type value is DB2SEC_NAMESPACE_SAM_COMPATIBLE (corresponds to a username style like domain\myname).

dbname

Input. The name of the database being connected to. The API can ignore this, or it can return differing authids when the same user connects to different databases. This parameter can be NULL.

dbnamelen

Input. Length in bytes of the dbname parameter value. This parameter is set to 0 if dbname parameter is NULL.

token

Input or output. Data that the plug-in might pass to the db2secGetGroupsForUser API. For GSS-API, this is a context handle (gss_ctx_id_t). Ordinarily, token is an input-only parameter and its value is taken from the db2secValidatePassword API. It can also be an output parameter when authentication is done on the client and therefore db2secValidatePassword API is not called. In environments where a trusted context is defined that allows switch user operations without authentication, the db2secGetAuthIDs API must be able to accommodate receiving a NULL value for this token parameter and be able to derive a system authorization ID based on the userid and useridlen input parameters above.

SystemAuthID

Output. The system authorization ID that corresponds to the ID of the authenticated user. The size is 255 bytes, but the DB2® database manager currently uses only up to (and including) 30 bytes.

SystemAuthIDlen

Output. Length in bytes of the SystemAuthID parameter value.

InitialSessionAuthID

Output. Authid used for this connection session. This is usually the same as the SystemAuthID parameter but can be different in some situations, for instance, when issuing a SET SESSION AUTHORIZATION statement. The size is 255 bytes, but the DB2 database manager currently uses only up to (and including) 30 bytes.

InitialSessionAuthIDlen

Output. Length in bytes of the InitialSessionAuthID parameter value.

username

Output. A username corresponding to the authenticated user and authid. This will only be used for auditing and will be logged in the "User ID" field in the audit record for CONNECT statement. If the API does not fill in the username parameter, the DB2 database manager copies it from the userid.

usernamelen

Output. Length in bytes of the username parameter value.

initsessionidtype

Output. Session authid type indicating whether or not the InitialSessionAuthid parameter is a role or an authid. The API should return one of the following values (defined in db2secPlugin.h):

DB2SEC_ID_TYPE_AUTHID (0)
DB2SEC_ID_TYPE_ROLE (1)

errormsg

Output. A pointer to the address of an ASCII error message string allocated by the plug-in that can be returned in this parameter if the db2secGetAuthIDs API execution is not successful.

errormsglen

Output. A pointer to an integer that indicates the length in bytes of the error message string in errormsg parameter.