Programming Guides › Programming Guide for C › Policy Management API › SM--Federation Security Services › Sm_PolicyApi_Scheme_t

Sm_PolicyApi_Scheme_t

Defines a SiteMinder authentication scheme object.

Syntax

typedef struct Sm_PolicyApi_Scheme_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                    /* Required */
   char pszDesc[BFSIZE];
   int nLevel;                              /* Required */
   char pszLib[BFSIZE];
   char pszParam[BFSIZE];
   char pszSecret[BFSIZE];
   bool bIsTemplate;
   bool bIsUsedbyAdmin;
   Sm_Api_SchemeType_t nType;               /* Required */
   bool bAllowSaveCreds;                    /* Required */
   bool bIsRadius;                          /* Required */
   bool bIgnorePwCheck;                     /* Required */
   struct Sm_PolicyApi_Scheme_s* next;
} Sm_PolicyApi_Scheme_t;

More Information:

Authentication Scheme Configuration

Sm_PolicyApi_SharedSecretPolicy_t

Defines a shared secret policy.

In the Administrative UI, a shared secret policy is defined in the Shared Secret Rollover tab of the Key Management dialog box.

Syntax

typedef struct Sm_PolicyApi_SharedSecretPolicy_s
{
   int iStructID;
   bool bIsEnabled;
   int iRolloverPeriod;
   int iRolloverFrequency;
} Sm_PolicyApi_SharedSecretPolicy_t;

Sm_PolicyApi_Server_t

Defines TCP/IP connectivity information for a Policy Server.

Syntax

typedef struct Sm_PolicyApi_Server_s
{
   int iStructId;
   char pszIpAddr[BFSIZE];                 /* Required */
   long nPort[3];
   long nClusterSeq;
   struct Sm_PolicyApi_Server_s* next;
} Sm_PolicyApi_Server_t;

Sm_PolicyApi_TrustedHost_t

Defines a trusted host object.

Syntax

typedef struct Sm_PolicyApi_TrustedHost_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];
   char pszDesc[BFSIZE];
   char pszIPAddr[BFSIZE];
   char pszSecret[BFSIZE];
   bool bIs4xHost;
   struct Sm_PolicyApi_TrustedHost_s* next;
   bool bRolloverEnabled;
} Sm_PolicyApi_TrustedHost_t;

Sm_PolicyApi_User_t

Defines a SiteMinder User object.

Syntax

typedef struct Sm_PolicyApi_User_s
{
   int iStructId;
   char pszUserPolicyOid[BFSIZE];            /* Required */
   char pszUserDirOid[BFSIZE];               /* Required */
   char pszPath[BFSIZE];                     /* Required */
   char pszClass[BFSIZE];                    /* Required */
   Sm_PolicyResolution_t nPolicyResolution;  /* Required */
   int nFlags;                               /* Required */
   struct Sm_PolicyApi_User_s* next;
} Sm_PolicyApi_User_t;

Sm_PolicyApi_UserContext_t

Makes user context information available to callers of the Policy Management API.

Syntax

typedef struct Sm_PolicyApi_UserContext_s
{
   int iStructId;
   Sm_Api_UserContext_t *pUserContext;
   struct Sm_PolicyApi_UserContext_s* next;
} Sm_PolicyApi_UserContext_t;

More Information:

Sm_PolicyApi_GetTrustedHostByName()

Sm_PolicyApi_UserDir_t

Defines a SiteMinder user directory object.

Syntax

typedef struct Sm_PolicyApi_UserDir_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                     /* Required */
   char pszDesc[BFSIZE];
   char pszNamespace[BFSIZE];                /* Required */
   char pszServer[BFSIZE];                   /* Required */
   char pszSearchRoot[BFSIZE];
   char pszUserLookupStart[BFSIZE];
   char pszUserLookupEnd[BFSIZE];
   char pszUsername[BFSIZE];
   char pszPassword[BFSIZE];
   int nSearchResults;                       /* Required */
   int nSearchScope;                         /* Required */
   int nSearchTimeout;                       /* Required */
   bool bSecureConnection;                   /* Required */
   bool bRequireCredentials;                 /* Required */
   char pszDisabledAttr[BFSIZE];
   char pszUniversalIDAttr[BFSIZE];
   char pszODBCQuerySchemeOid[BFSIZE];
   char pszAnonymousId[BFSIZE];
   char pszPasswordData[BFSIZE];
   char pszPasswordAttribute[BFSIZE];
   char pszEmailAddressAttr[BFSIZE];
   char pszChallengeRespAttr[BFSIZE];
   struct Sm_PolicyApi_UserDir_s* next;
} Sm_PolicyApi_UserDir_t;

Remarks

Fields apply to all types of directories (LDAP, ODBC, WinNT, and custom) unless individual directory types are specified.

Fields that apply to LDAP directories also apply to Active Directories.

Sm_PolicyApi_UserPasswordState_t

Information regarding all PasswordState virtual attributes is returned using the SmPolicyApi_UserPasswordState_t structure. This structure coexists with a User object, which is restricted by the UserDirectory OID and a User DN string. The structure can be retrieved, created, or updated through the C Policy Management API.

Syntax

typedef struct Sm_PolicyApi_UserPasswordState_s
{
   int iLoginFailures;
   time_t tLastLogin;
   time_t tPrevLogin;
   time_t tDisabled;
   time_t tLastPWChange;
} Sm_PolicyApi_UserPasswordState_t;

Sm_PolicyApi_Variable_t

Defines a variable object that can be used in a variable expression for a policy or a response. Variable objects are managed by the Variable Functions.

A variable is a dynamic object that is resolved to a value during an authorization request. The variables appear within an active expression defined for a policy or a response.

Variables are used as follows:

• With policies, variables are used as authorization constraints. When a user requests access to a resource, and the resource contains an active expression that includes one or more variables, the variables are resolved to values that pertain to the user. The values are then evaluated and used in the decision on whether to authorize the user.

  For example, suppose a policy that protects a bank's credit card application form contains an active expression with a Credit Rating variable and a Salary variable. When a user attempts to access the form, the user is authorized only if his credit rating and salary meet or exceed the minimum values for these variables.

• With responses, variables are used as return values. For example, a response attribute might be configured to return a transaction's tracking number obtained from a remote Web Service.

Syntax

typedef struct Sm_PolicyApi_Variable_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];
   char pszDesc[BFSIZE];
   char pszVariableTypeOid[BFSIZE];
   char pszDefinition[BFSIZE];
   char pszMetaData[BFSIZE];
   int nReturnType;
   bool bPreFetchFlag;
   char pszDomainOid[BFSIZE];
   Sm_PolicyApi_Oid_t* pNestedVariableList;
   struct Sm_PolicyApi_Variable_s*   next;
} Sm_PolicyApi_Variable_t;

Variable Definition

You define a variable by specifying where the variable's value can be found. You do so through the pszDefinition field.

The value of this field can be a simple string or a set of XML elements, depending on the variable type. Here are the SiteMinder variable types and a description of the pszDefinition field for each type:

• Post

  The pszDefinition field contains the name of a field on an HTML form. In a POST action, the variable value is derived from the value assigned to the field.

• RequestContext

  The pszDefinition field contains the following XML code:

  <RequestContextVariableDef>
     <ItemName></ItemName>
  </RequestContextVariableDef>
  

  The variable value depends upon which of the following attribute names appears within the ItemName element:

  • Action. With this item name, the variable value is the type of action specified in the request (for example, GET or POST).
  • Resource. With this item name, the variable value is the target resource (for example, /directory_name/).
  • Server. With this item name, the variable value is the full server name specified in the request (for example, server.company.com).
• Static

  The pszDefinition field contains the actual value that will be compared against the user-supplied data at runtime. For example, a Static variable of return type Sm_PolicyApi_VarReturnTypes_Date might be assigned the string value 2004-01-01. During authorization, this assigned date is compared against a user-supplied date.

