Policy Server Guides › Policy Server Configuration Guide › Variables › Web Service Variables

Web Service Variables

Web service variables provide a method for including dynamic data from a web service in a CA SiteMinder® policy. Web service variables are resolved by calling a web service. The Policy Server sends a SOAP request document, as specified in the web service variable definition, and receives a SOAP response document as a reply. The Policy Server extracts the value of the web services variable from the SOAP response document.

The Simple Object Access Protocol (SOAP) is a lightweight, XML-based protocol that consists of three parts:

• An envelope that defines a framework for describing message contents and how to process it.
• A set of encoding rules for expressing instances of application-defined data types.
• A convention for representing remote procedure calls and responses.

The following figure shows how a CA SiteMinder® deployment resolves a web services variable for a web service inside an Intranet. The web service is on the same side of the firewall as the Policy Server.

In this scenario, if a Web Service variable is associated with an authorization request, it is resolved on the Policy Server side by calling the Web Service Variables Resolver. The Web Service Variables Resolver runs in the same process space.

When defining the Web Service variable, the user specifies the SOAP document to send to the Web Service, the authentication credentials, and other parameters.

The resolver sends the specified SOAP document to the web service, extracts the value of the variable from the response and forwards it to the Policy Server to complete the authorization request.

Even if there is a firewall between the Policy Server and the web service, it can be configured to allow communication between the two. The Policy Server issues the request and reads the response, so the firewall is only required to allow outbound requests from the Policy Server to the web service.

A secure SSL connection can be configured between the Policy Server and the web service to allow for the inbound responses to come from the Web Service to the Policy Server. The SSL connection uses the server-side certificates on the web service and a list of trusted certificate authorities that are configured on the Policy Server side.

Component Requirements for Web Service Variables

Web service variables require a session store.

Note: More information about configuring a session store, see the Policy Server Installation Guide. For more information about upgrading a session store, see the CA SiteMinder® Upgrade Guide.

Security Requirements When Resolving Web Services Variables

Security for Web Services Variables requires an SSL connection between the Policy Server and the Web Service. You can also include a WS-Security header with a username token that the Web Service has been configured to recognize. WS-Security is a standard set of SOAP extensions that provides security token propagation, message integrity, and confidentiality through signing and encryption.

For a secure resolution of a Web Services Variable:

• The Policy Server must make a SOAP request to a Web Service on behalf of a known identity (a Web Service account). The model is similar to the model that CA SiteMinder® uses to access attributes in a user directory.
• The WS-Security header containing the Web Services credentials can be configured to include a base-64-encoded SHA-1 digest of the password.
• A Web Service variable can be configured to use an SSL connection with a server-side certificate, which means that the Policy Server must be configured with the list of trusted CAs.

Note: For SSL connections, configure server–side certificates for the Web Service. Configure a list of trusted CAs on the Policy Server. To configure trusted CAs, use the certificate data store described in Certificate Authorities and Web Services Variables.

Configure the Web Service Variable Resolver

For the Policy Server to resolve a Web Service variable, configure the Web Service Variable Resolver to connect to the web service. There are two categories of web service connections:

• Both the Policy Server and the web service are on the same side of a firewall.
• A firewall exists between the Policy Server and the web service, but it is configured to allow one-way communication between the two (outbound requests from the Policy Server to the web service).

Before being able to use the Web Service Variables functionality, the Policy Server must be configured with a list of trusted CAs, using the SmKeyTool command-line utility. If several Policy Servers are used in a load balancing or failover configuration, each of them must be configured with the same list of trusted CAs.

Default configuration settings are provided in the WebServiceConfig.properties file in the SiteMinder/Config/properties directory. You can modify these properties.

Sample WebServiceConfig.properties Configuration File

# Netegrity Web Service Variable Resolver properties configuration file:
# This file must be in the classpath that is used when the policy server runs.
# ResolutionTimeout is the amount of time the resolver will at most wait to resolve all Web Service variables related to a given request.
#
# This setting is intended to end sessions that are waiting on a web service that is not responding. The time that the Web Agent will typically wait before responding is typically 60 sec (but may be changed # in the future), which means this setting should be 60000 or greater to cancel transactions that cannot be returned.
ResolutionTimeout=75000
# MaxThreadCount is the maximal number of active threads running within the Web Service variables resolver.
MaxThreadCount=10

