Web Services Security Guides › CA SiteMinder® Web Services Security Policy Configuration Guide › Variables › Create a Variable

Create a Variable

You create a variable to make it available for use in policies or responses. Variables are domain objects. You create them within a specific policy domain, or import them into a domain using the smobjimport tool.

More information about importing objects into policy domains exists in the Policy Server Administration guide.

More information:

Domains

Create a SAML Assertion Variable

SAML Assertion variables let you obtain information from any SAML assertion and use this information in policy expressions to authorize a client. The assertion may be included in a SOAP envelope or HTTP header of an incoming XML message. For example, you can create a variable that enables the Policy Server to check who issued the assertion before permitting access to a web service.

SAML assertion variables are resolved to the value of an XPath string. The string identifies an element (and optionally, an operation to perform on that element) of a SAML assertion.

Note: For more information about XPATH, see the XPATH specification available at http://www.w3.org/TR/xpath.

To create a variable

1. Open the domain to which to you want to add a variable.
2. Click the Variables tab.

   A table lists the variables associated with the domain.

3. Click Create Variable.

   The Create Variable screen appears.

4. Verify that Create a new object is selected, and click OK.

   Variable settings open.

5. Type the variable name in the Name field.
6. Select SAML Assertion from the Variable Type list.

   SAML Assertion variable settings open.

   Note: Click Help for descriptions of settings and controls, including their respective requirements and limits.

7. Specify the data type in which the value of the specified XPATH query should be returned by choosing one of the following options from the Return Type list:
   • Boolean
   • Number
   • String (the default)
8. Type in an XPath query that you want to resolve to the variable value in the Query box.
9. Optionally, set the SAML Authentication Scheme Required box if the web service is protected by the SAML Session Ticket authentication scheme.
10. If the web service is not protected by the SAML Session Ticket authentication scheme, specify whether the SiteMinder WSS Agent should look for the SAML assertion in the Envelope Header or HTTP Header by selecting the appropriate SAML Assertion Location option.
11. Click Finish.

    The variable appears in the Variables tab of the domain. The variable can now be used in policy expressions or responses.

Create a Transport Variable

Transport variables let you obtain HTTP header values from the web service request.

To create a variable

1. Open the domain to which to you want to add a variable.
2. Click the Variables tab.

   A table lists the variables associated with the domain.

3. Click Create Variable.

   The Create Variable screen appears.

4. Verify that Create a new object is selected, and click OK.

   Variable settings open.

5. Type the variable name in the Name field.
6. Select Transport from the Variable Type list.

   Transport variable settings open.

   Note: Click Help for descriptions of settings and controls, including their respective requirements and limits.

7. Enter information in the following fields:

   Description

   (Optional) Specifies a brief description of the variable.

   Limits: No more than 1KB.

   Return Type

   Specifies the data type in which the value of the transport header data should be returned:

   • Boolean
   • Date
   • Number
   • String (the default)

   Transport Data Name

   Specifes the name of the HTTP header (for example, SOAPAction) that will provide the value of the variable.

8. Click Finish.

   The variable appears in the Variables tab of the domain. The variable can now be used in policy expressions or responses.

Create an XML Agent Variable

XML Agent variables let you obtain information about the web server whose resources the WSS Agent is protecting for use in policy expressions or responses.

To create a variable

1. Open the domain to which to you want to add a variable.
2. Click the Variables tab.

   A table lists the variables associated with the domain.

3. Click Create Variable.

   The Create Variable screen appears.

4. Verify that Create a new object is selected, and click OK.

   Variable settings open.

5. Type the variable name in the Name field.
6. Select XML Agent from the Variable Type list

   XML Agent variable settings open.

   Note: Click Help for descriptions of settings and controls, including their respective requirements and limits.

7. Enter information in the following fields:

   Description

   (Optional) Specifies a brief description of the variable.

   Limits: No more than 1KB.

   Property

   Specifies the XML Agent property that will provide the value of the variable:

   • Server Product Name—String representation of the web server product name—for example, iPlanet Web Server. Value is obtained from the ServerProductName Agent Configuration parameter.
   • Server Vendor—String representation of the web server vendor—for example, Sun. Value is obtained from the ServerVendor Agent Configuration parameter.
   • Server Version—String representation of the web server product version—for example, 6.0 SP2.

8. Click Finish.

   The variable appears in the Variables tab of the domain. The variable can now be used in policy expressions or responses.

Create an XML Body Variable

XML Body variables let you obtain information from any element in the body (or payload) of an incoming XML message for use in policy expressions and responses.

Specifically, XML Body variables are resolved to the value of an XPath string that identifies an element (and optionally, an operation to perform on that element) of an XML document.

Note: For more information about XPATH, see the XPATH specification available at http://www.w3.org/TR/xpath.

To create a variable

1. Open the domain to which to you want to add a variable.
2. Click the Variables tab.

   A table lists the variables associated with the domain.

3. Click Create Variable.

   The Create Variable screen appears.

4. Verify that Create a new object is selected, and click OK.

   Variable settings open.

5. Type the variable name in the Name field.
6. Select XML Body from the Variable Type list.
7. XML Body variable settings open.

   Note: Click Help for descriptions of settings and controls, including their respective requirements and limits.

8. Enter information in the following fields:

   Description

   (Optional) Specifies a brief description of the variable.

   Limits: No more than 1KB.

   Return Type

   Specifies the data type in which the value of the specified XPATH query should be returned:

   • Boolean
   • Date
   • Number
   • String (the default)