• UserContext

  The pszDefinition field contains some or all of the following XML code:

  <UserContextVariableDef>
     <ItemName></ItemName>
     <PropertyName></PropertyName>
     <DN></DN>
     <BufferSize></BufferSize>
  </UserContextVariableDef>
  

  The variable value is based on an attribute of a user directory connection (such as session ID) or on the contents of the user directory (such as user name). The name of the attribute upon which the variable value is based appears in the XML element ItemName.

  The ItemName element can contain one of the following values:

  • DirectoryEntryProperty
  • DirectoryNameSpace
  • DirectoryPath
  • DirectoryServer
  • IsUserContext
  • SessionId
  • UserPath
  • UserProperty
  • UserName

  The elements PropertyName, DN, and BufferSize are only used as follows:

  • When ItemName contains DirectoryEntryProperty, elements PropertyName, DN, and BufferSize are used.
  • When ItemName contains UserProperty, elements PropertyName and BufferSize are used.
• WebService

  The pszDefinition field contains the following basic XML structure:

  <WebServiceVariableDefn xmlns:NeteWS=
                         "http://www.netegrity.com/2003/SM6.0";>
     <NeteWS:RemoteURL></NeteWS:RemoteURL>
     <NeteWS:SSL/>
        <NeteWS:RemoteMethod></NeteWS:RemoteMethod>
        <NeteWS:ResultQuery></NeteWS:ResultQuery>
        <NeteWS:AuthCredentials>
           <NeteWS:Username></NeteWS:Username>
           <NeteWS:Password></NeteWS:Password>
           <NeteWS:Hash></NeteWS:Hash>
        </NeteWS:AuthCredentials>
        <NeteWS:Document>
           <SOAP:Envelope xmlns:SOAP=
                   "http://schemas.xmlsoap.org/soap/envelope/";>
              <SOAP:Header></SOAP:Header>
              <SOAP:Body></SOAP:Body>
           </SOAP:Envelope>
        </NeteWS:Document>
  </WebServiceVariableDefn>
  

  To retrieve a variable value from a Web Service, the Policy Server sends the Web Service a SOAP request document as specified in pszDefinition, and then extracts the variable value from the SOAP response.

  The following table describes the XML elements used to configure a WebService variable:

Note: The XML element structures shown above are formatted for legibility. The XML string supplied through the pszDefinition field should not be formatted with spaces, tabs, and return characters. For example, a RequestContext variable for a Resource attribute would be passed in pszDefinition as follows:

<RequestContextVariableDef><ItemName>Resource</ItemName></RequestContextVariableDef>

Sm_PolicyApi_VariableType_t

Defines a supported variable object type. Variable types are read-only. They cannot be created or deleted through the Policy Management Variable Functions.

Syntax

typedef struct Sm_PolicyApi_VariableType_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];
   char pszDesc[BFSIZE];
   char pszFilter[BFSIZE];
   struct Sm_PolicyApi_VariableType_s*    next;
} Sm_PolicyApi_VariableType_t;

Sm_PolicyApi_WSFEDProviderProp_t

Defines a linked list of WS-Federation Provider properties, that is, name/value pairs.

An Sm_PolicyApi_WSFEDProviderProp_t structure consists of a single name/value pair. You define a set of properties for a given WS-Federation object through a linked list of Sm_PolicyApi_WSFEDProviderProp_t structures.

Syntax

typedef struct Sm_PolicyApi_WSFEDProviderProp_s
{
	int iStructId;
	char pszName[BFSIZE];
	char pszValue[BFSIZE];
	Sm_PolicyApi_WSFEDProviderProp_t* next;
} Sm_PolicyApi_WSFEDProviderProp_t;

Parameters

iStructId

ID of the structure in Sm_PolicyAp_Structs_t. Should be set to Sm_PolicyApi_WSFEDProviderProp_ID.

pszName

Name of the WS-Federation Provider property.

pszValue

Value of the WS-Federation Provider property.

next

Pointer to the next WS-Federation Provider property data in the linked list.

Each Sm_PolicyApi_WSFEDProviderProp_t structure contains a WS-Federation metadata property defined as a name/value pair. A complete set of properties for a particular object is defined as a linked list of Sm_PolicyApi_WSFEDProviderProp_t structures.

The following metadata properties apply to WS-Federation objects types:

• Common properties
• Properties for defining a Resource Partner
• Properties for defining an Account Partner

Optional properties are specified in square brackets.

For Boolean values, a value of 1 denotes true; any other value denotes false.

The Property Name column also includes the corresponidng C Policy Management API macro name.

Common Properties

The following table specifies the metadata properties that are common to defining a Resource Partner or an Account Partner:

Resource Partner Properties

The following table lists the metadata properties used to define a Resource Partner:

Account Partner Properties

The following table lists the metadata properties used to define an Account Partner:

Sm_PolicyApi_WSFEDResourcePartner_t

Defines WS-Federation Resource Partner data.

Syntax

typdef struct Sm_PolicyApi_WSFEDResourcePartner_s
{
	int iStructId;
	Sm_PolicyApi_WSFEDProviderProp_t* pProps;
	Sm_PolicyApi_WSFEDResourcePartner_t* next;
} Sm_PolicyApi_WSFEDResroucePartner_t;

Parameters

iStructId

ID of the structure in Sm_PolicyApi_Structs_t. Should be set to Sm_PolicyApi_WSFEDResourcePartner_ID.

pProp

Pointer to the linked list of Resource Partner properties.

next

Pointer to the next Resource Partner data in the linked list.

Exported Types

The Policy Management API includes various categories of exported data types, including:

• Administrator rights
• Attribute Mode
• Authentication and authorization mapping types
• Certificate mapping attribute types
• Certificate mapping directory types
• Certificate mapping flags definitions
• Directory capabilities
• Domain flags
• Group types
• IP address types
• Management commands
• Password messages
• Password message fields
• Password message field types
• Password policy behavior flags
• Policy flags
• Policy Management API initialization flags
• Policy object IDs
• Policy resolutions
• Return codes
• Scheme types
• Shared secret rollover parameters
• Structure IDs

Administrator Rights

Sm_PolicyApi_AdminRights_t enumerates the rights of the administrator. These values may be used individually or combined to set multiple rights. The resulting value is passed to Sm_PolicyApi_AddAdmin() as one of the attributes in a Sm_PolicyApi_Admin_t structure.

The following table shows how these values are used to set administrative privileges:

Affiliate Attribute Types

Sm_PolicyApi_AffiliateAttrType_t enumerates the valid affiliate attribute types, for use in the affiliate functions to manipulate affiliate attributes.

Attribute Mode Types

Sm_PolicyApi_SAMLSPAttrMode_t enumerates the valid attribute retrieval types for use in SAML 2.0 Attribute Authority support:

One of these values should be provided in the nMode element of the Sm_PolicyApi_SAMLSPAttr_t structure.

Authentication and Authorization Mapping Types

Sm_PolicyApi_AuthAzMapType_t enumerates the authentication and authorization mapping types.

Certificate Mapping Attribute Types

Sm_PolicyApi_CertMapAttrType_t enumerates types of mapping that determine how an X.509 client certificate will map to the user information in the authentication directory.

Certificate Mapping Directory Types

Sm_PolicyApi_DirType_t enumerates the types of directories that can be used to authenticate users.

Certificate Mapping Flags Definitions

Sm_PolicyApi_CertMapFlags_t enumerates flags that represent certificate mapping properties.

Directory Capabilities

Sm_PolicyApi_GetUserDirCapabilities() uses the values that are enumerated in Sm_DirectoryCapability_t, which is defined in SmApi.h.

Note: Attribute masks are directory user profile attributes. They are available in the directory. Each attribute is read-only or read-write. Read-write attributes are not used by other applications.

Domain Flags

Sm_PolicyApi_DomainFlags_t enumerates flags pertaining to domain-wide influence.

Group Types

Sm_PolicyApi_Groups_t enumerates the type of group for which you can perform group functions.

IP Address Types

Sm_PolicyApi_IPAddressType_t enumerates the type of IP address restrictions that are defined for an object in Sm_PolicyApi_IPAddress_t.

Management Commands

Sm_PolicyApi_ManagementCommands_t enumerates the values that can be passed to Sm_PolicyApi_ManagementCommand() for flushing caches, for managing agent encryption keys, and for shared secret rollover.

Initialize the structure to zero (memset) prior to setting any values. Use the symbolic enumerated values, rather than hard-coding integer command values.

The value is passed in the iCommand field of the structure Sm_PolicyApi_ManagementCommand_t.

