# CA SOA Security Manager Authentication

## Contents
Overview Prerequisites Agent Configuration Message Details Configuration XmlToolkit.properties File

## Overview
CA SOA Security Manager can authenticate end-users and authorize them to access protected Web resources. When the Enterprise Gateway receives a message containing user credentials, it can forward the message to CA SOA Security Manager where the passed credentials is extracted from the message to authenticate the end-user. When the message has been passed to CA SOA Security Manager, it can authenticate the user by the following methods: XML Document Credential Collector: Gathers credentials from the message and maps them to fields within a user directory. XML Digital Signature: Validates the X.509 certificate contained within an XML-Signature on the message. WS-Security: Extracts user credentials from WS-Security tokens contained within the message. SAML Session Ticket: Consumes a SAML session ticket from an HTTP header, SOAP envelope, or session cookie to authenticate the end-user. By delegating the authentication decision to CA SOA Security Manager, the Enterprise Gateway acts as a Policy Enforcement Point (PEP). It enforces the decisions made by the CA SOA Security Manager, which acts a Policy Decision Point (PDP). Please refer to the Authentication Methods section of the CA SOA Security Manager Policy Configuration Guide for more information on these authentication methods. Enter a name for the filter in the Name: field before configuring the Agent and Message Details sections described below.
## Prerequisites
CA SOA Security Manager integration requires CA TransactionMinder SDK version 6.0 or later. Enterprise Gateway When adding third-party binaries to the Enterprise Gateway, you must perform the following steps: Add the binary files as follows: Add `.jar` files to the `InstallDir/ext/lib` directory. Add `.dll` files to the `InstallDir\win32\lib` directory. Add `.so` files to the `InstallDir/platform/lib` directory. Restart the Enterprise Gateway. Policy Studio When adding third-party binaries to the Policy Studio, you must perform the following steps: Add `.jar` files to the `InstallDir/plugins/thirdparty.runtime.dependencies_6.0.3` directory. Restart the Policy Studio.
## Agent Configuration
Name: Enter a name for this authentication filter in the field provided. Agent Name: In order to act as a PEP for the CA SOA Security Manager, the Enterprise Gateway must have been set up as a SOA Agent with the Policy Server. Please refer to the CA SOA Security Manager Agent Configuration Guide for more information on how to do this. Select a previously configured agent to connect to SOA Security Manager in the Agent Name field. This name must correspond with the name of an agent previously configured in the SOA Security Manager Policy Server. At runtime, the Enterprise Gateway connects as this agent to a running instance of SOA Security Manager. For details on how to configure SOA Security Manager connections, see the CA SOA Security Manager Connection Details.
## Message Details Configuration
While authenticating the user against CA SOA Security Manager, the user can also be authorized for a specified action on a particular resource. Configure the following fields in the Message Details section: Resource: Enter the name of the resource for which you want to ensure that the user has access to. By default, the `http.request.uri` message attribute is used, which contains the relative path on which the request was received by the Enterprise Gateway. Action: Specify the action that the user is attempting to perform on the specified resource. The Enterprise Gateway will check the user's entitlements in CA SOA Security Manager to ensure that the user is allowed to perform this action on the resource entered above. By default the `http.request.verb` message attribute is used, which stores the HTTP verb used by the client when sending up the message. Protocol: Select the protocol used by the client to access the requested resource. Users may have different access rights depending on their roles within the organization. For example, managers may be allowed to FTP to a given resource, but junior employees may only be allowed to GET a resource using HTTP. This field is pre-populated with the `http.request.protocol` message attribute, which contains the protocol used by the client to send the message to the Enterprise Gateway. Headers: In order to carry out further authorization checks on the message, it is possible to forward the HTTP headers associated with the client message to the CA SOA Security Manager. By default, the `http.headers` message attribute is used to ensure that the original client headers are send to the CA SOA Security Manager.
## XmlToolkit.properties File
The `XmlToolkit.properties` file contains default properties used by the SOA agent, such as the URL of the CA SOA Manager, an identifier for the SOA agent, and an indication to the SOA Manager if it should perform fine-grained resource identification or not. The `XmlToolkit.properties` file can be found in the `/lib/modules/soasm` directory of your Enterprise Gateway installation.
    #Wed Jul 18 15:02:16 BST 2007
    WSDMResourceIdentification=yes
    WS_UT_CREATION_EXPIRATION_MINUTES=60
The following properties are available: WSDMResourceIdentification: This value cannot be configured from the Policy Studio GUI and so can only be set directly in the properties file. If this property is set to "no" (or if the properties file cannot be found) only a "coarse-grained" resource identification will be performed on the requested URL. If this value is set to "yes", a "fine-grained" resource identification including the requested URL, Web Service name, and SOAP operation, i.e. [url]/[web service name]/[soap operation]. WS_UT_CREATION_EXPIRATION_MINUTES: Specifies the WS-Username Token age limit restriction in minutes. This setting helps prevent against replay attacks. The default token age limit is 60 minutes. See the section below for more information on modifying this setting. Configuring the Username and Password Digest Token Age Restriction: By default, the WS-Security authentication scheme imposes a 60 minute restriction on the age of Username and Password Digest Tokens to protect against replay attacks. You can configure a different value for the token age restriction for the Enterprise Gateway by setting the `WS_UT_CREATION_EXPIRATION_MINUTES` parameter in the `XmlToolkit.properties` file for that Enterprise Gateway. To configure the Enterprise Gateway to use a non-default age restriction for Username and Password Token authentication, complete the following steps: Navigate to the `INSTALL_DIR/system/lib/modules/soasm` directory, where `INSTALL_DIR` points to the root of your Enterprise Gateway installation. Open the `XmlToolkit.properties` file in a text editor. Add the following line, where `token_age_limit` specifies the token age limit in minutes: `WS_UT_CREATION_EXPIRATION_MINUTES=token_age_limit` Save and close the `XmlToolkit.properties` file. Restart the Enterprise Gateway. Important Points: The properties file is written to the `/lib/modules/soasm` directory when a SOA Security Manager Authentication or Authorization filter is loaded at startup, or on server refresh (for example, when a configuration update is deployed), but only if the file does not already exist in this location. If the properties file already exists in the `/lib/modules/soasm` directory, the WSDMResourceIdentification property is not overwritten. In other words, the user is allowed to manually set this property independently of the Policy Studio. If the WSDMResourceIdentification property does not exist, it is given a default value of "yes" and written to the file.