Sm_PolicyApi_Variable_t

Contents
casso10
Contents
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;
Field
Description
iStructId
Data structure ID, defined in Sm_PolicyApi_Structs_t.
pszOid
The unique object ID of the variable object.
pszName
The user-defined name of the variable object.
pszDesc
Optional text describing the variable object.
pszVariableTypeOid
The unique object ID of the variable type.
pszDefinition
Information needed to obtain the value of the variable at runtime.
pszMetaData
Reserved for use by the optional CA TransactionMinder product.
nReturnType
The data type of the variable value:
Sm_PolicyApi_VarReturnTypes_Boolean
Sm_PolicyApi_VarReturnTypes_Number
Sm_PolicyApi_VarReturnTypes_String
Sm_PolicyApi_VarReturnTypes_Date
bPreFetchFlag
Not currently used.
pszDomainOid
The unique object ID of the associated domain.
pNestedVariableList
A linked list of nested variable OIDs that are part of the definition of this variable.
next
Pointer to the next variable object structure.
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
CA Single Sign-On
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 sendsthe Web Service a SOAP request document as specified in
    pszDefinition
    , and then extracts the variable value from the SOAPresponse.
    The following table describes the XML elements used to configure a WebService variable:
Element
Description
RemoteURL
The URL to the Web Service that will resolve the WebService variable.
SSL
Specifies that the connection between the Policy Server and the Web Service should use SSL.
RemoteMethod
Set this element to POST.
ResultQuery
The return query, in XPath format. The Policy Server uses this information to search for the variable's value in the SOAP response document.
AuthCredentials
Optionally, specify the user's Web Service credentials through the following elements:
Username
Password (use either a SHA-1 password digest or a clear-text password)
Optionally, use the Hash element to specify that a hash of the password is to be included in the WS-Security password.
Document
Optionally, use this element to define a SOAP header and/or SOAP body through the following elements:
Envelope. The SOAP namespace is:http://schemas.xmlsoap.org/soap/envelope
Header. A user-defined SOAP header. A WS-Security header is automatically added to it if the user's Web Service credentials are specified.
Body. A user-defined SOAP body.
Nested variables of type RequestContext, UserContext, Post, and Static can be used inside the header and body. Their values are resolved and substituted before the request document is sent to the remote Web Service.
Specify a nested variable as follows:
$variable-name$
The XML element structures shown above are formatted for legibility. The XML stringsupplied 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>