Password Messages

Sm_PolicyApi_PasswordMsgId_t enumerates password message IDs.

Password messages describe the encoded error message returned to Sm_PolicyApi_SetPassword() when a new password does not satisfy the password policy requirements of the specified directory.

Additional information about the error message is available in the password message field associated with the password message.

Password Message Fields

Sm_PolicyApi_PasswordMsgFieldId_t enumerates password message field IDs.

Password message fields contain additional information about the password messages described in the previous section. You can find this additional information in the structure Sm_PolicyApi_PasswordMsgField_t.

Fields can be of type integer or string, or they can have no type.

Password Message Field Types

Sm_PolicyApi_FieldType_t enumerates the possible data types for the password message fields.

Password Policy Behavior Flags

Sm_PasswordPolicyBehavior_t enumerates the behavioral characteristics of a password policy.

Note: Values 0x00000400 through 0x00007c00 apply to password preprocessing. During preprocessing, the password is checked before it is processed or stored.

Policy Flags

Sm_PolicyApi_AddUsersToPolicy() uses the following values (which are defined in SmApi.h):

Policy Management API Initialization Flags

Sm_PolicyApi_InitFlags_t enumerates the initialization flags used by Sm_PolicyApi_Init(). These flags affect API behavior.

Policy Object IDs

Sm_PolicyApi_Objects_t describes the policy store properties that can be retrieved, set, and removed.

Note: Sm_PolicyApi_NULL_Domain_Props, value 0, is reserved.

The following table lists the domain object type values that can be passed to Sm_PolicyApi_GetDomainObjects():

The following table lists the global object type names that can be passed to Sm_PolicyApi_GetGlobalObjects():

Policy Resolutions

Sm_PolicyResolution_t, defined in SmApi.h, enumerates the values that describe the relationship between two policy objects.

More Information:

Sm_PolicyResolution_t

Return Codes

The value codes that can be returned by the API are enumerated in Sm_PolicyApi_Status_t. The values have the following significance:

• A zero return code indicates success.
• Negative return codes indicate failure.

Most of the code names are self-explanatory. However, note that Sm_PolicyApi_BadArgument (-10) is returned when one or more of the required input parameters is not supplied. For example, if an argument such as a domain OID is null or represents a string of zero length, Sm_PolicyApi_BadArgument is returned to the caller.

Return codes with values less than -100 (except for Sm_PolicyApi_NotUnique, value -105) will rarely be returned by this API. They are included for completeness.

SAML1x Redirect URL Types

Sm_PolicyApi_SAML1_STATUS_REDIRECT_URL_TYPE_t defines the type of redirection specified in Sm_PolicyApi_AddRedirectURLToSAML1xScheme() and Sm_PolicyApi_GetRedirectURLFromSAML1xScheme().

Sm_PolicyApi_SAML1_STATUS_REDIRECT_URL_TYPE_t is listed in SmPolicyApi45.h.

SAML Assertion Consumer Service Bindings

The following values are the SAML Protocol Bindings that can be specified for each row of the Assertion Consumer Service:

SAML Attribute Name Format Identifiers

Sm_PolicyApi_SAMLSPAttrNameFormat_t defines the format to use for specifying attributes that apply to a principal. The format specification is made within the structure Sm_PolicyApi_SAMLSPAttr_t.

The format identifiers are defined by the SAML 2.0 standard.

Sm_PolicyApi_SAMLSPAttrNameFormat_t is listed in SmPolicyApi45.h.

SAML Profiles

Sm_PolicyApi_SAML_Profile_t specifies the communication profile used to send and receive a SAML assertion for a particular affiliate object. The profile is specified as one of the attributes of a Sm_PolicyApi_Affiliate_t structure. Sm_PolicyApi_SAML_Profile_t is listed in SmPolicyApi45.h.

Scheme Types

Sm_Api_SchemeType_t describes the values that may be passed to Sm_PolicyApi_AddScheme() as one of the attributes of a SmPolicyApi_Scheme_t structure. Sm_Api_SchemeType_t is listed in SmApi.h.

Shared Secret Rollover Parameters

Sm_PolicyApi_SecretRolloverPeriod_t enumerates the units of time which, when combined with the rollover frequency setting, determines how often shared secret rollover occurs. For example a rollover period of RolloverHOURS and a frequency of 12 means that the shared secret is changed every 12 hours.

The rollover period is defined in the iRolloverPeriod field of structure Sm_PolicyApi_SharedSecretPolicy_t, and the frequency is defined in the iRolloverFrequency field of the structure.

Structure IDs

Sm_PolicyApi_Structs_t enumerates the data structures that can be passed to and from the Policy Management API as follows:

Structure of a Policy Application

Policy applications must perform the following operations:

• Initialization: Sm_PolicyApi_Init() or Sm_PolicyApi_InitEx() must be the first function called by the API client session. The function initializes the connection to the SiteMinder policy store and establishes the init handle. (The init handle is passed in calls to Sm_PolicyApi_Login() and Sm_PolicyApi_Release().)
• Login: Sm_PolicyApi_Login() must be called after initialization and before making calls to the other functions in the API. This function can check the administrator's login credentials (username and password) or the administrator's validity.
  If the administrator is authenticated, the function initializes internal data structures and resources. Once the administrator is logged in, the Policy Server initializes a handle that is used as an input parameter to subsequent Policy Management API functions. Sm_PolicyApi_Login() can be called more than once during the client session.
• Logout: Sm_PolicyApi_Logout() logs out the administrator.
• Release: Sm_PolicyApi_Release() must be the last function called by the API client session. It disconnects from the policy store and releases memory and resources held by the API. This function must be called once per client session. Failure to call this function will result in a memory leak.

Functions by Category in the Policy Management API

Most of the functions in the Policy Management API are categorized according to the SiteMinder policy store object (for example, an agent, policy, or rule) that a given function acts upon. There are additional categories-required functions, user state functions, and utility functions such as cache and agent encryption key management-that are categorized by the type of service that certain functions perform.

Use these categories to help you find a particular Policy Management API function to use in your custom policy management applications.

The categories of Policy Management API functions include:

• Required Functions
• Administrator Functions
• Agent Functions
• Agent Configuration Functions
• Authentication/Authorization Map Functions
• Authentication Scheme Functions
• Certificate Mapping Functions
• Domain Functions
• Federation Functions
• General Object Functions
• Group Functions
• ODBC Query Scheme Functions
• Password Policy Functions
• Policy Functions
• Realm Functions
• Registration Scheme Functions
• Regular Expression Functions
• Response Functions
• Rule Functions
• SAML 2.0 Attribute Authority Functions
• SAML 2.0 Configuration Functions
• SAML 2.0 Indexed Endpoint Functions
• User Directory Functions
• User and User State Functions
• User Password State Functions
• Utility Functions
• Variable Functions
• WS-Federation Functions

Required Functions

The following functions must be used in all policy management applications:

Administrator Functions

The following functions manage SiteMinder administrator objects:

Agent Functions

The following functions manage SiteMinder agent objects.

Note: There is no facility for creating Agent Types or Agent Type attributes.

Agent Configuration Functions

The following functions manage configuration objects (agent configuration objects, host configuration objects, and trusted host objects) for centrally configuring agents.

Trusted hosts are created in any of the following ways:

• During agent installation
• Through the command line using the smreghost tool. For information about using this tool, see Web Agent Installation Guide.
• Through the Sm_PolicyApi_AddTrustedHost() function.

  
  

Authentication/Authorization Map Functions

The following functions manage SiteMinder authentication and authorization directory mapping objects:

Authentication Scheme Functions

The following functions manage SiteMinder authentication schemes:

Certificate Mapping Functions

The following functions manage SiteMinder certificate mapping objects:

Domain Functions

The following functions manage SiteMinder domain objects:

Federation Functions

The following functions support the manipulation of Policy Store data (Affiliate Domain and Affiliate objects) required to generate SAML assertions.

General Object Functions

The following functions act on multiple types of SiteMinder objects:

Group Functions

The following functions manage SiteMinder group objects. You can create agent groups, response groups, and rule groups, as enumerated in Sm_PolicyApi_Groups_t.

Note: Groups of global objects are not supported.

A group can contain individual items or groups of its own type. For example, a rule group can contain rules and/or groups of rules.

ODBC Query Scheme Functions

The following functions manage SiteMinder ODBC query schemes:

Password Policy Functions

The following functions manage SiteMinder password policy objects:

Policy Functions

The following functions manage SiteMinder policy and policy link objects. A policy link is an association of a policy, a rule, and optionally, a response.

Realm Functions

The following functions manage SiteMinder realms objects:

Registration Scheme Functions

The following functions manage SiteMinder registration schemes:

Regular Expression Functions

The following functions manage SiteMinder regular expressions:

Response Functions

The following functions manage SiteMinder response objects:

Rule Functions

The following functions manage SiteMinder rule objects:

SAML1.x Configuration Functions

The following functions provide support for SAML 1.x configuration settings:

SAML 2.0 Attribute Authority Functions

The following functions managed attributes for a SAML Requester:

SAML 2.0 Configuration Functions

The following functions manage SAML 2.0 affiliations, Service Providers, and Identity Providers.

SAML 2.0 Indexed Endpoint Functions

The following functions manage indexed endpoints in the Service Provider:

User Directory Functions

The following functions manage SiteMinder user directory objects:

User and User State Functions

The following functions perform operations on user state and on user entries in a SiteMinder user directory:

User Password State Functions

The following functions manage SiteMinder password state objects:

Utility Functions

The following functions provide a variety of services, including memory, cache, and agent encryption key management:

Variable Functions

The following methods manage variables.

WS-Federation Functions

The following table lists the supported functions for Resource Partners and Account Partners:

Function Declarations for the Policy Management API

Function declarations include the syntax and return values for each function in the Policy Management API for reference.

Sm_PolicyApi_AddAdmin()

Creates a new SiteMinder administrator object at a global scope. The administrator's attributes are contained in the pstructAdmin structure.

If the administrator object exists and bUpdate is true, the item is updated.

Type

Administrator function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddAdmin (
   void*                    pSessionHandle,
   Sm_PolicyApi_Admin_t*    pstructAdmin,
   const bool               bUpdate
);

Returns

• Sm_PolicyApi_Success. The administrator object was created successfully.
• Sm_PolicyApi_Failure. The administrator object was not created successfully.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create an administrator object.
• Sm_PolicyApi_InvalidOid:
  • The administrator object identifier was not found during an update.
  • The user directory object identifier was not found.
  • The scheme object identifier was not found.

Sm_PolicyApi_AddAdminToAffiliateDomain()

Adds an administrator to an affiliate domain.

Type

Federation function

Syntax

int SM_EXTERN Sm_PolicyApi_AddAdminToAffiliateDomain (
   void*        pSessionHandle,
   const char*  pszAdminOid,
   const char*  pszAffiliateDomainOid
);

Returns

• Sm_PolicyApi_Success. The administrator was added to the affiliate domain.
• Sm_PolicyApi_Failure. The administrator was not added to the affiliate domain.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to delete an affiliate domain.
• Sm_PolicyApi_InvalidOid. The affiliate domain OID was not found during an update.
• Sm_PolicyApi_DuplicateEntry. The specified administrator object identifier already exists in the affiliate domain

Sm_PolicyApi_AddAdminToDomain()

Gives the specified administrator permission to administer the specified domain, and associates the administrator object identified by szAdminOid with the domain identified by szDomainOid.

Type

Administrator function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddAdminToDomain (
   void*            pSessionHandle,
   const char*      pszAdminOid,
   const char*      pszDomainOid
);

Returns

• Sm_PolicyApi_Success. The administrator was added to the domain.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to add an administrator to a domain.
• Sm_PolicyApi_InvalidOid. The administrator object identifier or the domain object identifier was not found.
• Sm_PolicyApi_DuplicateEntry. The specified administrator object identifier already exists in the domain.

Sm_PolicyApi_AddAffiliate()

Creates a new or updates an existing affiliate object. This function will also retrieve the PropertyCollection object based on the AffiliateDomain OID.

Type

Federation function

Syntax

int SM_EXTERN Sm_PolicyApi_AddAffiliate (
   void*                       pSessionHandle,
   Sm_PolicyApi_Affiliate_t*   pstructAffiliate,
   const bool                  bUpdate
);

Remarks

This function creates affiliate objects that are based on the artifact profile or the POST profile (see the Sm_PolicyApi_Affiliate_t field SAMLProfile). Creating an affiliate object based on the POST profile requires an API version of at least SM_POLICY_API_VERSION_6_0_2. If an earlier version is involved, the POST profile request is ignored (along with any POST-specific fields in Sm_PolicyApi_Affiliate_t) and an attempt is made to create an affiliate object based on the artifact profile.

Returns

• Sm_PolicyApi_Success. The affiliate was created successfully.
• Sm_PolicyApi_Failure. The affiliate was not created successfully.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create an affiliate.
• Sm_PolicyApi_DomainNotFound. The affiliate domain OID was not found.
• Sm_PolicyApi_DomainNotAffiliate. The domain is not an affiliate domain.

Sm_PolicyApi_AddAffiliateDomain()

Creates a new or updates an existing affiliate domain. Sets bIsAffiliate to TRUE.

Type

Federation function

Syntax

int SM_EXTERN Sm_PolicyApi_AddAffiliateDomain (
   void*                           pSessionHandle,
   Sm_PolicyApi_AffiliateDomain_t  *pstructAffiliateDomain,
   const bool                      bUpdate
);

Returns

• Sm_PolicyApi_Success. The affiliate domain was created successfully.
• Sm_PolicyApi_Failure. The affiliate domain was not created successfully.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create an affiliate domain.
• Sm_PolicyApi_DomainNotFound. The affiliate domain OID was not found during an update.
• Sm_PolicyApi_DomainNotAffiliate. The domain is not an affiliate domain.

Sm_PolicyApi_AddAgent()

Creates a new SiteMinder agent. The attributes of the agent are contained in the pstructAgent structure.

If the agent exists and the bUpdate flag is true, the item is updated.

You must specify an agent type with this call. To get the agent type OID for the agent, use Sm_PolicyApi_GetGlobalObjects().

Type

Agent function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddAgent (
   void*                   pSessionHandle,
   Sm_PolicyApi_Agent_t*   pstructAgent,
   const bool              bUpdate
);

Returns

• Sm_PolicyApi_Success. The agent was created successfully.
• Sm_PolicyApi_Failure. The agent was not created successfully.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create an agent.
• Sm_PolicyApi_InvalidOid:
  • The agent type OID was not found or is not of the specified agent type.
  • The agent OID was not found. This happens when this function is called with bUpdate set to true and the pszOid field of Sm_PolicyApi_Agent_t holds the OID of the agent being updated.
• Sm_PolicyApi_NotUnique. An agent with the same name exists.
• Sm_PolicyApi_RadiusIpAddrNotUnique. Another RADIUS IP address exists that is the same.
• Sm_PolicyApi_MissingProperty. One of the required fields is not set.

Sm_PolicyApi_AddAgentConfig()

Creates or modifies an agent configuration object in the policy store.

Type

Agent configuration function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddAgentConfig (
   void*                            pSessionHandle,
   Sm_PolicyApi_AgentConfig_t*      pstructAgentConfig,
   const bool                       bUpdate
);

Returns

• Sm_PolicyApi_Success. The operation was successful.
• Sm_PolicyApi_Failure. Generalized failure.
• Sm_PolicyApi_InvalidOid. The unique ID does not correspond to an agent configuration object.
• Sm_PolicyApi_NoPrivilege. The caller does not have the privilege to add or modify an agent configuration object.
• Sm_PolicyApi_InvalidHandle. The session pointer is not valid.
• Sm_PolicyApi_NoSession. The API user is not properly logged in.

Sm_PolicyApi_AddAgentConfigAssociation()

Adds or modifies a configuration parameter name and corresponding value in a specified agent configuration object.

Type

Agent configuration function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddAgentConfigAssociation (
   void*                            pSessionHandle,
   const char*                      pszAgentConfigOid,
   Sm_PolicyApi_Association_t*      pstructAssociation,
   bool                             bUpdate
);

Returns

