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. Namespace type 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 mentioned previously.
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 example, 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 be used only for auditing and will be logged in the "User ID" field in the audit record for CONNECT statement. If the API does specify 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 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)
Currently, Db2 only supports authid (DB2SEC_ID_TYPE_AUTHID).
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.