Previous Topic: SmDirSetUserAttrMulti()Next Topic: SmDirValidateInstance()

Programming Guides › Programming Guide for C › Directory API Guidance › Directory API Reference › SmDirSetUserDisabledState()

SmDirSetUserDisabledState()

The SiteMinder Policy Server calls SmDirSetUserDisabledState() when an administrator uses the SiteMinder Policy Server User Interface to disable or enable a user, or Password Services disables a user.

This call gives you the opportunity to set the disabled flag in your custom directory to the disabled reason passed in through nDisabledReason.

When implementing SmDirSetUserDisabledState(), be sure that you have specified which field (or attribute) in the custom directory will hold the disabled reason. In the SiteMinder Policy Server User Interface, specify the attribute name in the Disabled Flag field on the User Attributes tab on the User Directory dialog box. This attribute is passed in through lpszDisabledAttr.

Syntax

int SM_EXTERN SmDirSetUserDisabledState (
   const Sm_Api_Context_t*        lpApiContext,
   void*                          pHandle,
   void*                          pInstanceHandle,
   const char*                    lpszUserDN,
   const char*                    lpszDisabledAttr,
   const Sm_Api_DisabledReason_t  nDisabledReason
);

Parameter

I/O

Description

lpApiContext

I

Pointer to the API context structure.

pHandle

I

The address of the pointer returned by SmDirInit().

pInstanceHandle

I

The address of a pointer to the user instance handle.

lpszUserDN

I

Buffer containing the Distinguished Name (DN) of the user whose disabled state has to be modified.

lpszDisabledAttr

I

The user directory attribute that holds a user’s disabled state. The SiteMinder Policy Server checks this attribute to see if a user is enabled or disabled. If a user is disabled, this attribute also holds the specific reason. Use this attribute to change a user’s disabled state.

nDisabledReason

I

Reason that the user was disabled or enabled. Possible reasons are enumerated in Sm_Api_DisabledReason_t. Store the user-disabled state in the user directory attribute that is specified in lpszDisabledAttr.

Note: A user account can be disabled for multiple reasons. Be sure to hold onto the disabled reason(s) and be sure that you don’t overwrite those bits. For example, if the User must change password at next login checkbox is checked and the administrator clicks Disable, the nDisabledReason parameter holds both the Sm_Api_Disabled_PWMustChange bit and the Sm_Api_Disabled_AdminDisabled bit. When the user account is enabled, be sure to clear all the disabled bits.

Returns

Returns 0 if successful or -1 if not successful.

Remarks

To enable a user’s account in the Policy Server User Interface:

  1. Navigate to the User Management dialog box.
  2. Select the user whose account you are enabling.
  3. Click Enable.

To disable a user’s account in the Policy Server User Interface:

  1. Navigate to the User Management dialog box.
  2. Select the user whose account you are disabling.
  3. Click Disable.

Enabled user accounts can also be disabled by using Password Services. For example, you can configure Password Services to disable a user account under the following conditions:

Sample Code Information

When using the sample, specify the disabled attribute as Disabled. This attribute will be passed in through the parameter lpszDisabledAttr. You can specify the attribute by entering Disabled in the Disabled Flag field on the User Attributes tab of the User Directory dialog box.

In the SiteMinder Policy Server User Interface, in the User Management dialog box, suppose an administrator selects the enabled user Mikel and clicks Disable. Using the sample code, the User DN (lpszUserDN) is Mikel, and the Disabled Attribute (lpszDisabledAttr) is Disabled. The Disabled Reason (nDisabledReason) is Sm_Api_Disabled_AdminDisabled. In the SiteMinder Policy Server User Interface, the User Management dialog box shows that the Current Settings for Mikel have changed from User is enabled to Disabled - administrative.