• Sm_PolicyApi_Success. The operation was successful.
• Sm_PolicyApi_Failure. Generalized failure.
• Sm_PolicyApi_InvalidOid. The unique ID does not correspond to an agent configuration object.
• Sm_PolicyApi_NoPrivilege. The caller does not have the privilege to add agent configuration object parameters.
• Sm_PolicyApi_InvalidHandle. The session pointer is not valid.
• Sm_PolicyApi_NoSession. The API user is not properly logged in.

Sm_PolicyApi_AddAssertionConsumerServiceToSAMLSP

Adds a new indexed endpoint, which includes an index, binding, and an Assertion Consumer Service URL, to the Service Provider.

Note: An existing indexed endpoint reference cannot be modified.

Type

Federation function

Syntax

int SM_EXTERN Sm_PolicyApi_AddAssertionConsumerServiceToSAMLSP (
   void*                               pSessionHandle,
   const Sm_PolicyApi_SAMLSPAssertionConsumerService_t* 
                pstructSAMLSPAssertionConsumerService,
   const char*                         pszSAMLSPOid
);

Returns

• Sm_PolicyApi_Success. The Assertion Consumer Service was added successfully.
• Sm_PolicyApi_Failure - The Assertion Consumer Service was not added successfully.
• Sm_PolicyApi_ACSDuplicateIndex - There is already an Assertion Consumer Service assigned to thei Service Provider with the same index value.
• Sm_PolicyApi_InvalidHandle - There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession - There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege - The administrator does not have the privilege to add an Assertion Consumer Service.

Remarks

The following fields of the Sm_PolicyApi_SAMLSPAssertionConsumerService_t structure are evaluated:

• The value of the index is a unique positive integer, less than 65535,
• The Assertion Consumer URL starts with http:// or https://.
• The binding is either HTTP-Post or HTTP_Artifact.

Sm_PolicyApi_AddAttributeToAffiliate()

Adds a new attribute to an affiliate.

Type

Federation function

Syntax

int SM_EXTERN Sm_PolicyApi_AddAttributeToAffiliate (
   void*                               pSessionHandle,
   const Sm_PolicyApi_AffiliateAttr_t* pstructAffiliateAttr,
   const char*                         pszAffiliateOid
);

Returns

• Sm_PolicyApi_Success. The affiliate attribute was created successfully.
• Sm_PolicyApi_Failure - The affiliate attribute was not created successfully.
• Sm_PolicyApi_InvalidHandle - There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession - There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege - The administrator does not have the privilege to create an affiliate attribute.
• Sm_PolicyApi_InvalidOid - The affiliate OID was not found.

Sm_PolicyApi_AddAttributeToSAMLScheme()

Adds an attribute, which can be requested from the configured Attribute Service, to a SAML 2.0 authentication scheme.

Syntax

int SM_EXTERN Sm_PolicyApi_AddAttributeToSAMLScheme(
   void*                                pHandle,
   const Sm_PolicyApi_Scheme_t*         pstructScheme,
   const Sm_PolicyApi_SAMLRequesterAttr_t*     pAttr
);

Returns

• Sm_PolicyApi_Success. The attribute was added successfully.
• Sm_PolicyApi_Failure. The attribute was not added successfully.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to add an attribute to a SAML Requester.
• Sm_PolicyApi_SAMLIDP_IncorrectParameters. Supplied SAML provided properties are incomplete or incorrect.
• Sm_PolicyApi_DuplicateAttribute. An attribute already exists with the same Name and NameFormat.

Sm_PolicyApi_AddAttributeToSAMLSP()

Defines a SAML 2.0 attribute for the Service Provider.

A SAML 2.0 attribute contains information about a principal who is trying to access a resource on the Service Provider-for example, the principal's user DN.

The defined attribute is included in an attribute statement for all SAML 2.0 assertions that are produced for the Service Provider.

Type

SAML 2.0 Configuration function, domain scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddAttributeToSAMLSP (
   void*                                pHandle,
   const Sm_PolicyApi_SAMLSPAttr_t*     pstructSAMLSPAttr,
   const char*                          pszSAMLSPOid
);

Returns

• Sm_PolicyApi_Success. The attribute was added successfully.
• Sm_PolicyApi_Failure. The attribute was not added successfully.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to add an attribute to a SAML Service Provider.
• Sm_PolicyApi_DuplicateAttribute. An attribute already exists with the same Name and NameFormat.

Sm_PolicyApi_AddDomain()

Creates a new SiteMinder domain. Attributes of the domain are contained in the pstructDomain structure.

If the domain exists and the bUpdate flag is true, the item is updated.

Type

Domain function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddDomain (
   void*                    pSessionHandle,
   Sm_PolicyApi_Domain_t*   pstructDomain,
   const bool               bUpdate
);

Returns

• Sm_PolicyApi_Success. The domain was created successfully.
• Sm_PolicyApi_Failure. The domain was not created successfully.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create a domain.
• Sm_PolicyApi_InvalidOid. The domain OID was not found during an update.

Sm_PolicyApi_AddGlobalPolicy()

Creates a new global policy in the object store. The policy attributes are contained in the pStructPolicy structure.

If the policy exists and the bUpdate flag is true, the item is updated.

Type

Policy function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddGlobalPolicy (
   void*                    pSessionHandle,
   Sm_PolicyApi_Policy_t*   pStructPolicy,
   const bool               bUpdate
);

Returns

• Sm_PolicyApi_Success. The global policy was created successfully.
• Sm_PolicyApi_Failure. The global policy was not created successfully.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create a global policy.
• Sm_PolicyApi_NotImplemented: The client who called this function initialized the API with a version less than SM_POLICY_API_VERSION_6_0.

Sm_PolicyApi_AddGlobalResponse()

Creates a new global response in the object store.

Type

Rule function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddGlobalResponse (
   void*                      pSessionHandle,
   Sm_PolicyApi_Response_t*   pStructResponse,
   const bool                 bUpdate
);

Returns

• Sm_PolicyApi_Success. The global response was created successfully.
• Sm_PolicyApi_Failure. The global response was not created successfully.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create a global response.
• Sm_PolicyApi_InvalidOid: A global response with a matching OID was not found during an update.
• Sm_PolicyApi_NotImplemented: The client who called this function initialized the API with a version less than SM_POLICY_API_VERSION_6_0.

Sm_PolicyApi_AddGlobalRule()

Creates a new global rule in the object store.

Type

Rule function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddGlobalRule (
   void*                   pSessionHandle,
   Sm_PolicyApi_Rule_t*    pStructRule,
   const bool              bUpdate
);

Returns

• Sm_PolicyApi_Success. The global rule was created successfully.
• Sm_PolicyApi_Failure. The global rule was not created successfully.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create a global rule.
• Sm_PolicyApi_InvalidOid:
  • A global rule with a matching OID was not found during an update.
  • An agent or agent group with matching OID was not found.
• Sm_PolicyApi_NotImplemented: The client who called this function initialized the API with a version less than SM_POLICY_API_VERSION_6_0.

Sm_PolicyApi_AddGroup()

Adds a new group object to the Siteminder policy store. The attributes of the group are contained in the pStructGroup structure.

Note: Groups of global objects are not supported.

The pszDomainOid parameter is required by a rule group or response group. An agent group does not require a domain OID because it is not a domain-based object.

If the group object exists and the bUpdate flag is true, the item is updated.

Type

Group function, global scope (agents) or domain scope (responses, rules).

Syntax

int SM_EXTERN Sm_PolicyApi_AddGroup (
   void*                    pSessionHandle,
   Sm_PolicyApi_Groups_t    dwGroup,
   const char*              pszDomainOid,
   Sm_PolicyApi_Group_t*    pStructGroup,
   const bool               bUpdate
);

Returns

• Sm_PolicyApi_Success. The add was successful.
• Sm_PolicyApi_Failure. The add was not successful.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to add a group.
• Sm_PolicyApi_InvalidOid. The domain OID was not found (for a domain-based group).
• Sm_PolicyApi_BadGroup. The dwGroup parameter is not the rule, response, or agent group type.

Sm_PolicyApi_AddHostConfig()

Creates or updates a host configuration object in the policy store.

Type

Agent configuration function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddHostConfig (
   void*                            pSessionHandle,
   Sm_PolicyApi_HostConfig_t*       pstructHostConfig,
   const bool                       bUpdate
);

Returns

• Sm_PolicyApi_Success. The operation was successful.
• Sm_PolicyApi_Failure. Generalized failure.
• Sm_PolicyApi_InvalidOid. The unique ID does not correspond to a host configuration object.
• Sm_PolicyApi_NoPrivilege. The caller does not have the privilege to create or modify a host configuration object.
• Sm_PolicyApi_InvalidHandle. The session pointer is not valid.
• Sm_PolicyApi_NoSession. The API user is not properly logged in.

Sm_PolicyApi_AddMessageConsumerPluginToSAML1xScheme()

Adds or updates a message consumer plugin setting to a SAML 1.x authentication scheme.

Syntax

int SM_EXTERN Sm_PolicyApi_AddMessageConsumerPluginToSAML1xScheme(
   void*    pHandle,
   char*    pszSchemeOID,
   char*    pluginClass,
   char*    pluginParam                        
);

Parameters

phandle

[in] A pointer to an internal Policy Management API data structure. The structure holds information about the administrator session and the client session.

pszSchemeOid

[in] A pointer to the OID of the authentication scheme that is being updated.

pluginClass

[in] A pointer to the name of the message consumer plugin class to be set.

pluginParam

[in] A pointer to the parameters of the message consumer plugin class to be set.

Returns

• Sm_PolicyApi_Success. The action was completed successfully.
• Sm_PolicyApi_Failure. The action was unsuccessful.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_SchemeNotFound. The authentication scheme corresponding to the OID was not found, or was not a SAML 1.x authentication scheme.
• Sm_PolicyApi_InvalidOid. The OID of the authentication scheme is NULL.

Sm_PolicyApi_AddOneTimeUsePropToAffiliate()

Adds or updates the OneTimeUse property for an assertion in a SAML 1.x affiliate.

Syntax

int SM_EXTERN Sm_PolicyApi_AddOneTimeUsePropToAffiliate(
   void*    pHandle,
   char*    pszAffiliateOID,
   bool     bOneTimeUse
                           
);

Parameters

pHandle

[in] A pointer to an internal Policy Management API data structure. The structure holds information about the administrator session and the client session.

pszAffiliateOid

[in] A pointer to the OID of an existing SMAL 1.x affiliate.

bOneTimeUse

[in] A Boolean value that specifies whether an assertion is used only once in this affiliate.

Returns

• Sm_PolicyApi_Success. The action was completed successfully.
• Sm_PolicyApi_Failure. The action was unsuccessful.
• Sm_PolicyApi_NoSession. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoPrivilege. The administrator did not have sufficient access privileges.

Sm_PolicyApi_AddPasswordPolicy()

Adds a password policy object.

Note the following about Sm_PolicyApi_PasswordPolicy_t:

• When the password policy applies to an entire directory (bEntireDir is set to true), you must set pszPath and pszClass to an empty string. The Policy Management API returns Sm_PolicyAPI_BadArgument if these strings are not empty.
• When the pszPasswordServicesRedirect field is set to an empty string, the Policy Management API sets it to a default URL:

  /siteminderagent/forms/smpwservices.fcc
  

Type

Password policy function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddPasswordPolicy (
   void*                            pSessionHandle,
   Sm_PolicyApi_PasswordPolicy_t*   pstructPasswordPolicy,
   const bool                       bUpdate
);

Returns

• Sm_PolicyApi_Success. The create was successful.
• Sm_PolicyApi_Failure. The create was not successful.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create a password policy.
• Sm_PolicyApi_InvalidOid:
  • The password policy OID was not found during an update.
  • The user directory OID was not found.
• Sm_PolicyApi_BadArgument. The path and class are empty.

Sm_PolicyApi_AddPolicy()

Creates a new SiteMinder policy. The policy attributes are contained in the pStructPolicy structure.

If the policy exists and the bUpdate flag is true, the item is updated.

Type

Policy function, domain scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddPolicy (
   void*                    pSessionHandle,
   Sm_PolicyApi_Policy_t*   pStructPolicy,
   const bool               bUpdate
);

Returns

• Sm_PolicyApi_Success. The policy was created successfully.
• Sm_PolicyApi_Failure. The policy was not created successfully.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create a policy.
• Sm_PolicyApi_InvalidOid:
  • The policy OID was not found during an update.
  • The domain OID was not found.

Sm_PolicyApi_AddPolicyLink()

Creates a new SiteMinder policy link for the policy identified by pszPolicyOid.

A policy link object binds a policy to a rule and, optionally, a response. The attributes of the new policy link are contained in the pstructPolicyLink structure.

If the policy link exists and the bUpdate flag is true, the item is updated.

Type

Policy function, domain scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddPolicyLink (
   void*                         pSessionHandle,
   const                         pszPolicyOid, 
   Sm_PolicyApi_PolicyLink_t*    pstructPolicyLink
);

Returns

• Sm_PolicyApi_Success. The policy link was created successfully.
• Sm_PolicyApi_Failure:
  • The domain of a rule OID is not the same as the domain of the policy OID.
  • The domain of a response OID is not the same as the domain of the policy OID.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create a policy link.
• Sm_PolicyApi_InvalidOid:
  • The policy OID was not found.
  • The rule or rule group OID was not found.
  • The response or response group OID was not found.

Sm_PolicyApi_AddRealm()

Creates a new SiteMinder realm within the domain specified in pStructRealm. The pStructRealm structure also contains other attributes of the realm, including the agent or agent group that protects the realm.

Sm_PolicyApi_AddRealm() fails if a protecting agent or agent group is not specified.

If the new realm is a top-level realm, set pszParentRealmOid (in Sm_PolicyApi_Realm_t) to the domain OID. Otherwise, set pszParentRealmOid to the OID of the new realm's parent realm.

If the realm exists and the bUpdate flag is true, the existing item is updated.

It is the responsibility of the client application to meet the following conditions in order to add an authorization directory to a realm successfully:

• The directory mapping between the authorization user directory and authentication user directory should exist.

  Note: The Policy Management API checks only to see if the authorization user directory exists. It does not validate if there is a directory mapping for the given authorization user directory.

• The associated authentication user directory should be present in the user directory collection of the domain.

Type

Realm function, domain scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddRealm (
   void*                    pSessionHandle,
   Sm_PolicyApi_Realm_t*    pStructRealm,
   const bool               bUpdate
);

Returns

• Sm_PolicyApi_Success. The realm was created successfully.
• Sm_PolicyApi_Failure. The realm was not created successfully.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create a realm.
• Sm_PolicyApi_InvalidOid:
  • The realm OID was not found during an update.
  • The domain OID was not found.
  • The agent OID or agent group OID was not found.
  • The scheme OID was not found.
  • The parent OID could not be found. (The parent OID can be a realm OID or a domain OID.)

Sm_PolicyApi_AddRedirectURLToSAML1xScheme()

Adds or updates a redirect URL setting in a SAML 1.x authentication scheme.

Syntax

int SM_EXTERN Sm_PolicyApi_AddRedirectURLToSAML1xScheme(
        void*        pSessionHandle,
        const char*  pszSchemeOid,
        int          iTypeURL,
        char*        URL,
        int          redirectMode
);

Parameters

pSessionHandle

[in] A pointer to an internal Policy Management API data structure. The structure holds information about the administrator session and the client session.

pszSchemeOid

[in] A null-terminated string containing the object identifier of the authentication scheme being updated.

iTypeUrl

[in] An integer specifying the type of redirect URL, defined in Sm_PolicyAPI_SAML1_STATUS_REDIRECT_URL_TYPE_t as follows:

• Sm_PolicyAPI_SAML1_STATUS_REDIRECT_URL_USER_NOT_FOUND_TYPE = 0
• Sm_PolicyAPI_SAML1_STATUS_REDIRECT_URL_INVALID_SSO = 1
• Sm_PolicyAPI_SAML1_STATUS_REDIRECT_URL_UNACCEPTABLE_USER_CREDENTIALS = 2

URL

[in] A pointer to the input redirect URL.

redirectMode

