tibasMemberDef_SetAuthenticationCallback()
Specifies a callback routine that allows you to customize how user authentication information is retrieved for users.
If you invoke tibasMemberDef_SetAuthenticationCallback() to specify a callback routine for your application and the security policy file for the domain that controls the metaspace which your application is joining specifies user password or X509v3 authentication, then the callback routine is called when users try to connect to the domain.
If there is no callback routine, ActiveSpaces provides a default mechanism, which prompts the user for the required information on the default console. In such a case, passwords are never echoed on the console.
Declaration
tibas_status tibasMemberDef_SetAuthenticationCallback( tibasMemberDef memberDef, tibasMetaspace_AuthenticationCallback callback, void* closure)
Parameters
| Parameter | Description |
|---|---|
| memberDef | Specify the memberDef object that identifies the member for which you want to set the authentication callback. |
| callback | Specifies the name of the callback function used to process authentication information |
| closure | A pointer to a closure value that is returned to your application when the authentication callback function completes. This can be a text string, or any information that your application needs to keep track of during the authentication process. |
Remarks
Use the tibasMemberDef_SetAuthenticationCallback() function to specify the name of a callback function that is used to retrieve authentication credentials for users requesting connection to a specified member.
The authentication callback routine must conform to the following function prototype, which is defined in the security.h header file:
tibas_status TIBAS_COMMON_API tibasMemberDef memberDef, tibasMetaspace_AuthenticationCallback callback, void* closure);
The authentication callback routine takes one argument—a tibasAuthenticationInfo struct that is defined in the security.h header file as follows:
typedef struct _tibasAuthenticationInfo
{
tibas_authenticationMethod authenticationMethod;
const char* metaspaceName;
tibasUserCredential* credential;
const char* authHint;
} tibasAuthenticationInfo;
The tibasAuthenticationInfo structure includes the following members:
- authenticationMethod
- Based on the value assigned to the authentication setting in the security policy file that the security domain is using, ActiveSpaces assigns one of the following values to the authenticationMethod data type:
- metaspaceName
- The currently connected metaspace is assigned.
- credential
- A pointer to a tibasUserCredential structure that is used to process the authentication information.
- authHint
- ActiveSpaces populates this element with the authorization hint that is provided in the security policy file that the active security domain is using the hint keyword, for example, hint=SystemLoginInformation.
Using the Credential Member
The credential member is a tibasUserCredential structure. This structure contains a set of members that the callback function uses to store authentication information that is passed to it, such as authentication domains, usernames, and passwords.
The tibasUserCredential is defined in the security.h header file. It has the following definition:
typedef struct _tibasUserCredential
{
char domain[64];
char username[64];
char keyfile[256];
char password[64];
} tibasUserCredential;
You use the members of the credential structure to pass to ActiveSpaces the authentication information provided by users requesting access to security domains. The elements are defined as follows: