Programming Guides › Programming Guide for C › Directory API › Sequence of Function Calls › 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
);

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:

• Inactivity—A specified period of time has elapsed since the user has logged in.
• Failed login attempts—The user has reached a specified number of consecutive failed log in attempts.
• Expired password—The user has failed to make a required password change.
• Forced password change—The user is being forced to change his or her password. On the User Management dialog box, the administrator has checked User must change password at next login.

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.