[in] An integer specifying the input redirect mode, which is either 0 for 302 No Data, or 1 for Http-Post.

Return Values

• Sm_PolicyApi_Success. The action was completed successfully.
• Sm_PolicyApi_Failure. The action was unsuccessful.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_SchemeNotFound. The authentication scheme corresponding to the OID was not found, or was not a SAML 1.x authentication scheme.
• Sm_PolicyApi_InvalidOid. The OID of the authentication scheme is NULL.

Sm_PolicyApi_AddRegistrationScheme()

Adds a registration scheme.

Type

Registration scheme function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddRegistrationScheme (
   void*                         pSessionHandle,
   Sm_PolicyApi_RegistrationScheme_t* 
                                 pstructRegistrationScheme,
   const bool                    bUpdate
);

Returns

• Sm_PolicyApi_Success. The registration scheme was created successfully.
• Sm_PolicyApi_Failure. The registration scheme was not created successfully.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create a registration scheme.
• Sm_PolicyApi_InvalidOid:
  • The registration scheme object identifier was not found during an update.
  • The user directory object identifier was not found.

Sm_PolicyApi_AddRegularExpressionToPasswordPolicy()

Adds a regular expression to the referenced password policy. Implemented only if the session's version is set to SM_POLICY_API_VERSION_6_0.

Type

Regular Expression function.

Syntax

int SM_EXTERN    Sm_PolicyApi_AddRegularExpressionToPasswordPolicy (
   void*                              pSessionHandle,
   const char*                        pszPasswordPolicyOid,
   Sm_PolicyApi_RegularExpression_t*  pstructRegExpr
);

Returns

• Sm_PolicyApi_Success. The regular expression was added successfully.
• Sm_PolicyApi_Failure. The regular expression was not added successfully.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to add a regular expression.
• Sm_PolicyApi_InvalidOid: The password policy OID was not found.

Sm_PolicyApi_AddResponse()

Creates a new SiteMinder response. The attributes of the response itself are contained in the pStructResponse structure.

If the response exists, and the bUpdate flag is true, the item is updated.

Type

Response function, domain scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddResponse (
   void*                      pSessionHandle,
   Sm_PolicyApi_Response_t*   pStructResponse,
   const bool                 bUpdate
);

Returns

• Sm_PolicyApi_Success. The response was created successfully.
• Sm_PolicyApi_Failure. The response was not created successfully.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create a response.
• Sm_PolicyApi_InvalidOid:
  • The response OID was not found during an update.
  • The domain OID was not found.
  • The agent type OID was not found.

Sm_PolicyApi_AddResponseAttr()

Creates a new SiteMinder response attribute object within the response identified by pszResponseOid. The response attributes are contained in the pstructResponseAttr parameter.

Type

Response function, domain scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddResponseAttr (
   void*                         pSessionHandle,
   const char*                   pszResponseOid,
   Sm_PolicyApi_ResponseAttr_t*  pstructResponseAttr
);

Returns

• Sm_PolicyApi_Success. The response attribute was added successfully.
• Sm_PolicyApi_Failure. The response attribute was not added successfully.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to add a response attribute.
• Sm_PolicyApi_InvalidOid:

The response OID was not found.

• The agent type attribute OID was not found.

Sm_PolicyApi_AddRule()

Creates a new SiteMinder rule. The attributes of the rule itself are contained in the structure referenced by pStructRule.

If the rule exists and the bUpdate flag is true, the item is updated.

Note: A rule is always associated with a realm. Rule names are unique within in a realm but not within a domain.

Type

Rule function, domain scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddRule (
   void*                   pSessionHandle,
   Sm_PolicyApi_Rule_t*    pStructRule,
   const bool              bUpdate
);

Returns

• Sm_PolicyApi_Success. The rule was created successfully.
• Sm_PolicyApi_Failure. The rule was not created successfully.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create a rule.
• Sm_PolicyApi_InvalidOid:
  • The rule OID was not found during an update.
  • The realm OID was not found.

Sm_PolicyApi_AddSAMLAffiliation()

Adds a new SAML affiliation object or modifies an existing one.

Type

SAML 2.0 Configuration function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddSAMLAffiliation (
   void*                              pSessionHandle,
   Sm_PolicyApi_SAMLAffiliation_t*    pstructAffiliation,
   const bool                         bUpdate,
   char**                             pszErrMsg
);

Returns

• Sm_PolicyApi_Success. The operation was successful.
• Sm_PolicyApi_Failure. The operation was not successful.
• Sm_PolicyApi_InvalidProp. A specified property is invalid. The property name is returned in pszErrMsg.
• Sm_PolicyApi_MissingProperty. A required property was not specified. The property name is returned in pszErrMsg.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create a SAML affiliation.
• Sm_PolicyApi_InsufficientData. Required properties for configuring the SAML affiliation were missing.

Sm_PolicyApi_AddSAMLScheme()

Adds a new SAML 2.0 authentication scheme object or modifies an existing one. This function also defines metadata properties for the associated Identity Provider. The metadata properties are stored with the authentication scheme.

Type

SAML 2.0 Configuration function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddSAMLScheme

(
   void*                                     pHandle,
   Sm_PolicyApi_Scheme_t*                    pstructScheme,
   Sm_PolicyApi_SAMLProviderProp_t*          pProps,
   const bool                                bUpdate,
   char**                                    pszErrMsg
);

Returns

• Sm_PolicyApi_Success. The SAML 2.0 authentication scheme operation was successful.
• Sm_PolicyApi_Failure. The SAML 2.0 authentication operation was not successful
• Sm_PolicyApi_InvalidProp. A specified property is invalid. The property name is returned in pszErrMsg.
• Sm_PolicyApi_MissingProperty. A required property was not specified. The property name is returned in pszErrMsg.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create a SAML 2.0 authentication scheme.
• Sm_PolicyApi_SAMLIDP_IncorrectParameters. The supplied SAML provider properties are incomplete or incorrect.
• Sm_PolicyApi_SAMLIDP_ProviderIdNotUnique. The supplied SAML provider ID is not unique.

Sm_PolicyApi_AddSAMLServiceProvider()

Adds a new SAML 2.0 Service Provider object or modifies an existing one.

If a Service Provider cannot be created, any associated objects created in the policy store during the attempt will be rolled back.

Type

SAML 2.0 Configuration function, domain scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddSAMLServiceProvider
(
   void*                          pSessionHandle,
   Sm_PolicyApi_SAMLSP_t*         pstructSAMLSP,
   const bool                     bUpdate,
   char**                         pszErrMsg
);

Returns

• Sm_PolicyApi_Success. The Service Provider operation was successful.
• Sm_PolicyApi_Failure. The Service Provider operation was not successful.
• Sm_PolicyApi_InvalidProp. A specified property is invalid. The property name is returned in pszErrMsg.
• Sm_PolicyApi_MissingProperty. A required property was not specified. The property name is returned in pszErrMsg.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create a Service Provider.
• Sm_PolicyApi_DomainNotFound. The affiliate domain OID was not found.
• Sm_PolicyApi_DomainNotAffiliate. The domain is not an affiliate domain.
• Sm_PolicyApi_InsufficientSPData. Required properties for configuring the Service Provider were missing.

Sm_PolicyApi_AddScheme()

Creates a new SiteMinder authentication scheme. Attributes of the scheme are contained in the pstructScheme structure.

If the scheme exists and the bUpdate flag is true, the item is updated.

Type

Authentication scheme function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddScheme (
   void*                    pSessionHandle,
   Sm_PolicyApi_Scheme_t*   pstructScheme,
   const bool               bUpdate
);

Returns

• Sm_PolicyApi_Success. The scheme was created successfully.
• Sm_PolicyApi_Failure. The scheme was not created successfully.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to create a scheme.
• Sm_PolicyApi_InvalidOid. The scheme object identifier was not found during an update.

Sm_PolicyAPI_AddTargetConfigToSAML1xScheme

Adds a default target configuration setting in a SAML 1.x authentication scheme.

Syntax

The Sm_PolicyApi_AddTargetConfigToSAML1xScheme function has the following syntax:

int SM_EXTERN Sm_PolicyApi_AddTargetConfigToSAML1xScheme(
        void*        pHandle,
        const char*  pszSchemeOid,
        const char*  pszURL,
        int         iQPOverridesTarget
);

