db2secGetGroupsForUser API - Get list of groups for user

Returns the list of groups to which a user belongs.

API and data structure syntax

     SQL_API_RC ( SQL_API_FN *db2secGetGroupsForUser) 
                           ( const char *authid,
                             db2int32 authidlen,
                             const char *userid,
                             db2int32 useridlen,
                             const char *usernamespace,
                             db2int32 usernamespacelen,
                             db2int32 usernamespacetype,
                             const char *dbname,
                             db2int32 dbnamelen,
                             void *token,
                             db2int32 tokentype,
                             db2int32 location,
                             const char *authpluginname,
                             db2int32 authpluginnamelen,
                             void      **grouplist,
                             db2int32 *numgroups,
                             char      **errormsg,
                             db2int32 *errormsglen );

db2secGetGroupsForUser API parameters

authid

Input. This parameter value is an SQL authid, which means that Db2 converts it to an uppercase character string with no trailing blanks. Db2 always provides a non-null value for the authid parameter. The API must be able to return a list of groups to which the authid belongs without depending on the other input parameters. It is permissible to return a shortened or empty list if this cannot be determined.

If a user does not exist, the API must return the return code DB2SEC_PLUGIN_BADUSER. Db2 does not treat the case of a user not existing as an error, since it is permissible for an authid to not have any groups associated with it. For example, the db2secGetAuthids API can return an authid that does not exist on the operating system. The authid is not associated with any groups, however, it can still be assigned privileges directly.

If the API cannot return a complete list of groups using only the authid, then there will be some restrictions on certain SQL functions related to group support. For a list of possible problem scenarios, see the Usage notes section in this topic.

authidlen

Input. Length in bytes of the authid parameter value. The Db2® database manager always provides a non-zero value for the authidlen parameter.

userid

Input. This is the user ID corresponding to the authid. When this API is called on the server in a non-connect scenario, this parameter will not be filled by Db2.

useridlen

Input. Length in bytes of the userid parameter value.

usernamespace

Input. The namespace from which the user ID was obtained. When the user ID is not available, this parameter will not be filled by the Db2 database manager.

usernamespacelen

Input. Length in bytes of the usernamespace parameter value.

usernamespacetype

Input. The type of namespace. Valid values for the usernamespacetype parameter (defined in db2secPlugin.h) are:

DB2SEC_NAMESPACE_SAM_COMPATIBLE Corresponds to a username style like domain\myname
DB2SEC_NAMESPACE_USER_PRINCIPAL Corresponds to a username style like myname@domain.ibm.com

Currently, the Db2 database system only supports the value DB2SEC_NAMESPACE_SAM_COMPATIBLE. When the user ID is not available, the usernamespacetype parameter is set to the value DB2SEC_USER_NAMESPACE_UNDEFINED (defined in db2secPlugin.h).

dbname

Input. Name of the database being connected to. This parameter can be NULL in a non-connect scenario.

dbnamelen

Input. Length in bytes of the dbname parameter value. This parameter is set to 0 if dbname parameter is NULL in a non-connect scenario.

token

Input. A pointer to data provided by the authentication plug-in. It is not used by Db2. It provides the plug-in writer with the ability to coordinate user and group information. This parameter might not be provided in all cases (for example, in a non-connect scenario), in which case it will be NULL. If the authentication plug-in used is GSS-API based, the token will be set to the GSS-API context handle (gss_ctx_id_t).

tokentype

Input. Indicates the type of data provided by the authentication plug-in. If the authentication plug-in used is GSS-API based, the token will be set to the GSS-API context handle (gss_ctx_id_t). If the authentication plug-in used is user ID/password based, it will be a generic type. Valid values for the tokentype parameter (defined in db2secPlugin.h) are:

DB2SEC_GENERIC: Indicates that the token is from a user ID/password based plug-in.
DB2SEC_GSSAPI_CTX_HANDLE: Indicates that the token is from a GSS-API (including Kerberos) based plug-in.

location

Input. Indicates whether Db2 is calling this API on the client side or server side. Valid values for the location parameter (defined in db2secPlugin.h) are:

DB2SEC_SERVER_SIDE: The API is to be called on the database server.
DB2SEC_CLIENT_SIDE: The API is to be called on a client.

authpluginname

Input. Name of the authentication plug-in that provided the data in the token. The db2secGetGroupsForUser API might use this information in determining the correct group memberships. This parameter might not be filled by Db2 if the authid is not authenticated (for example, if the authid does not match the current connected user).

authpluginnamelen

Input. Length in bytes of the authpluginname parameter value.

grouplist

Output. List of groups to which the user belongs. The list of groups must be returned as a pointer to a section of memory allocated by the plug-in containing concatenated varchars (a varchar is a character array in which the first byte indicates the number of bytes following the first byte). The length is an unsigned char (1 byte) and that limits the maximum length of a groupname to 255 characters. For example, "\006GROUP1\007MYGROUP\008MYGROUP3". Each group name should be a valid Db2 authid. The memory for this array must be allocated by the plug-in. The plug-in must therefore provide an API, such as the db2secFreeGroupListMemory API that Db2 will call to free the memory.

numgroups

Output. The number of groups contained in the grouplist parameter.

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 db2secGetGroupsForUser 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.

Usage notes

The following list describes the scenarios that which problems can occur if an incomplete group list is returned by this API to Db2:

Alternate authorization is provided in CREATE SCHEMA statement. Group lookup will be performed against the AUTHORIZATION NAME parameter if there are nested CREATE statements in the CREATE SCHEMA statement.
Processing a jar file in an MPP environment. In an MPP environment, the jar processing request is sent from the coordinator node with the session authid. The catalog node received the requests and process the jar files based on the privilege of the session authid (the user executing the jar processing requests).
- Install jar file. The session authid needs to have one of the following rights: DBADM, or CREATEIN (implicit or explicit on the jar schema). The operation will fail if the rights stated previously are granted to group containing the session authid, but not explicitly to the session authid.
- Remove jar file. The session authid needs to have one of the following rights: DBADM, or DROPIN (implicit or explicit on the jar schema), or is the definer of the jar file. The operation will fail if the rights stated previously are granted to group containing the session authid, but not explicitly to the session authid, and if the session authid is not the definer of the jar file.
- Replace jar file. This is same as removing the jar file, followed by installing the jar file. Both of the scenarios described previously apply.
When SET SESSION_USER statement is issued. Subsequent Db2 operations are run under the context of the authid specified by this statement. These operations will fail if the privileges required are owned by one of the SESSION_USER's group is not explicitly granted to the SESSION_USER authid.