Certificate Authorities and Web Services Variables

To use SSL connections when resolving web services variables, configure a list of trusted Certificate Authorities (CAs). The Policy Server uses the CAs when it establishes a connection to a Web Service.

To configure the list in the certificate data store, use the Administrative UI.

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 Static Variable

You can 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 1 K.

Follow these steps:

1. Click Policies, Domain.
2. Click Variables.
3. Click Create Variable.

   Verify that the Create a new object of type Variable option is selected.

4. Click OK.
5. Select a domain from the list and click Next.
6. Type the variable name in the Name field.
7. 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.

8. Specify the data type and value of the variable in Variable Information.
9. 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 can 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 1 K.

Follow these steps:

1. Click Policies, Domain.
2. Click Variables.
3. Click Create Variable.

   Verify that the Create a new object of type Variable option is selected.

4. Click OK.
5. Select a domain from the list and click Next.
6. Type the variable name in the Name field.

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

   Example: %REQUEST_ACTION

7. Select Request Context from the Variable Type list.

   Request context settings open.

8. Select the variable value from the Property list.
9. 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 1 K.

Follow these steps:

1. Click Policies, Domain.
2. Click Variables.
3. Click Create Variable.

   Verify that the Create a new object of type Variable option is selected.

4. Click OK.
5. Select a domain from the list and click Next.
6. Type the variable name in the Name field.

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

   Example: %SM_USERPATH

7. Select User Context from the Variable Type list.

   User context settings open.

8. Select the portion of the user context that provides the value of the variable from the Item list.
9. (Required for Session Variable) Specify the type of data that is represented by the variable (Boolean, Number, String, or Date) in the Return Type field.

   For other Item list selections, the Return Type value is preset as String or Boolean as appropriate and not user-configurable.

10. (Required for User Property, Directory Entry, and Session Variable) Enter the name of the directory or user attribute that provides the variable value in the Property field.
11. (Required for User Property, Directory Entry, and Session Variable) Enter the size of the buffer (in bytes) that is to store the variable in the Buffer field.
12. (Required for Directory Entry) Enter the distinguished name of the directory entry in the DN field.
13. Click Submit.

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

Configure Support for Multiple Value User Attribute Results When Processing User Context Variables

By default, user context variables that are configured to obtain the value of a specified user property in the directory only support single value user attributes.

You can configure the Policy Server to support multiple value user attribute results when processing user context variables.

Follow these steps:

1. Stop the Policy Server.
2. Open the following file in a text editor:

   ps_install_dir\config\properties\scriptActiveExpConfig.properties

3. Add a line containing the following entry anywhere in the file:

   ALLOW_MULTIVALUSERATTR=1
   

4. Save the file and exit the text editor.
5. Start the Policy Server

Create a Form Post Variable

You can 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 1 K.

Follow these steps:

1. Click Policies, Domain.
2. Click Variables.
3. Click Create Variable.

   Verify that the Create a new object of type Variable option is selected.

4. Click OK.
5. Select a domain from the list and click Next.
6. Type the variable name in the Name field.
7. Select Post from the Variable Type list.

   Form post settings open.

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

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

Create a Web Services Variable

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

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

Follow these steps:

1. Click Policies, Domain.
2. Click Variables.
3. Click Create Variable.

   Verify that the Create a new object of type Variable option is selected.

4. Click OK.
5. Select a domain from the list and click Next.
6. Type the variable name in the Name field.
7. Select Web Service from the Variable Type list.

   Web Service settings appear.

8. Select the data type from the Return Type list.
9. Type the web service URL in the URL field.
10. Type the XPath query in the XPath field.

    Note: The Policy Server uses this query to extract the value of the Web Service variable from the SOAP document that is returned by the Web Service.

11. (Optional) Select the Require Credentials option in Web Service Credentials and specify the user name and password that the Policy Server is to use when connecting to the web service.
12. (Optional) Click the following button in the SOAP Document section to add existing variables to the SOAP message:

    Variable

13. (Optional) Click Add in HTTP Headers to associate an HTTP header with the Web Service variable.
14. Click Finish.

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