Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 6 MemberDef : MemberDef Operations : tibasMemberDef_SetAuthenticationCallback()

tibasMemberDef_SetAuthenticationCallback()
Function
Declaration
tibas_status tibasMemberDef_SetAuthenticationCallback(
tibasMemberDef memberDef,
tibasMetaspace_AuthenticationCallback callback,
void* closure)
 
Purpose
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.
Parameters
 
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:
AUTH_USERPWD  ActiveSpaces sets the authentication method to this value is set when the security policy file specifies authentication=userpwd.
AUTH_X509V3  ActiveSpaces sets the authentication method to this value when the security policy file specifies authentication=x509.
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:
domain  Passes authentication domain information to ActiveSpaces, if applicable (for example, for Windows systems)
username  Passes the username for authentication.
keyfile  If X509 authentication is used, passes either the account or keyfile password.
password  Passes the user password.
Example
For a code example showing how to use an authentication callback function, see the reference article on the ASUserAuthentication example program in the TIBCO ActiveSpaces Developers Guide (ASUserAuthenticator).
See Also
tibasMemberDef_GetAuthenticationCallback()

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved