Programming Guides › Programming Guide for C › Context Structures › Sm_Api_UserContext_t

Previous Topic: Sm_Api_TunnelContext_t

Next Topic: Multi-Valued Attributes in LDAP

Sm_Api_UserContext_t

Contains information about the user.

Syntax

typedef struct
{
   unsigned char  bIsUserContext;
   char* lpszUserName;
   char* lpszUserPath;
   char* lpszDirPath;
   void* lpReserved1;
   char* lpszDirServer;
   char* lpszDirNamespace;
   char* lpszSessionId;
   Sm_Api_GetDnProp fGetDnProp;
   Sm_Api_SetDnProp fSetDnProp;
   void* lpParam;
   Sm_Api_GetUserProp fGetProp;
   Sm_Api_SetUserProp fSetProp;
   Sm_Api_AuthenticateUser fAuthenticate;
} Sm_Api_UserContext_t;

Field

Description

bIsUserContext

Flag indicating that SiteMinder has established the user's identity and that the user context is available. When this flag is set, the fGetProp, fSetProp, fGetDnProp, and fSetDnProp user attribute functions are available.

lpszUserName

Full distinguished name of the user.

lpszUserPath

User path in the following format:

directory-namespace + server + / + user-DN

For example:
ldap://server.company.com/
   uid=user1,ou=people,o=company.com

lpszDirPath

Directory path of the SiteMinder user directory where the user context was established, in the following format:
directory-namespace + server

For example:
ldap://server.company.com

lpReserved1

Reserved for internal use.

lpszDirServer

Directory server of a SiteMinder user directory where user's context was established.

lpszDirNamespace

Directory namespace such as LDAP:, AD:, WinNT:, or ODBC:.

lpszSessionId

Session ID that has been or will be assigned to the user's session, depending on whether or not the session has been established.

fGetDnProp

Function that returns an attribute of a directory entry. If the user context flag bIsUserContext is set, developers can call this function to retrieve a well-known attribute of any DN that the user is related to in the context of a directory (for example, user is a member of a group).

The calling syntax for this function is:
if (lpUserContext->bIsUserContext)
{
char lpszDN[]="cn=group,ou=org unit,o=org";
char lpszCommonName[100];
int nBytes = lpUserContext->fGetDnProp(
                lpUserContext->lpParam,
                lpszDN,
                "accesslevel",
                sizeof (lpszCommonName),
                lpszCommonName);
}

If no error occurs, the function places the value of the requested attribute in the null-terminated output buffer and returns its length. Otherwise, the function returns –1.

The attribute returned from this function should not be larger than the maximum buffer size specified in the nBytesValueBuf argument. Larger attributes are truncated to nBytesValueBuf.

 

fSetDnProp

Function that sets an attribute of a directory entry. If the user context flag bIsUserContext is set, developers can call this function to set a well-known attribute of any DN that the user is related to in the context of a directory (for example: user is a member of a group). At this time only attributes of type 'string' are supported.

The calling syntax for this function is:
if (lpUserContext->bIsUserContext)
{
char lpszDN[]="cn=group,ou=org unit,o=org";
char lpszTimestamp[] = "<timestamp>";
int nErr = lpUserContext->fSetDnProp (
                 lpUserContext->lpParam,
                 lpszDN,
                 "lastaccess",
                 sizeof (lpszTimestamp),
                 lpszTimestamp);
}

 

 

lpParam

Pointer to the parameters to be passed to fGetProp, fSetProp, fGetDnProp, and, fSetDnProp functions.

fGetProp

Function that returns user attributes. If the user context flag bIsUserContext is set, developers can call this function to retrieve a well-known user attribute.

The calling syntax for this function is:

if (lpUserContext->bIsUserContext)
{
char lpszCommonName[100];
int nBytes = lpUserContext->fGetProp (
               lpUserContext->lpParam,
               "cn",
               sizeof (lpszCommonName),
               lpszCommonName);
}

If no error occurs, the function places the value of the requested attribute in the null-terminated output buffer and returns its length. Otherwise, the function returns -1.

The attribute returned from this function should not be larger than the maximum buffer size specified in the nBytesValueBuf argument. Larger attributes are truncated to nBytesValueBuf.

 

fSetProp

Function that sets a user attribute. If the user context flag bIsUserContext is set, developers can call this function to set a well-known user attribute. At this time, only attributes of type "string" are supported.

The calling syntax for this function is:

if (lpUserContext->bIsUserContext)
{
char lpszCommonName[] = "John Smith";
int nErr = lpUserContext->fSetProp (
               lpUserContext->lpParam,
               "cn",
               sizeof (lpszCommonName),
               lpszCommonName);
}

If no error occurs, the function returns 0. Otherwise, the function returns -1.

 

 

fAuthenticate

Function that authenticates a user. This function is called after the user context is established. Returns one of the following:

  • If authentication is successful, returns 0.
  • If authentication fails, returns -1. The reason for the failure is not indicated.

The calling syntax for this function is:

int authRslt=lpUserContext->fAuthenticate(
    lpUserContext->lpParam,
    lpUserCredentials->lpszPassword,
    nBytesUserMsg,
    lpszUserMsg, // User message output
    nBytesErrMsg,
    lpszErrMsg); // Error message output

 

Function Declarations

In structure Sm_Api_UserContext_t, the functions fGetDnProp, fSetDnProp, fGetProp, fSetProp, and fAuthenticate are declared in SmApi.h as follows:

fGetDnProp

typedef int (SM_EXTERN *Sm_Api_GetDnProp)
(
const void* lpParam,        /* The function parameter */
const char* lpDn,           /* The DN of a directory object */
const char* lpszPropName,   /* User property name (null-term) */
const int nBytesValueBuf,   /* Max size of user property buffer */
char* lpszValueBuf /* Output buffer to hold the user property */
);

fSetDnProp

typedef int (SM_EXTERN *Sm_Api_SetDnProp)
(
const void* lpParam,        /* The function parameter */
const char* lpDn,           /* The DN of a directory object */
const char* lpszPropName,   /* User property name (null-term) */
const int nBytesValueBuf,   /* Size of user property buffer */
const char* lpszValueBuf    /* The user property buffer */
);

fGetProp

typedef int (SM_EXTERN *Sm_Api_GetUserProp)
(
const void* lpParam,        /* The function parameter */
const char* lpszPropName,   /* User property name (null-term) */
const int nBytesValueBuf,   /* Max size of user property buffer */
char* lpszValueBuf   /* Output buffer to hold the user property */
);

fSetProp

typedef int (SM_EXTERN *Sm_Api_SetUserProp)
(
const void* lpParam,        /* The function parameter */
const char* lpszPropName,   /* User property name (null-term) */
const int nBytesValueBuf,   /* Size of user property buffer */
const char* lpszValueBuf    /* The user property buffer */
);

fAuthenticate

typedef int (SM_EXTERN *Sm_Api_AuthenticateUser)
(
const void* lpParam,        /* The function parameter */
const char* lpszPassword,   /* User password (null-terminated) */
const int nBytesUserMsg,    /* Max size of user message buffer */
char* lpszUserMsg,   /* Output buffer to hold the user message */
const int nBytesErrMsg,    /* Maximum size of the error buffer */
char* lpszErrMsg    /* Output buffer to hold the error message */
);

More Information:

Multi-Valued Attributes in LDAP

Copyright © 2010 CA. All rights reserved. Email CA about this topic