Programming Guides › Programming Guide for C › Policy Management API Guidance › Policy Management API Data Structures › Sm_PolicyApi_Variable_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>