9. Do one of the following:
   • Load a schema (.xsd) file and select the element to map to the specified field name by browsing using the following procedure:
     1. Click Browse and navigate to the schema file.
     2. Click Upload XSD File.

        The schema is uploaded.

     3. Select the schema element that you want to map to the specified field name in the Select a node group box.

        The Select a node group box displays the selected schema using a standard tree-style hierarchical view. Click the plus sign (+) next to an element to expand it. Click the minus sign (-) beside an expanded element to contract it. Elements marked with an asterisk (*) are repeatable within the XML document (that is, incoming XML documents may contain multiple instances of that element).

   • Unset the Advance XPath query option and type an XPATH query defining the mapping in the XPath field.
10. Optionally, if you are working from a loaded schema in the Select a node group box, specify an XPath function (count, div, index, mod, sum) that you want to apply to a repeatable schema element, by choosing it from the Function drop-down list.

    The Function option lets you create more complex mappings by processing functions that further evaluate the XML document.

    Note: For more information about these functions, go to the XPATH specification at http://www.w3.org/TR/xpath.

11. Click Finish.

    The variable appears in the Variables tab of the domain. The variable can now be used in policy expressions or responses.

Create an XML Envelope Header Variable

XML Envelope Header Variables let you obtain information from any element in the SOAP envelope header (including WS‑Security headers) of an incoming XML message, for use in policy expressions or responses.

Specifically, XML Envelope Header variables are resolved to the value of an XPath string that identifies a SOAP envelope header element (and optionally, an operation to perform on that element) of an XML document.

Note: For more information about XPATH, see the XPATH specification available at http://www.w3.org/TR/xpath.

To create a variable

1. Open the domain to which to you want to add a variable.
2. Click the Variables tab.

   A table lists the variables associated with the domain.

3. Click Create Variable.

   The Create Variable screen appears.

4. Verify that Create a new object is selected, and click OK.

   Variable settings open.

5. Type the variable name in the Name field.
6. Select XML Header from the Variable Type list.

   XML Header variable settings open.

   Note: Click Help for descriptions of settings and controls, including their respective requirements and limits.

7. Specify the data type in which the value of the specified XPATH query should be returned by choosing one of the following options from the Return Type list:
   • Boolean
   • Number
   • String (the default)
8. Type in an XPath query that you want to resolve to the variable value in the Query box.
9. Click Finish.

   The variable appears in the Variables tab of the domain. The variable can now be used in policy expressions or responses.

Create a Static Variable

You create a static variable to make it available for use in policies or responses.

Note: The value of the resolved variable must not be greater than 1K.

To create a variable

1. Open the domain to which to you want to add a variable.
2. Click the Variables tab.

   A table lists the variables associated with the domain.

3. Click Create Variable.

   The Create Variable screen appears.

4. Verify that Create a new object is selected, and click OK.

   Variable settings open.

5. Type the variable name in the Name field.
6. Select Static from the Variable Type list.

   Static variable settings open.

   Note: Click Help for descriptions of settings and controls, including their respective requirements and limits.

7. Specify the data type and value of the variable in the Variable Information group box.
8. Click Submit.

   The variable appears in the Variables tab of the domain. The variable can now be used in policy expressions or responses.

Create a Request Context Variable

You create a request context variable to make it available for use in policies or responses.

Note: The value of the resolved variable must not be greater than 1K.

To create a variable

1. Open the domain to which to you want to add a variable.
2. Click the Variables tab.

   A table lists the variables associated with the domain.

3. Click Create Variable.

   The Create Variable screen appears.

4. Verify that Create a new object is selected, and click OK.

   Variable settings open.

5. Type the variable name in the Name field.

   Note: Request Context variable names must begin with the percent character (%).

   Example: %REQUEST_ACTION

6. Select Request Context from the Variable Type list.

   Request context settings open.

7. Select the variable value from the Property list.
8. Click OK.

   The variable appears in the Variables tab of the domain. The variable can now be used in policy expressions or responses.

Create a User Context Variable

You create a user context variable to make it available for use in policies or responses.

Note: The value of the resolved variable must not be greater than 1K.

To create a variable

1. Open the domain to which to you want to add a variable.
2. Click the Variables tab.

   A table lists the variables associated with the domain.

3. Click Create Variable.

   The Create Variable screen appears.

4. Verify that Create a new object is selected, and click OK.

   Variable settings open.

5. Type the variable name in the Name field.

   Note: User Context variable names must begin with the percent character (%).

   Example: %SM_USERPATH

6. Select User Context from the Variable Type list.

   User context settings open.

7. Select the portion of the user context that provides the value of the variable from the Property list.

   The return type value appears as either string or boolean depending on the value you selected from the Property list.

8. (Required for User Property and Directory Entry) Enter the name of the directory or user attribute that provides the variable value in the Property field.
9. (Required for User Property and Directory Entry) Enter the size of the buffer (in bytes) that is to store the variable in the Buffer field.
10. (Required for Directory Entry) Enter the distinguished name of the directory entry in the DN field.
11. Click Submit.
12. The variable appears in the Variables tab of the domain. The variable can now be used in policy expressions or responses.

Create a Form Post Variable

You create a Form Post variable to make it available for use in policies.

Note: The value of the resolved variable must not be greater than 1K.

To create a variable

1. Open the domain to which to you want to add a variable.
2. Click the Variables tab.

   A table lists the variables associated with the domain.

3. Click Create Variable.

   The Create Variable screen appears.

4. Verify that Create a new object is selected, and click OK.

   Variable settings open.

5. Type the variable name in the Name field.
6. Select Post from the Variable Type list.

   Form post settings open.

7. Enter the name of the POST variable contained in the form in the Form Field Name field.
8. Click OK.

   The variable appears in the Variables tab of the domain. The variable can now be used in policy expressions.