Parameters

The Sm_PolicyApi_AddTargetConfigToSAML1xScheme function accepts the following parameters:

pHandle

[in] A pointer to an internal Policy Management API data structure. The structure holds information about the administrator session and the client session.

pszSchemeOid

[in] A null-terminated string containing the object identifier of the authentication scheme being updated.

pszURL

[in] A pointer to a valid default target configuration URL.

iQPOverrides Target

[in] An integer specifying the value specified in the 'Query parameter override Default Target' check box.

Valid values for iQPOverridesTarget are:

• 0 specifies that the query parameter does not override the target.
• 1 specifies that the query parameter overrides the target.

Return Values

The Sm_PolicyApi_AddTargetConfigToSAML1xScheme function returns one of the following values:

• Sm_PolicyApi_Success. The action was completed successfully.
• Sm_PolicyApi_Failure. The action was unsuccessful.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_SchemeNotFound. The authentication scheme corresponding to the OID was not found, or was not a SAML 1.x authentication scheme.
• Sm_PolicyApi_InvalidOid. The OID of the authentication scheme is NULL.

Sm_PolicyApi_AddToGroup()

Adds an item to the group identified by pszGroupOid.

The item (which may be a group) and the group must exist and must be of the same type.

The pszDomainOid parameter is required by a rule group or response group. An agent group does not require a domain OID because it is not a domain-based object.

Type

Group function, global scope (agents) or domain scope (responses, rules).

Syntax

int SM_EXTERN Sm_PolicyApi_AddToGroup (
   void*                   pSessionHandle,
   Sm_PolicyApi_Groups_t   dwGroup,
   const char*             pszItemOid,
   const char*             pszGroupOid,
   const char*             pszDomainOid
);

Returns

• Sm_PolicyApi_Success. The add was successful.
• Sm_PolicyApi_Failure. The add was not successful.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to add a rule, response, or agent OID to its respective group.
• Sm_PolicyApi_InvalidOid:
  • The domain OID was not found (for a domain-based group).
  • The group OID was not found.
  • The rule, response, or agent OID or group OID was not found.
• Sm_PolicyApi_BadGroup. Parameter dwGroup is not the rule, response, or agent type.

Sm_PolicyApi_AddTrustedHost()

Creates or modifies a trusted host object in the object store.

Use this function to register the trusted host "offline"-that is, without a connection between the agent and the Policy Server. When you use this function, you must run the SiteMinder smreghost tool to define the shared secret in the host configuration file (default name SmHost.conf). You define the shared secret with the -sh option of the smreghost tool.

Type

Agent configuration function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddTrustedHost (
     void*                            pSessionHandle,
     Sm_PolicyApi_TrustedHost_t*      pstructTrustedHost,
     bool                             bUpdate,
     bool                             bGenSharedSecret
);

Remarks

If bGenSharedSecret is true, the function generates a 128-byte value and updates the pszSecret field of pstructTrustedHost. If bGenSharedSecret is false, the value of the shared secret for a new or updated trusted host object is taken from the pszSecret field of the pstructTrustedHost structure.

If both bGenSharedSecret and bUpdate are true, the function ignores the value specified in the pszSecret field of pstructTrustedHost, generates a new value, and updates the object in the object store and in the pszSecret field of pstructTrustedHost.

If the function generates the shared secret, you must retrieve the generated shared secret in clear text so that you can define it in the -sh option of the smreghost tool. To retrieve the shared secret, call Sm_PolicyApi_GetTrustedHost().

In past releases, agent registration with the Policy Server always used 128-byte random ASCII shared secrets. The new model makes it possible to use a user-defined string value as a shared secret. This is a potential security weakness. The administrator who chooses offline agent host configuration must create a strong shared secret and store it safely. It is strongly recommended that you call the function Sm_PolicyApi_AddTrustedHost() with the bGenSharedSecret parameter set to true. This enforces automatic generation of a hard-to-guess shared secret.

Use of this function is not required to either create a trusted host or to define the host configuration. SiteMinder automatically creates and configures the trusted host during installation, and also when you run smreghost without using the -sh option.

Returns

• Sm_PolicyApi_Success. The trusted host object was created or modified.
• Sm_PolicyApi_Failure. Generalized failure.
• Sm_PolicyApi_InvalidOid. The unique ID does not correspond to a Trusted Host object.
• Sm_PolicyApi_NoPrivilege. The caller does not have the proper privileges to add or modify a trusted host object.
• Sm_PolicyApi_InvalidHandle. The session pointer is not valid.
• Sm_PolicyApi_NotUnique. The shared secret already exists.
• Sm_PolicyApi_NoSession. The API user is not properly logged in.
• Sm_PolicyApi_InvalidProp. Invalid shared secret value specified.
• Sm_PolicyApi_GenSharedSecretFailure. Failed to generate a 128‑byte shared secret value.

Sm_PolicyApi_AddUserDirToAffiliateDomain()

Adds a user directory to an existing affiliate domain.

Type

Federation function

Syntax

int SM_EXTERN Sm_PolicyApi_AddUserDirToAffiliateDomain (
   void*         pSessionHandle,
   const char*   pszUserDirOid,
   const char*   pszAffiliateDomainOid
);

Returns

• Sm_PolicyApi_Success. The user directory was added to the affiliate domain successfully.
• Sm_PolicyApi_Failure. The user directory was not added to the affiliate domain.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to add a user directory to an affiliate domain.
• Sm_PolicyApi_InvalidOid. The affiliate domain OID or user directory OID was not found during an update.
• Sm_PolicyApi_DuplicateEntry. The user directory exists in the user directory collection of the domain.

Sm_PolicyApi_AddUserDirToDomain()

Associates the directory object identified by pszUserDirOid with the domain identified by pszDomainOid. The directory object is appended to the end of the search order.

Type

User directory function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddUserDirToDomain (
   void*          pSessionHandle,
   const char*    pszUserDirOid,
   const char*    pszDomainOid
);

Returns

• Sm_PolicyApi_Success. The add operation was successful.
• Sm_PolicyApi_Failure. The add operation was not successful.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to add a user directory to a domain.
• Sm_PolicyApi_InvalidOid. A user directory or domain OID was not found.
• Sm_PolicyApi_DuplicateEntry. The user directory exists in the user directory collection of the domain.

Sm_PolicyApi_AddUseSecureAuthPropToAffiliate()

Adds or updates the UseSecureAuthURL property to a SAML 1.x affiliate.

Syntax

int SM_EXTERN Sm_PolicyApi_AddUseSecureAuthPropToAffiliate(
   void*    pHandle,
   char*    pszAffiliateOID,
   bool     bUseSecureAuthURL
                           
);

Parameters

pHandle

[in] A pointer to an internal Policy Management API data structure. The structure holds information about the administrator session and the client session.

pszAffiliateOid

[in] A pointer to the OID of an existing SMAL 1.x affiliate.

bUseSecureAuthURL

[in] A Boolean value that specifies whether to use a secure authentication URL for this affiliate.

Returns

• Sm_PolicyApi_Success. The action was completed successfully.
• Sm_PolicyApi_Failure. The action was unsuccessful.
• Sm_PolicyApi_NoSession. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoPrivilege. The administrator did not have sufficient access privileges.

Sm_PolicyApi_AddUsersToAffiliate()

Adds a user directory entry to an affiliate.

Type

Federation function

Syntax

int SM_EXTERN Sm_PolicyApi_AddUsersToAffiliate (
   void*               pSessionHandle,
   const char*         pszAffiliateOid,
   Sm_PolicyApi_User_t *pStructUsers,
   int                 iPolicyFlags
);

Returns

• Sm_PolicyApi_Success. The user was added was successful.
• Sm_PolicyApi_Failure. The user was not added successfully.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to add a user.
• Sm_PolicyApi_InvalidOid: The affiliate OID was not found.
• Sm_PolicyApi_DuplicateEntry. The user is already part of the affiliate.

Sm_PolicyApi_AddUsersToPolicy()

Adds a user directory entry to the policy identified by pszPolicyOid. Only one user specification (which may be an aggregate) can be added at a time.

Type

User and user state function.