Cisco ACE XML Gateway User Guide (Software Version 6.1) - Controlling Access to Services [Cisco ACE XML Gateways]

Table Of Contents

Controlling Access to Services

Overview of Access Control

About Multiple Credentials and Credential Mediation

Authentication in .NET

Working with Authenticators and Authorization Groups

Creating an Authenticator and Authorization Group

Deleting Authenticators and Authorization Groups

Changing an Authenticator's Authorization Group

Provisioning Services

Specifying Credential Requirements

IP Address Conditions

SSL/TLS Certificate Conditions

Verifying by SSL Certificate Fingerprint

Verifying by SSL Certificate Authority

Verifying by LDAP Query

HTTP(S) Basic Authentication Conditions

WSS Username/Password Token Conditions

WSS Password Digest Conditions

SAML Token Conditions

XPath Password Conditions

Security Token Conditions

Time-of-Day Conditions

Verifying Password-Based Credentials

Verifying Credentials with Active Directory LDAP Query

Configuring Active Directory LDAP Query Verification

Verifying Credentials with LDAP

Using LDAP Bind Password Verification

Using LDAP Query Password Verification

Using Per-Authenticator XML Security Public Keys

Identity Reports

Enabling Identity Reporting Features

Viewing User Activity Information

Controlling Access to Services

This chapter describes how to control access to services exposed by the ACE XML Gateway. It covers these topics:

•Overview of Access Control

•Working with Authenticators and Authorization Groups

•Provisioning Services

•Specifying Credential Requirements

•Verifying Password-Based Credentials

•Using Per-Authenticator XML Security Public Keys

•Identity Reports

Overview of Access Control

The ACE XML Gateway and Manager provide a rich set of capabilities for composing and enforcing access control requirements in an application network. The ACE XML Gateway is capable of checking a wide range of credential types, including SSL certificate, SAML, WSS UsernameToken, and username/passwords in a variety of formats. The ACE XML Gateway can verify credential data itself or using an external resource, such as an LDAP directory or SOAP service.

You can supplement the out-of-box capabilities of the ACE XML Gateway with the ACE XML Gateway SDK. The SDK lets you define new credential types and verification mechanisms for the policy. For more information on the SDK, see the Cisco ACE XML Gateway Developer Guide.

About Multiple Credentials and Credential Mediation

In credential mediation, an incoming credential is modified from one format to another for outgoing delivery. The ACE XML Gateway can mediate credentials to several formats, including HTTP Basic Authentication, NTLM header, WSS UsernameToken, and SAML token. The source credential can be any type of username/password type credential, a SAML Token Subject NameIdentifier, the DN of an SSL certificate, and more.

You can set up credential mediation by configuring backend service authentication with an incoming credential as the source of the outgoing credential.

For certain types of credentials, it may make sense for a given message to contain more than one instance of that type of credential. For example, a request may use multiple credentials to identify each of several participants who have contributed to the composition of the request. (In contrast, other types of credentials, such as IP address, can meaningfully occur only once in a request.) The ACE XML Gateway can evaluate and mediate multiple credentials in a request. Multiple credential mode is available for WSS UsernameToken and SAML credentials.

It is important to note that multiple credential mode does not stipulate a minimum credential requirement. In other words, a request without credentials may be accepted by an authenticator in multiple credential mode. It should only be used if the intention is to evaluate multiple credentials, if present, but not require their presence. For this reason, the ACE XML Manager prevents you from provisioning a handler that has already been provisioned to an authenticator in multiple credential mode to any other authenticator. Attempting to do so raises this policy compilation warning: "A handler that is provisioned to an authenticator that uses optional credentials cannot be provisioned to any additional authenticators."

Credential mediation is available for messages with multiple credentials. In general, the multiple credential handling scenarios supported by the ACE XML Gateway include:

•Mapping username/password credentials from an incoming request to credentials of type WSS UsernameToken, HTTP Basic Authentication, or SAML token in the outgoing request.

•Mapping multiple WSS UsernameToken credential values to SAML assertions. Custom attributes of the UsernameToken element (that is, attributes not in the WSS namespace) can be mapped to attributes in generated SAML attribute statements as well.

•Checking multiple SAML assertions, and either passing through or stripping out the assertions.

•Mapping user attributes acquired from an LDAP lookup to multiple SAML assertions.

For more information on credential mediation and setting up backend authentication, see Chapter 7, "Authenticating Requests to Backend Systems."

Authentication in .NET

In .NET, clients typically send their initial requests without authentication credentials. The client is expected to provide credentials if it receives back an HTTP 401 response with a WWW-Authenticate: Basic header. By default, the ACE XML Gateway includes this header in authorization error responses, so that .NET clients are prompted to supply credentials in a subsequent request.

When configuring settings for .NET infrastructure in which HTTP Basic Authentication is required by the backend, be sure to configure credential passthrough on the service descriptor. To do so, in the Service Authentication configuration, choose the option Send Basic Auth header with username and password from consumer credential.

For more information, see Chapter 7, "Authenticating Requests to Backend Systems."

Working with Authenticators and Authorization Groups

To define access conditions for services, you use a policy object called an authenticator. An authenticator contains access conditions based on one or more credential type. The conditions defined in an authenticator are applied to service access through another policy object called an authorization group. After creating the authenticator in an authorization group, you apply its requirements to a service by associating the authorization group with a virtual service.

Figure 6-1 shows authenticators, authorization groups, and handlers as portrayed in the Access Control page.

Figure 6-1 Authenticators, Authorization Group, and Handler

Creating an Authenticator and Authorization Group

The first step in setting up access control rules is creating the authenticator. To create an authenticator:

Step 1 While logged in to the web console as an Administrator or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu.

If there are any handlers or basic virtual services in the policy, they appear in the Access Control Browser (Figure 6-2). They are displayed by access status—either unprovisioned (which are inaccessible), publicly available, or assigned to an authorization group.

Figure 6-2 Access Control Browser

Step 2 Click the Add an Authenticator button.

Step 3 In the Edit General Information page, type a name for the authenticator in the Authenticator Name field. It is important for the name to be distinctive, since this name is used in descriptions in the event and message traffic logs for successful access attempts.

If associating an XML Security Public Key with the authenticator, you do not need to specify a name for the authenticator. Instead, log events and other activities associated with this authenticator can be identified by the Common Name (CN) in the client certificate validated for a given request. To associate an XML Security Public Key with the authenticator:

a. Expand the Advanced Options control.

b. Click the checkbox labeled Set the name of this authenticator to the CN from this Consumer Certificate.

Note For more information, see "Using Per-Authenticator XML Security Public Keys" section.

Step 4 Specify the authorization group in which the authenticator should be added.

•To add the authenticator to an existing authorization group, choose the group from the Authorization Group menu. Keep in mind that requests that meet the conditions of this authenticator will be able to access the services to which the existing authorization group is associated.

•To create a new authorization group to contain the authenticator, with Create in new authorization group named selected in the Authorization Group menu type the name of the new authorization group in the field next to the Authorization Group menu.

Step 5 Click Create to add the authenticator to the working policy.

By default, an authenticator with no access conditions blocks all requests. For information on adding access conditions, see "Specifying Credential Requirements" section. After adding access conditions, you can configure identity reporting features, as described in "Identity Reports" section.

Deleting Authenticators and Authorization Groups

An authorization group can only be deleted if it does not contain authenticators or references to virtual services. If it does, you need to remove these dependencies before attempting to delete the authorization group.

In general, you can remove dependencies as follows:

•To remove a relationship between an authorization group and a handler, click on the authorization group name, and in the table on the resulting page uncheck all the handlers that are provisioned to it.

•To delete an authenticator, click on its name in the Access Control Browser and click the Delete This Authenticator button at the bottom of the page.

•To delete an authorization group, click on the name of the authorization group in the Access Control Browser and click the Delete Authorization Group button at the bottom of the page.

Changing an Authenticator's Authorization Group

As described in "Creating an Authenticator and Authorization Group" section, when creating an authenticator you must specify the authorization group to which it belongs. The authorization group for an existing authenticator can be changed later as follows:

Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu.

Step 2 In the Access Control Browser, click the name of the authenticator to be configured.

Step 3 In the Authenticator information page, click the Edit link in the General section of the page.

Step 4 In the Authorization Group menu, choose a new authorization group for the authenticator.

An authenticator can only be in one authorization group at a time, so adding it to a new group removes it from the previous one.

Step 5 Click Save Changes to commit your changes to the working policy.

Provisioning Services

After creating an authenticator, you can enforce its conditions by associating it to virtual services (via an authorization group). There are several requirements for associating authenticators with virtual services:

•The authenticator must only contain conditions for credential types that are supported by the protocol of the virtual service. For example, authenticators that require XML-based credentials, such as SAML, can only be assigned to services based on XML protocols, such as SOAP or HTTP Post Body.

•If the credential is passed as a SOAP header (such as WSS UsernameToken or SAML token), SOAP header processing must be enabled in the virtual service. If not, a policy compilation error will prevent you from deploying the policy.

To apply an authenticator to virtual services through an authorization group:

Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu.

Step 2 In the Access Control Browser, click the name of the handler or virtual service to provision.

Step 3 Click the Access is restricted to the following authorization groups button. The checkboxes in the Allow Access column are enabled.

Alternatively, you can specify unrestricted public access by clicking the Public button. To make the service inaccessible to consumers, click the No access button.

Step 4 To impose the access conditions within an authorization group to a virtual service, click the checkbox for the authorization group. You can select as many authorization groups as desired.

Step 5 Click Save Changes to commit the changes to the working policy.

After you deploy the policy, only requests that meet the requirements of the authenticator can access the service.

Specifying Credential Requirements

An authenticator defines conditions for accessing a service. The ACE XML Gateway supports these types of access conditions:

•IP Address Conditions

•SSL/TLS Certificate Conditions

•HTTP(S) Basic Authentication Conditions

•WSS Username/Password Token Conditions

•WSS Password Digest Conditions

•SAML Token Conditions

•XPath Password Conditions

•Security Token Conditions

•Time-of-Day Conditions

A single authenticator can contain multiple conditions based upon different credential types. A request must meet all conditions in an authenticator to be accepted by the authenticator. In other words, the conditions in the authenticator are and'd. You can effect or'd conditions by using more than one authenticator with a service. In this case, a request needs to satisfy all conditions in only one of the authenticators to be accepted.

You can supplement the built-in credential types in two ways: with pre-built extensions provided by Cisco and with extensions you create with the ACE XML Gateway SDK.

Cisco extensions are separately distributed modules that extend the ACE XML Gateway to support additional types of credentials. Extensions exist for the following types:

•Netegrity tokens (Netegrity SiteMinder and TransactionMinder)

•Integrated Windows Authentication (Kerberos)

Note For more information on the extensions published by Cisco, contact your Cisco support representative. For more information on creating extensions, see the Cisco ACE XML Gateway Developer Guide.

An authenticator can have only one condition based upon IP address, time-of-day, or WSS Password Digest credentials. For other credential types, it can have multiple conditions for the same type. In effect, this allows you to test a single credential instance, such as a username/password combination, in multiple ways. (It is not intended to support checking multiple username/password combinations in a single request.) For example, you can have an authenticator test a password credential with LDAP bind in one condition and have it checked against an access control verifier extension in another.

IP Address Conditions

The IP address credential enables you to control access based on the IP address of the requester. You can specify that the requester must have a specific IP address or an address that falls within a range of acceptable addresses. To set up an IP address requirement:

Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu.

Step 2 Click on the authenticator in which you want to add the credential requirement, or create a new one as described in "Working with Authenticators and Authorization Groups" section.

Step 3 Choose IP Address from the Add Credential menu and click Add.

Step 4 Type the range of addresses that are to be accepted by the credential requirement in the text fields in dotted-decimal format. For example:

10.1.0.101 - 10.1.0.201

For a single address, type the same IP address in both fields.

Step 5 Click the Add a New IP Address Row button to include additional, non-contiguous ranges.

Step 6 Click Save Changes to commit the changes to the working policy.

The new credential requirement appears in the Required Credentials area of the authenticator page.

SSL/TLS Certificate Conditions

With an SSL/TLS credential requirement, the ACE XML Gateway authenticates consumers based on X.509 client certificates submitted in requests.

A client certificate can be validated in several ways. You can have the client certificate fingerprint compared to the fingerprint of a certificate stored in the policy, accepting the credential if the certificates match. You can verify the issuer of the certificate to ensure that it is a trusted Certificate Authority. You can also use a value from the certificate to retrieve user data from an LDAP directory. The values available include:

•Subject DN

•Subject Alternative Name

•Subject Key Identifier

•Certificate Fingerprint

A portion of these values can be used as well, since the policy can apply a regular expression to a value before it is used in the LDAP query. Therefore, the CN can be extracted from the DN, for instance. If a record for the user is found, the returned data can be further evaluated to arrive at an authorization decision.

To specify an SSL certificate requirement:

Step 1 As an Administrator user or a Privileged user with the Access Control role in the console, click the Access Control Browser link in the navigation menu.

Step 2 Click on the authenticator in which you want to add the credential requirement, or create a new one as described in "Working with Authenticators and Authorization Groups" section.

Step 3 Choose SSL/TLS Certificate from the Add Credential menu and click Add.

Step 4 In the SSL/TLS Certificate page, choose how you want the incoming SSL/TLS Certificate to be verified from the Verify Using menu, from these options:

•SSL Certificate Fingerprint (see "Verifying by SSL Certificate Fingerprint" for details)

•SSL Certificate Authority (see "Verifying by SSL Certificate Authority" for details)

•Certificate-Based LDAP Query (see "Verifying by LDAP Query" for details)

Step 5 If you want the certificate to be verified if present, but do not want to require requests to include a certificate, enable the option Verify only when a client certificate is present (allow requests without client certificates).

Requests are blocked in this case only if they include a certificate that does not meet the configured criteria.

Step 6 Click Save Changes to commit the changes to the working policy.

The new credential requirement appears in the Required Credentials area of the authenticator page.

You can add more than one certificate condition to an authenticator, all of which must be met by a request for the request to be accepted. Therefore, you can verify by fingerprint match, for example, as well as by certificate authority on single certificate in a request.

Verifying by SSL Certificate Fingerprint

A certificate in an incoming request can be verified by comparing its fingerprint to that of a consumer certificate that has already been loaded in the policy. If the fingerprints match, the request is accepted.

For fingerprint matching to work properly, the CA that issued the certificate to be matched needs to be specified as a trusted CA in the policy. (During SSL negotiation, the ACE XML Gateway indicates to the client which CA's it will trust. Some types of clients do not send a certificate without this hint, which means that if the CA is not listed as a trusted CA, the client will never submit the certificate.)

To require the client certificate to match one that has been uploaded into the policy:

Step 1 Choose require a client certificate that is identical to this certificate.

Step 2 Choose the certificate to be matched, uploading it if it is not already identified as a resource.

If it is not already uploaded, upload the CA certificate for the issuer of the certificate for which you are configuring fingerprint matching.

Verifying by SSL Certificate Authority

You can choose to trust a certificate based on the identify of the Certificate Authority who issued the client certificate. To verify certificates by CA, the CA certificate must be loaded as a trusted CA certificate into the policy. By default, the ACE XML Gateway is not set up to trust any CA. You can specify CA's to be trusted in the trusted authority resource page. For more information, see "Uploading a Certificate Authority Resource" section on page 28-286.

To require the client certificate be signed by a trusted CA:

Step 1 Choose require a client certificate that is signed by.

Step 2 Choose whether you want the certificate to be signed by any of the certificate authorities that are configured in the policy or the CA's you select.

Step 3 Optionally, specify additional constraints for the certificate by choosing from these options:

•Also require that the client certificate subject's Distinguished Name matches, to match the client certificate subject's DN against a regular expression you specify.

•Also require that the client certificate issuer's Distinguished Name matches, to match the client certificate issuer's DN against a regular expression you specify.

•Also require that the client certificate subject's Distinguished Name exactly matches this certificate, to require a match between the client certificate subject's DN and a certificate you choose.

Verifying by LDAP Query

The ACE XML Gateway supports LDAP as a verification mechanism for an SSL certificate subject. The condition can simply check that a record exists for a user in the directory or, as an additional check, evaluate a property of the user once the user's record is found.

An LDAP certificate check should usually be used with an authenticator condition that checks the CA of the certificate or a fingerprint match, since by itself this check does not validate the authenticity or trustworthiness of the certificate.

Also note that this type of verifier can be used to verify credentials if present, but not specifically require the credential in the request. In this way, this verifier is similar to multiple credential mode authenticators, such as multiple WSS UsernameToken and multiple SAML conditions, which do not require a credential, but verify the credentials if present.

An LDAP record is matched to a certificate subject using an identifying property from the certificate. This implies that the LDAP directory includes a value from the user certificate as a user attribute, such as the fingerprint of the user's public key, subject alternative name, or subject key identifier. Alternatively, you can use the Subject DN of the certificate, and apply a regular-expression-based text replacement to the DN, so that it matches the form of a valid user record in the directory.

The general steps for verifying certificates by LDAP are:

•Step 1: Identify the LDAP directory to use.

•Step 2: Specify the value from the certificate you want to be used to find the user record in the LDAP directory.

•Step 3: Specify the filter to be executed in the LDAP directory. The query should return the data from a user record that can be used in the access decision, or simply the user record to check for a valid user account in the directory.

•Step 4: Specify a regular expression that, when applied to the data returned by the filter, returns a result for a valid user.

The procedures for verifying a client's SSL certificate by LDAP directory are detailed below. Example configuration values follow these steps.

Step 1 Select Certificate-based LDAP Query in the Verify Using menu.

Step 2 Choose the option Verify only when a client certificate is present if you want to validate the certificate if present in the request, but not specifically require that a credential be present. That is, requests without the credential will be accepted by this authenticator, but if included, the credential must be verifiable as specified by this authenticator.

Step 3 From the Server menu, choose the LDAP server against which the credential will be verified. If the server you want to use does not appear in the list, click New LDAP Server and configure the connection to the LDAP directory.

Step 4 In Certificate Field, choose the property of the client certificate that contains data to be used for verification. This will be the data bound to the %d variable, which is the system variable that identifies a user or application.

Step 5 If the certificate field value cannot be used "as is" in the LDAP filter (as would usually be the case when using the Subject DN), the value needs to be converted to a form that matches the compared data in the LDAP directory. Enable this conversion by selecting the Apply regular expression substitution to the certificate field value option and entering a regular expression and substitution string. (If the certificate value does not need to be modified before the ACE XML Gateway runs the query, you can leave the regular expression option disabled.)

With this option selected, the regular expression is applied to the certificate property you choose, with the resulting data being used to populate the %d variable.

Data matched by the regular expression is available as backslash variables, which have the form "\1" and "\2" (which would be the first and second regular expression matches from the source value). The result should be a DN in the form suitable for comparison with the LDAP data.

To apply a regular expression to the source value:

a. Select the Apply regular expression substitution to the certificate field value checkbox.

b. Enter the regular expression to use in the Regex field. The regular expression should match the portion of the field you want to use in the LDAP query.

c. In the Replace With field, use static text and back-reference variables to compose the source comparison value. For an example, see the discussion following these steps.

If the regular expression does not produce a match against the property value, the property value is not changed. To help you troubleshoot composition of the regular expression, the event log shows the results of the regular expression comparison, whether a match and replacement occurred or no data was matched.

Step 6 In the User DN and Bind with Password fields, specify credentials the ACE XML Gateway should use to log onto the LDAP directory to verify the user.

This should be the user DN and password of a known-good user account with query permissions in the directory. It is recommended that you create a dedicated user account in the directory for the ACE XML Gateway to use for this purpose.

Step 7 In the Base DN field, specify the location of the directory in which you want the query filter to be applied.

In most cases, this should be %d, which will have the value specified in the Client Certificate Settings (often the Subject DN of the certificate after processing by the Regex and Replace With result).

Step 8 In Filter, enter an LDAP query to be executed at the Base DN.

This could be a record under the one identified by the Base DN, or if the Base DN identifies the user record to be evaluated, it may be a filter that simply passes through the result (that is, a no-op filter), such as {{{(objectClass=*)}}}. This would return the entire record for the Base DN.

Step 9 Optionally, use the Attributes field to reduce the information returned by the filter to the value of specific LDAP attributes. This can simplify the Match Regex needed to validate the results.

For example, to use the e-mail addresses of sales people and no other data, enter mail in the Attributes field. This returns only the list of mail attributes for each record returned by the query.

You can specify more than one attribute to get multiple values. Use spaces to separate multiple attribute names.

The attribute results are available for populating SAML credentials generated for outgoing requests (enabled in the SAML generation page with the option labelled Include LDAP records, if available, as SAML Attribute Statements).

Step 10 In the Match Regex field, enter a regular expression to be run against the attribute result or filter result, if no attribute is specified.

This expression can test an attribute of the user record that has been returned, such as group membership. If applying the regular expression produces a match, the authentication/authorization is considered successful.

Step 11 Click Save Changes to commit your changes to the working policy.

For example, given an LDAP directory that contains the fingerprint of each user's certificate in an attribute called certFingerprint, you could set up verification settings as follows:

•Certificate field: Certificate Fingerprint (SHA-1)

•Regular expression substitution: disabled

•Base DN: dc=cisco,dc=com

•Filter: (certFingerprint=%d)

The certificate field value used is the certificate fingerprint, which populates the %d variable. The filter checks this value against the certFingerprint. If the certFingerprint in the directory matches %d, the filter is satisfied and this condition met.

If using the Subject DN as the match value, it is important to understand how the ACE XML Gateway renders the DN. When the ACE XML Gateway processes a certificate, it creates a string representation of the certificate's Subject DN.

Before starting, you should send a request with the certificate to the ACE XML Gateway with debug-level logging enabled. The normalized DN in the certificate will appear in the event log. This is the value against which your regular expression will run. For example, a request that contains the certificate from the sample certificate, beagle.cer, produces an entry with the following description:

DN of client certificate subject is emailAddress=operations@beaglepartners.com,CN=Beagle Partners Inc.,OU=Operations,O=Beagle Partners Inc.,L=Hampton,ST=Virginia,C=US

This is the value against which the regular expression would be run. Accordingly, the regular expression needs to be designed with this DN format in mind.

For example, to covert this source Subject DN into the following value:
CN=Beagle Partners Inc.,OU=Operations,O=Beagle Partners Inc.,ST=Virginia  
Would require a regular expression of:
emailAddress=[^,]*,CN=([^,]*),OU=([^,]*), O=([^,]*),L=[^,],ST=([^,]*),.*  
The emailAddress is ignored (since the regular expression not parenthesized). The next steps of the expression put the value after CN= into the variable \1, the value after OU= into \2, and so on. The L value is, like the email address, ignored.

The Replace With value would be:
CN=\1, OU=\2, O=\3, ST=\4  
Figure 6-3 shows this sample configuration.

Figure 6-3 Regular expression configuration

HTTP(S) Basic Authentication Conditions

Authenticator can be configured to evaluate HTTP Basic Authorization credentials. In this type of credential, username/password credentials are passed in the header of the message.

To require an HTTP Basic Authorization credential:

Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu.

Step 2 Click on the authenticator in which you want to add the requirement or create a new one as described in "Working with Authenticators and Authorization Groups" section.

Step 3 Choose HTTP(S) Basic Authentication from the Add Credential menu and click Add.

Step 4 Choose how you want the credential to be verified by choosing it from the Verify Using menu.

For more information, see "Verifying Password-Based Credentials" section.

Step 5 Click Save Changes to commit the changes to the working policy.

The new credential requirement appears in the Required Credentials area of the authenticator page.

WSS Username/Password Token Conditions

WSS UsernameToken is an authentication mechanism defined in WS-Security specification "Web Services Security UsernameToken Profile 1.0." This type of token appears in the SOAP header portion of a SOAP envelope, as shown in the example token in Example 6-1.

Example 6-1 WSS UsernameToken credential
... 
<soap:Header   
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"> 
 <wsse:Security>  
 <wsse:UsernameToken> 
  <wsse:Username>username</wsse:Username> 
  <wsse:Password  
         Type="wsse:PasswordText">password</wsse:Password> 
 </wsse:UsernameToken>  
</wsse:Security>   
... 
WSS Username credentials are available as source credentials for credential mediation. That is, the username/password values from an incoming request can be used to generate a basic auth or SAML token in the outgoing request. Further, any custom WSS Username attributes in the WSS Username element can be mapped to attributes in generated SAML AttributeStatements. To enable this option, configure the mapping option labeled Send extension attributes from WSS UsernameTokens as attributes in generated SAML AttributeStatements on the System Management > Gateway Settings page.

A request can contain more than one WSS UsernameToken, each of which can represent a participant in generating the request. For example, a request may have one credential for the end user who generated the request and another for the application used. You can configure an authenticator to qualify multiple credentials in a request.

To qualify multiple credentials, enable multiple credential mode in the WSS UsernameToken authenticator. The configuration needs to specify the number of credentials that the ACE XML Gateway should expect in the message. This is the number of credentials checked and available for credential generation. If a request contains more than this number, the additional credentials are ignored.

Once the multiple credential mode is enabled, you can add additional conditions based on the WSS UsernameToken credential. If you only specify one condition, all credentials need to meet that condition. In this case, the condition would probably use a verification mechanism that can verify multiple identities, such as LDAP query. If you specify two conditions, on the other hand, a request with two credentials that meet just one of the conditions will be accepted. In other words, all credentials in the request must meet all conditions of at least one authenticator to be accepted.

It is important to note that multiple credential mode does not require a credential to be present. If a request does not contain a credential, it will be accepted by the authenticator. This can have the effect of making the service associated with this type of authenticator publicly accessible. You should use this mode only to process and validate credentials, if present, but not to enforce minimum credential requirements.

Also note that any virtual service to which this authenticator is applied must have SOAP header processing enabled.

To set up a WSS UsernameToken requirement in an authenticator:

Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu.

Step 2 Click on the authenticator in which you want to add the credential requirement, or create a new one as described in "Working with Authenticators and Authorization Groups" section.

Step 3 Choose WSS Username/Password from the Add Credential menu and click Add.

Step 4 To enable multiple credential validation, follow these steps:

a. Click the configure multiple WSS UsernameToken mode link.

b. Select the Enable multiple WSS UsernameToken mode, verifying at most option, and specify the number of tokens expected in the message in the verifying at most field.

The ACE XML Gateway will process the number of tokens you specify. If the message has additional credentials, they are ignored. With this option enabled, the ACE XML Gateway will always check for at least one credential, even if 0 or a negative number is specified as the number of tokens per message to be verified.

c. Click Save Changes in the Multiple WSS UsernameToken Mode page.

You can now add multiple conditions for WSS UsernameToken credentials to the authenticator.

Step 5 In the authenticator page, again add a WSS UsernameToken requirement.

Step 6 Use the Verify using menu to specify how the username and password values are to be verified.

For more information, see "Verifying Password-Based Credentials" section.

Step 7 Click Save Changes.

Since WSS username/password credentials are passed in the header of the message, you must enable SOAP header processing on all message handlers to be associated with the authenticator.

Step 8 If SOAP header processing is not already enabled, in the Virtual Services browser, click the name of the handler or virtual service that uses the authenticator.

Step 9 In the Request Processing area of the page, click the edit link next to SOAP Header Processing.

Step 10 If it is not already enabled, check the Process header elements for SOAP role check box.

If not configuring other header processing tasks, you can retain the default values for the other settings.

Step 11 Click Save Changes to commit the changes to the working policy.

WSS Username/Password credential checking is now enabled. Deploy the policy to have the ACE XML Gateway enforce this change.

WSS Password Digest Conditions

By default, the WSS Username/Password credential described in the previous section resides in the message header unencrypted. Assuming transport-level encryption is used to secure the message as it crosses the network, the password nevertheless is unprotected once it arrives at its destination.

For more security, you can encrypt the credential through the use of WSS Password Digest. WSS Password Digest encrypts the password value, making it secure at the endpoint as well as in transit.

Note In addition to password encryption, WSS Password Digest is intended to prevent replay attacks through the use of a nonce, an arbitrary value that must be unique across requests. However, nonce values are not retained at the ACE XML Gateway, so nonce uniqueness is not enforced. Also note that the ACE XML Gateway does not check digest expiration.

In a SOAP envelope header, a password digest looks as follows:

Example 6-2 WS Security Password Digest credential
... 
<soap:Header> 
 <wsse:Security 
        xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/ 
                  oasis-200401-wss-wssecurity-secext-1.0.xsd"  
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/ 
                 oasis-200401-wss-wssecurity-utility-1.0.xsd"> 
  <wsse:UsernameToken> 
   <wsse:Username>jdoe</wsse:Username> 
   <wsse:Password>Ikky9DZH7lZ52JGDaZDys8ALbbM=</wsse:Password> 
   <wsse:Nonce>MQ==</wsse:Nonce> 
   <wsu:Created>2006-02-13T15:43:46Z</wsu:Created> 
  </wsse:UsernameToken> 
 </wsse:Security> 
</soap:Header> 
... 
Notice the values of the Password and Nonce elements in the header. As indicated by the WS-Security specification, the password token is generated by combining and encrypting (SHA1) the concatenated, Base64-encoded nonce, timestamp, and password.

To evaluate a token, therefore, the ACE XML Gateway applies Base64 decoding of the Password from the message, producing a hexadecimal result. It then decodes the Nonce and combines it with the timestamp in the message and password (stored in the authenticator configuration). It then applies SHA1 encryption to the concatenated result. The hexadecimal results are compared to the decoded digest value. If they match, the request is validated.

To get a WSS Password Digest credential requirement, a virtual service must be configured for SOAP header processing. The settings for enabling SOAP header processing are in the Request and Response processing settings for the virtual service.

To set up a WSS Password Digest credential requirement:

Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu.

Step 2 Click on the authenticator in which you want to add the credential requirement, or create a new one as described in "Working with Authenticators and Authorization Groups" section.

Step 3 Choose WSS Password Digest from the Add Credential menu and click Add.

Step 4 Type the username and password values to be accepted in the appropriate fields and click Save Changes.

The password should be the un-encoded password value, that is, the one used to generate the digest password by the client.

Step 5 Since WSS username/password credentials are passed in the header of the message, SOAP header processing must be enabled for handlers associated with the authenticator. If it is not already enabled, enable header processing as follows:

a. In the Virtual Services browser, click the name of the handler or virtual service that uses the authenticator. The message specification settings for the service handler appear.

b. In the Request Processing area of the page, click the edit link next to SOAP Header Processing.

c. If it is not already selected, click the checkbox next to Process header elements for SOAP role.

If no other header processing tasks are required, the remaining settings can remain at their default values.

Step 6 Click Save Changes to commit the changes to the working policy.

WSS Password Digest credential checking is now enabled. To make the ACE XML Gateway enforce this change, deploy the policy.

SAML Token Conditions

SAML (Security Assertion Markup Language) is an XML-based protocol for exchanging security information. SAML is intended to provide single sign-on capabilities across organizational boundaries. A SAML credential takes the form of a token element in the WS-Security header block of a message.

The ACE XML Gateway can act as a relying party or asserting party for SAML credentials. That is, you can configure authenticator conditions based upon SAML assertions or add assertions to outgoing messages. The ACE XML Gateway supports SAML versions 1.0, 1.1, and 2.0.

For a SAML assertion to be trusted by the ACE XML Gateway, its integrity must be ensured either by XML Signature or through SSL encryption of the connection between the consumer and Gateway. Thus, for an SSL requirement, the virtual service must be configured to use an SSL-secured port.

As with other types of credential requirements, a SAML requirement is specified in an authenticator. You can set up an authenticator to require a single SAML token or multiple tokens in an incoming request. By default, the SAML tokens are consumed by the ACE XML Gateway, meaning they are taken out of the request after validation. To configure passthrough, specify backend service authentication for the service interface definition.

A SAML condition must require at least one of the following elements in the SAML assertion:

•authentication statement

•authorization decision statement

•attribute statement

The authenticator can specify various properties the element needs to have to be accepted. For example, it may require the assertion to have an authentication statement that indicates the subject was authenticated by password.

Timestamp conditions in SAML assertions are automatically validated by the ACE XML Gateway. NotBefore and NotOnOrAfter conditions, for example, are checked for conflict against the ACE XML Gateway's internal system clock and, if invalid, cause the assertion to be rejected.

Note The ACE XML Gateway can cache SAML assertion validation results, avoiding the performance burden of validating identical assertions. Enable SAML assertion caching from the System Management > Gateway Settings page. SAML Assertion Caching settings appear near the bottom of the page.

To configure a SAML token requirement:

Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu.

Step 2 Click on the authenticator for which you want to add the SAML credential requirement or create a new one as described in "Working with Authenticators and Authorization Groups" section.

Step 3 From the Add Credential menu, choose SAML Token and click Add.

Step 4 In Verify Using menu, choose the SAML version of the credential to be authenticated:

•SAML 1.0

•SAML 1.1

•SAML 2.0

Your selection affects the options available on the page, reflecting the differences between SAML versions. Use the options to specify the characteristics of the assertion this authenticator requires.

Step 5 A request can contain multiple SAML assertions. Choose whether this condition should apply to a specific number of credentials in the request or to all credentials by choosing from:

•At least allows you to specify a minimum number of required credentials in the request which must meet this condition. If a request has fewer valid assertions than the configured amount, it is blocked.

•All specifies that all assertions in the request must meet this condition.

Important to note is that all does not require a minimum number of credentials in the request. If a request does not contain a SAML assertion, it will be accepted by the authenticator. This can have the effect of making the service associated with this type of authenticator publicly accessible. You should use this mode only if you want to process and validate credentials, if present, but not to enforce minimum credential requirements.

Step 6 If appropriate for the SAML assertions to be accepted, specify Audience conditions as follows:

a. Select the checkbox labelled Require an Audience Condition that matches any one of the following.

b. In the entry field beneath the Require an Audience Condition checkbox, type the audience URI required for the assertion.

c. Add requirements for additional Audience conditions if needed.

A message can contain multiple Audience elements, any of which can be required by an authenticator. If an assertion includes Audience elements not specifically required by the authenticator, the elements are ignored.

Step 7 The Subject of an assertion refers to the user, application, or other party for whom the assertion attests. Optionally, you can specify requirements for the Subject by setting a NameIdentifier requirement:

a. Click the NameIdentifier is button.

b. In the field next to NameIdentifier is, type the subject NameIdentifier value that the authenticator is to require.

c. If needed, qualify the NameIdentifier value with an administrative or security domain by selecting the with NameQualifier checkbox and typing the NameQualifier value in the text field.

A name qualifier specifies an administrative or security domain. It provides a means of federating names from disparate user stores to avoid collisions.

d. Specify the format of the NameIdentifier value by choosing the with Format checkbox and choosing an option from the with Format menu. The options vary by SAML version, but in general they are:

–#emailAddress requires the NameIdentifier value to be in the local-part@domain format of an email address as specified by "addr-spec" in IETF RFC 2822, such as:

<NameIdentifier Format="urn:oasis:names:tc:
SAML:1.0:assertion#emailAddress">
jdoe@example.com
</NameIdentifier>

–#X509SubjectName requires the NameIdentifier to be in the form of an X.509 Subject DN.

–#WindowsDomainQualifiedName requires the NameIdentifier value to be in the DomainName\UserName format of a domain-qualified user name for the Microsoft Windows™ platform. Optionally, the domain name and "\" separator may be omitted.

To ignore the NameIdentifier element, click the Ignore the NameIdentifier value button.

Step 8 The Subject Confirmation settings control how the integrity of the assertion is to be evaluated by the ACE XML Gateway. To configure how the Subject is confirmed:

•Choose the confirmation method to be accepted in incoming assertions from:

–Sender Vouches allows the "sender vouches" confirmation method. The sender vouches confirmation method implies that the relying party (the ACE XML Gateway in this case) has an existing trust relationship with the sender or that the backend service does not require a more stringent requirement level than that implied by sender vouches.

–Holder-of-key means that the subject may be authenticated by the holder-of-key confirmation method, in which key information is passed in the element SubjectConfirmationData. The ACE XML Gateway verifies the referenced key against the SSL/TLS certificate requirement for the authenticator.

–Artifact directs the Gateway to extract from the message a SAML artifact that it can use to verify the identity of the sender.

–Bearer (for SAML 1.1) specifies that the subject of the assertion may confirm itself, subject to any optional constraints on the confirmation that are specified in the SubjectConfirmationData element.

The URI prefixes for the methods are:

–urn:oasis:names:tc:SAML:1.0:cm applies to sender-vouches, holder-of-key, artifact, and bearer

–urn:oasis:names:tc:SAML:2.0:cm applies to sender-vouches, holder-of-key, artifact, bearer

For example, an incoming message would indicate holder-of-key as follows:

<SubjectConfirmation
Method="urn:oasis:names:
tc:SAML:1.0:cm:holder-of-key">
<SubjectConfirmationData>
...
</SubjectConfirmationData>
</SubjectConfirmation Method>

•To specify the method by which the message integrity is ensured, choose an item from the Integrity Protection menu:

–SSL (HTTPS) means that the connection used to make the request must be secured by SSL.

Note For increased security, configure the authenticator to test SSL/TLS credentials (see "SSL/TLS Certificate Conditions" section) if you choose this confirmation method.

–XML Signature means that the message must supply a public key that the authenticator can use to verify the signed elements of the message.

Step 9 Choose a Subject Statement the assertion must have. You must require at least one subject statement:

•Require an Authentication Statement. Select this option to require an authentication statement, of any type or one that indicates a particular authentication method.

If you specify an authentication method, the assertion needs to reflect that authentication method. If it does not, the message is rejected. The following methods are available:

–Password method indicates that a password was used to authenticate the subject. If another authentication method was used, the authenticator rejects the message.

–Kerberos requires that Kerberos was used to authenticate the subject.

–Secure Remote Password requires that the Secure Remote Password protocol was used to authenticate the subject (see RFC 2945).

–Hardware Token requires that a hardware token was used to authenticate the subject.

–SSL/TLS Certificate requires that either of the SSL or TLS protocols was used to perform certificate-based client authentication.

–X.509 Public Key requires that a mechanism based on an X.509 public key was used to authenticate the subject.

–PGP Public Key requires that a mechanism based on a key authenticated by means of a PGP web of trust was used to authenticate the subject.

–SPKI Public Key requires that a mechanism based on SPKI public key infrastructure was used to authenticate the subject.

–XKMS Public Key requires that a mechanism based on an XKMS trust service was used to authenticate the subject.

–XML Digital Signature requires that an XML digital signature was used to authenticate the subject.

–Unspecified can be used if the assertion may indicate "unspecified" as the confirmation method.

•Click the Require an Authorization Decision Statement that permits access to option to specify a statement based on an authorization decision statement that permits access to a specified resource.

•To require attribute statements in assertions, click the Require Attribute Statement(s) checkbox and specify attribute requirements using these fields:

–Attribute Name is the name of the required attribute.

–Attribute Namespace is the namespace in which the AttributeName element is interpreted.

–Attribute Value field is a text value of the attribute.

Step 10 Click Save Changes to commit your changes to the working policy.

Once the policy is deployed, the authenticator rejects messages that do not meet all of the attribute statement criteria you specify.

XPath Password Conditions

The XPath Password credential is one of several types of password-based credentials in the ACE XML Gateway. It is verified by one of the mechanisms described in "Verifying Password-Based Credentials" section.

An XPath password credential requirement tests two values at a location identified by XPath in the message. For mediation and identity tracking purposes, the values are interpreted as username and password values.

Note XPath password checking does not work for incoming messages that are encrypted. Since this type of credential check occurs before messages are decrypted, the requirement cannot be satisfied by an encrypted message.

To set up an XPath username/password authentication requirement:

Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu.

Step 2 Click on the authenticator for which you want to specify an access condition or create a new one.

Step 3 From the Add Credential menu, choose XPath Password and click Add.

Step 4 Type the location where the credentials are expected to appear in the body of the message by XPath expression.

For example, a username at the following location of an incoming XML message:

//Envelope/Body/retrieveQuote/user

Can be extracted with the following XPath expression:

//*[local-name()='Envelope']/*[local-name()= 'Body']/*[local-name()='retrieveQuote']/ *[local-name()='user']/text()

Note The local-name() function is a standard XPath function that lets you avoid having to qualify each element name by namespace.

Step 5 The ACE XML Gateway will extract username and password values for the location identified by the XPath. Configure how you want to have the values verified by choosing the appropriate method from the Verify Using menu.

Step 6 Click Save Changes to commit the changes to the working policy.

The new credential requirement appears in the Required Credentials area of the authenticator page.

Security Token Conditions

A security token is a single-part value from either the HTTP header, GET or POST argument, or a portion of the message identified by XPath. You can configure authentication based on the token value. The requirement can verify the token by regular expression or by an external SOAP service.

Note Security token checking does not work for incoming messages that are encrypted. Since this type of credential check occurs before messages are decrypted, the requirement cannot be satisfied by an encrypted message.

In verifying a token by SOAP service, the ACE XML Gateway sends the token to the service in the form of a SOAP request and expects an access decision in the response. If the term "Permit" (case-sensitive) appears as the content of the first element under the SOAP body element of the response, the user is considered accepted by this condition. If "Permit" does not appear at this location of the response, the request is considered to be rejected.

The ACE XML Gateway generates the access decision request based on the configuration for the requirement. The request can include information on the consumer request, such as the service requested, which can be used to inform the decision.

A sample request appears as follows:

Example 6-3 Sample SOAP authentication request (line breaks added for readability)
<?xml version="1.0" encoding="UTF-8"?>  
 <soap:Envelope 
        xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
        xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
    <soap:Body soap:encodingStyle= 
           "http://schemas.xmlsoap.org/soap/encoding/"> 
       <authService> 
          <token xsi:type="xsd:string">[tokenvalue]</token> 
          <path xsi:type="xsd:string">/service/order.asmx</path> 
          <action xsi:type="xsd:string"> 
              "http://oakinsurance.com/order/retrieveQuote" 
          </action> 
          <method xsi:type="xsd:string">retrieveQuote</method> 
          <methodns xsi:type="xsd:string"> 
              http://oakinsurance.com/order/ 
          </methodns> 
       </authService> 
    </soap:Body> 
 </soap:Envelope>
In the sample request:

•authService is the Method value in the authenticator condition configuration.

•token is the value extracted at the XPath (or HTTP header) of the consumer request.

•path is the path on the ACE XML Gateway for the service requested by the consumer.

•action is the SOAPAction in the original consumer request.

•method is the service method requested in the original consumer request.

•methoddns is the method name space in the original request.

The service that receives the request can use these values in any way desired to make an access decision. From the ACE XML Gateway's point-of-view, it must simply return a response in the expected form.

A suggested structure for the response is described in the WSDL file available for downloading from the security token configuration page in the ACE XML Manager.

A positive response from the service to the Gateway must contain the word "Permit" as the content of the first subelement of the first element under the SOAP Body. The ACE XML Gateway will block the consumer request otherwise.

For example, the ACE XML Gateway would interpret the following as a positive response.

Example 6-4 Access Permitted
<?xml version="1.0" encoding="UTF-8"?> 
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
  <soap:Body> 
    <AuthenticationService> 
      <response>Permit</response> 
    </AuthenticationService> 
  </soap:Body> 
</soap:Envelope> 
In this case, "Permit" appears in an element named response. However, the element name is unimportant to the ACE XML Gateway; it may be named anything, as may the decision element's parent element. What is important is that "Permit" appears in the content of the first element below the first SOAP Body subelement of a positive response. Any other text will result in the consumer's request being blocked.

The ACE XML Gateway locates the decision in the response with the following XPath:

/*[local-name()='Envelope']/*[local-name()='Body']/*[1]/*[1]/text()

The following also indicates a positive decision.

Example 6-5 Access Permitted by myAuthService
<?xml version="1.0" encoding="UTF-8"?> 
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
  <soap:Body> 
    <myAuthService> 
      <decision>Permit</decision> 
    </myAuthService> 
  </soap:Body> 
</soap:Envelope>
To configure a security token requirement:

Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu.

Step 2 Click on the authenticator for which you want to specify an access condition or create a new one.

Step 3 Choose Security Token from the Add Credential menu and click Add.

Step 4 Identify the source of the token, from these options:

•HTTP argument. An HTTP argument value drawn from the query string of a GET request or the body of a form POST (where the content is of type application/x-www-form-urlencoded).

•HTTP header. The value of an HTTP header in the message.

•XPath expression. Any content from the message identified by XPath expression.

Step 5 Choose how the token is to be verified, using either:

•a regular expression

•an external service

Step 6 To use an external service, follow these steps:

a. Choose SOAP Callout from the Verify Using menu.

b. Enter the values for the authorization service:

–Service Host is the host name of the machine that hosts the authorization service.

–Port is the port on which the service host listens for authorization requests.

–Path is the path of the authorization service on the host.

–SOAPAction is the SOAPAction value to use in the request.

c. Enter the name of the method that performs the authorization and a method namespace.

d. If desired, have SOAP arguments namespace-qualified (for Document-style services) and enable response caching.

Step 7 Click Save Changes. The new credential requirement appears in the Required Credentials area of the authenticator page.

When needed, you can have the WSDL generated for the authorization service by clicking the Show WSDL for this Authorization Service button. By generating service code from this WSDL in an IDE, you can quickly create the skeleton code for an authorization service.

Time-of-Day Conditions

Making a service available only during the normal business hours of its expected audience can contribute to the security of backend systems. The ACE XML Gateway system allows you to specify an authenticator requirement based on the time of day. The system uses its internal system clock to evaluate requests. Requests outside permitted times are rejected by the authenticator.

To set up a time-based check:

Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu.

Step 2 Click on the authenticator for which you want to specify an access condition or create a new one.

Step 3 Choose Time-of-Day from the Add Credential menu and click Add.

Step 4 In the Time-of-Day edit page, click the accept the message only during button.

Step 5 In the From and To fields, enter the time range in which you want the authenticator to accept messages as Greenwich Mean Time (GMT). The range must be in GMT even if the Manager web console is set to display times using another time zone.

This value must be in the form NN:NN, in which N is a whole number greater than 1 and less than 12.

Step 6 From the menu next to the From field, choose AM or PM.

Step 7 In the To field, type the hour of the day at which to stop accepting messages.

This value must be of the form NN:NN, in which N is a whole number greater than 1 and less than 12. It must be Greenwich Mean Time (GMT), even if the Manager web console displays a different time zone.

Step 8 From the pull-down menu next to the To field, choose AM or PM.

Step 9 To specify the days of the week on which to accept messages, click one or more checkboxes to represent the days on which to accept messages.

Step 10 Click Save Changes to commit the changes to the working policy.

The Time-of-day credential condition appears in the Authenticator settings. Deploy your changes to have them take effect at the ACE XML Gateway.

Verifying Password-Based Credentials

Several credential types in the ACE XML Gateway are based on passwords. These include HTTP Basic Authentication, WSS Username/Password, and XPath Password. In addition, custom credentials created through the ACE XML Gateway SDK can extend the generic username/password credential type.

Password-based credentials can be verified with the following verification mechanisms:

•fixed values stored in the policy

•a password file

•an Active Directory^® server

•an LDAP server

A fixed value is an explicitly set username/password combination in the authenticator that the consumers' credentials must match. A password file is an Apache-style htpasswd file that contains the username and password combinations to be accepted. To be available in the credential interface, the file must first be uploaded as a resource in the ACE XML Manager. To upload the file, click the Password Files link in the navigation menu and from there add a password file as indicated by the ACE XML Manager interface.

For Active Directory and LDAP verification, several modes of verification are available. These modes and the steps for setting them up are described in the following sections.

Verifying Credentials with Active Directory LDAP Query

The ACE XML Gateway supports Active Directory directory service as a verification mechanism for password-based credentials passed in service requests. The ACE XML Gateway can verify user credentials with Active Directory in two ways:

•The ACE XML Gateway can try to bind to the Active Directory server with the user's DN and password passed in the request. Success indicates that the credentials match a directory account.

•In addition to the bind attempt, the ACE XML Gateway can check the user's memberOf attributes for a particular value.

For verification to work, the username passed in the service request must be either the DN of the Active Directory user account or a value that can be mapped to the DN through another attribute (such as a sAMAccountName or mail attribute).

In practice, it's unlikely that usernames in service requests will be identical to the DN of accounts in the Active Directory server (such as cn=Joe User,cn=Users,dc=Cisco,dc=Com). But if the username does map to another user attribute, such as sAMAccountName, you can configure a mapping query that enables the ACE XML Gateway to retrieve the DN prior to the bind attempt.

To issue the mapping query, the ACE XML Gateway first binds to the Active Directory server with a known-valid account. It is recommended that you create a dedicated account in the Active Directory server specifically for the ACE XML Gateway.

Figure 6-4 illustrates the interaction between the ACE XML Gateway and the Active Directory server if verification is configured in this three-step process. In the sequence shown, verification is successful. A failure at any point, such as the inability to match an attribute for the mapping query, would of course abbreviate the process.

Figure 6-4 Active Directory Verification Sequence

Configuring Active Directory LDAP Query Verification

To configure username/password credential verification with an Active Directory server:

Step 1 After setting up an authenticator condition for one of the password credential types (such as HTTP Basic Authentication, WSS Username, or XPath password), choose the Active Directory Query option from the Verify Using menu.

Step 2 Choose the Active Directory server to verify user credentials from the Server menu.

If the directory you want to use appears in the Server menu, choose it from the list. If not, click the New LDAP Server button and configure a connection to the Active Directory server.

Step 3 In the simplest verification mode you can configure, the ACE XML Gateway simply attempts to log in with the username and password supplied in the request.

To use this method, choose the option labeled No lookup; use credential username as the full user DN. Note that the username supplied in the service request must be a full DN that can be used to bind to the Active Directory server.

Step 4 If the usernames supplied in service requests do not directly correspond to DN's in the directory but would match another attribute of the user, you can use a username-mapping query to acquire the user's DN, which is then used in a bind attempt.

To set up a mapping query:

a. Select the Map credential username to option.

b. From the menu, choose the attribute whose value will match the username of a valid user. The most likely attribute options are preconfigured, and include mail, sAMAccountName, and userPrincipalName. However, you can select other LDAP attribute and specify any attribute name desired.

The ACE XML Gateway creates a filter based on your choice, such as (sAMAccountName=juser).

c. Specify valid credentials for the ACE XML Gateway to use to bind to the directory to perform the query. From the Bind menu, choose:

–anonymously if the directory accepts anonymous binds and the anonymous account is configured with privileges that enable finding user records.

–with DN specified to have the ACE XML Gateway bind with a specific account. In this case, enter a valid distinguished name in the Bind with DN field and its password.

Note It is recommended that you create a dedicated account in the directory for the ACE XML Gateway to use for this purpose. If you have done so, enter the DN and password for the ACE XML Gateway's account.

d. In the Base DN field, enter the "folder" that contains the user accounts you want to query. A sample value would be something like: cn=Users,dc=Cisco,dc=Com

Step 5 Optionally, further qualify authenticated users by checking their memberOf attribute for a particular value.

To do so, click the checkbox labeled Verify that user is a member of a group with name and type the value of the memberOf attribute that qualifies the user for the authenticator.

Step 6 The Error Handling option allows a client to get an extended error code received from the LDAP system. The option is introduced for the following types of authenticators:

·Active Directory LDAP Query

·LDAP Bind Success

·LDAP Query

In order to add the LDAP error code to the response the exception mapping must be configured. The %s should be added to the Message Body field for "Authentication or authorization failure". For more information, see "Configuring Global Exceptions" section on page 22-212.

Step 7 Click Save Changes to commit changes to the working policy.

The credential condition appears in the authenticator settings. Deploy your changes to have them take effect at the ACE XML Gateway.

Verifying Credentials with LDAP

The steps for verifying password-based credentials with an LDAP server are similar to those described for Active Directory verification in "Verifying Credentials with Active Directory LDAP Query" section.

As for Active Directory verification, the ACE XML Gateway can verify credentials for LDAP through several methods:

•In the simplest case, the ACE XML Gateway attempts to bind to the LDAP server with the username and password in the request. If the bind attempt succeeds, the request is considered to meet this condition.

•With or without a bind attempt, the ACE XML Gateway can query the directory for the value of a particular user attribute.

In the bind attempt, the ACE XML Gateway can submit as the username a DN you specify or a DN acquired through a setup query. The setup query maps the user identifier from a service request (such as jdoe2) to the distinguished name (DN) used in the LDAP server (such as cn=Jane Doe, cn=Users, dc=Cisco, dc=com).

Using LDAP Bind Password Verification

In the simplest password verification mode with LDAP, the ACE XML Gateway simply attempts to log in with the DN of the user and password supplied in the request. In most cases, the usernames passed in requests will not directly match the form of user DN's in the LDAP directory. Therefore, the username passed in the request must be mapped to a DN somehow.

You can do this in several ways:

•If the username corresponds to another user attribute (such as a userPrincipalName), you can have the ACE XML Gateway acquire the DN by issuing a Setup Query that searches for the attribute, getting back (if found) the full LDAP name of the matching record.

•If username values in requests will reliably match a portion of the DN, such as its common name (cn), you can avoid a setup query by specifying a "parameterized" DN.

The value of the username from the request can be added to the DN as a substitution variable, such as:

cn=%u,cn=Users,dc=Cisco,dc=Com

At runtime, %u will be replaced with the username from the request.

The following steps describe how to configure LDAP bind verification with and without a setup query:

Step 1 In the authenticator condition for a password credential type (such as HTTP Basic Authentication or WSS Username), choose LDAP Bind Success from the Verify Using menu.

The Server, Setup Query, and Bind settings appear.

Step 2 If the connection to the LDAP server you want to use is already defined in the policy, choose it from the Server menu. If it is not yet defined, click the New LDAP Server button and configure the connection to the LDAP server.

Step 3 To have the ACE XML Gateway use a setup query to acquire the DN with which to make the bind attempt, perform these steps:

a. Click the checkbox labelled Perform setup query, storing result DN in substitution variable %d.

b. Specify how the ACE XML Gateway will bind to the directory to perform the setup query by choosing from the Bind menu:

–anonymously if the directory supports anonymous access and the account has privileges to find the user records.

–with DN specified to have the ACE XML Gateway bind with a specific account. Enter a valid distinguished name in the User DN field and its password.

Note It is recommended that you create a dedicated account in the directory for the ACE XML Gateway to use for this purpose. If you have done so, enter the DN and password for the ACE XML Gateway's account.

c. In the Base DN field, enter the "folder" that contains the user accounts you want to query. A sample value would be something like: cn=Users,dc=Cisco,dc=Com

If you have a very complicated Active Directory instance with multiple trees and forests, you will probably have to use an LDAP browser to figure out the correct DN to use.

d. In the Filter field, specify the LDAP filter expression that tests a particular user property, with the goal of matching the account of the user who submitted the service request. This mapping is aided by the %u variable, which contains the value of the username from the request. For example:

(|(cn=%u)(uid=%u))

If the value of a cn or uid property under the specified base DN matches the username from the request, the ACE XML Gateway gets back the full DN of the matched record. The DN gets populated into the %d variable, which is subsequently available to the ACE XML Gateway in its bind-as-user attempt.

Step 4 In the Bind settings, configure the username the ACE XML Gateway will use to bind to the directory with the password from the request:

•If you have configured a setup query, you would most likely enter %d in this field (the variable populated with the full DN from the setup query).

•If not using a setup query, configure a parameterized DN. For example:

cn=%u,cn=Users,dc=Cisco,dc=Com

The %u variable will be replaced with the username from the request.

Step 5 Click Save Changes to commit your settings to the working policy.

The password requirement should appear in the authenticator page with LDAP Bind Request listed as the verification method.

Using LDAP Query Password Verification

In the query mode of LDAP password verification, the ACE XML Gateway queries the LDAP directory for records matching a specified filter, checks the results with a regular expression, and makes an access decision based on the results.

To perform the query, the ACE XML Gateway may optionally bind to the directory with the user credentials. This has the effect of validating the password supplied in the request. If you do not want the ACE XML Gateway to bind to the directory as a user, it can be configured to bind with its own account.

If the usernames as received in requests do not match the DN needed to bind to the directory, you may need to configure a setup query that retrieves the user DN from the LDAP directory first.

The following figure illustrates the interaction between the ACE XML Gateway and LDAP server given a configuration that reflects the most stringent verification requirements.

Figure 6-5 LDAP Query Verification Sequence

The following steps describe how to configure LDAP bind verification with or without a setup query:

Step 1 In the authenticator condition for a password credential type (such as HTTP Basic Authentication or WSS Username), choose LDAP Query from the Verify Using menu.

The Server, Setup Query, Query and Result Processing settings appear.

Step 2 If the connection to the LDAP server you want to use is already defined in the policy, choose it from the Server menu. If it is not yet defined, click the New LDAP Server button and configure the connection to the LDAP server.

Step 3 To use a setup query to acquire the user DN the ACE XML Gateway uses to bind to the directory, perform the following steps (alternatively, you can have the ACE XML Gateway bind to the directory with its own account to run the verification query, in which case you can skip this step):

a. Click the checkbox labelled Perform setup query, storing result DN in substitution variable %d.

b. Specify how the ACE XML Gateway will bind to the directory to perform the setup query by choosing from the Bind menu:

•anonymously if the anonymous account is enabled in the directory and is configured with privileges that enable the anonymous user to find the user records.

•with DN specified to have the ACE XML Gateway bind with a specific account. Enter a valid distinguished name in the User DN field and its password in the Password and Repeat Password fields.

Note It is recommended that you create a dedicated account in the directory for the ACE XML Gateway to use for this purpose. If you have done so, enter the DN and password for the ACE XML Gateway's account.

c. In the Base DN field, specify the location of the user account data in the directory, in DN format, such as cn=Users,dc=Cisco,dc=Com

If you have a very complicated LDAP instance with multiple trees and forests, you will probably have to use an LDAP browser to determine the correct DN to use.

d. In the Filter field, specify the LDAP filter expression that tests a particular user property, with the goal of matching the account of the user who submitted the service request. This mapping is aided by the %u variable, which contains the value of the username from the request. For example:

(|(cn=%u)(uid=%u))

If the value of a cn or uid property under the specified base DN matches the username from the request, the ACE XML Gateway gets back the full DN of the matched record. The DN gets populated into the %d variable, which is subsequently available to the ACE XML Gateway in its bind-as-user attempt.

Step 4 In the Query settings, configure the query for evaluating the user attributes. The result of the query will be, in the positive case, an LDIF (Lightweight Directory Interchange Format) match result, which is tested by a result processing expression you configure.

Like the setup query, a verification query is made up of bind settings and a filter. The bind attempt can be performed with known-good credentials (for example, of an account created for the ACE XML Gateway) or with credentials from the service request. In most cases, the service request credentials will be used for this step, which has the effect of validating those credentials.

To configure the verification query:

a. Specify how the ACE XML Gateway will bind to the directory to perform the verification query from the Bind menu:

•anonymously if the anonymous account access is enabled in the directory with query privileges and you do not want to validate user credentials.

•with DN specified, to have the ACE XML Gateway bind with a specific account. In this case, further specify either a valid distinguished name in the User DN field and its password (for example, for the account created for the ACE XML Gateway).

To validate the credentials supplied in the request, pass the DN of the requesting user, either as acquired from a setup query (%d) or using a parameterized DN (see "Using LDAP Bind Password Verification" section).

If passing the user's DN, choose the option labelled Use password provided by consumer for this credential to have the ACE XML Gateway bind with the password supplied in the service request.

b. In the Base DN field, type the directory that contains the user accounts you want to query. A sample value would be: cn=Users,dc=Cisco,dc=Com

If you have a very complicated LDAP instance with multiple trees and forests, you will probably have to use an LDAP browser to figure out the correct DN to use.

c. In the Filter field, specify an LDAP filter expression that queries attributes of the user. As for the user DN used to bind to the directory, you may need to use substitution variables to define a useful filter. For example:

(&(Name=Sales)(Member=%d))

This means that the "Name" of the group must be "Sales" and it must have a "Member" attribute equal to the user DN. This should return an LDIF-formatted query result similar to: "cn=support,cn=users,dc=Cisco,dc=com"

d. Use the Attributes field, if desired, to reduce the information returned by the filter to the value of specific LDAP attributes. You can specify more than one attribute to get multiple values. To do so, use a space to separate the attribute names.

For example, to use the e-mail addresses of sales people and no other data, enter mail in the Attributes field. This would just return the list of mail attributes for each record returned by the query. Using the Attributes field to narrow the filter return results can simplify the Match Regex you need to specify to validate the results.

Step 5 The result of the verification query is one or more records from the directory. You can check the results with the result processing expression. The result processing expression serves to validate the results returned by the filter.

Type a regular expression that tests the user data; that is, if it produces a match in the data, permits the user in this authenticator condition. For example, to ensure that the group returned is the sales group, type .*sales.*

LDIF output is always all lowercase, so make sure your regular expression matches the lowercase version of the string.

Note Depending on your LDAP schema and requirements, arriving at the correct filter and result processing expression to use may not be a simple matter. To help, you can use an LDAP tool such as Softerra™ LDAP Browser (http://www.softerra.com) to send the query and then tailor a regular expression that best suits your requirements.

Step 6 Click Save Changes to commit your settings to the working policy.

The password requirement should appear in the authenticator page with LDAP Query listed as the verification method.

Using Per-Authenticator XML Security Public Keys

By associating a consumer public key to an authenticator, the consumer's certificate can be used in XML encryption and XML signature verification tasks for messages accepted by the authenticator. This feature allows a virtual service to accept incoming messages from a variety of consumers while using certificates of various consumers for XML security processing tasks. That is, instead of requiring a separate virtual service for each service consumer (in order to accommodate the different client keys), this specialization can be located in the authenticators.

Note This authenticator key is used only to process message content. A different setting specifies the X.509 public key the ACE XML Gateway uses to establish an HTTPS connection with consumers for this authenticator (configurable by adding an SSL/TLS Certificate condition to the authenticator).

After the authenticator key is configured, you can apply it to message processing by choosing the consumer's XML security public key option in the appropriate area of the service handler configuration, as in Figure 6-6. The figure shows the option in the XML signature configuration settings, accessible from the SOAP Header Processing page of any SOAP service object.

Figure 6-6 Verifying XML signatures with the consumer key

To configure an XML security public key for an authenticator:

Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu.

Step 2 Click on the authenticator for which you want to specify an access condition or create a new one.

Step 3 Click the Edit link in the General section of the information page.

Step 4 If the public key resource does not appear in the XML Security Public Key menu, click the Upload button and use the Upload Consumer Certificate Resource page to add it to the list of consumer certificates.

Step 5 Choose the new XML Security Public Key resource name from the menu on the Edit General Information page.

Step 6 Optionally, have the name of the authenticator taken from the CN value of the certificate by choosing the option labelled Set the name of this Authenticator to the CN from this Consumer Certificate.

In the event log, this name is used to identify service access events permitted by this authenticator.

Step 7 Click Save Changes to save the changes to the working policy.

You can now configure message processing specifications in the virtual services associated with the authenticator to use the consumer certificate configured for the authenticator.

Identity Reports

The ACE XML Gateway can report usage information based on consumer identity. Identity reporting is available if a credential validated by an authenticator can be tied to a given consumer, such as the username of a username/password credential or the subject identifier of a SAML token (in contrast, a time-of-day authenticator check cannot be tied to a given user).

The ACE XML Gateway can report activities by consumer identity, such as number of requests, request size, and so on. This information appears in the Performance Monitor and in exported performance statistics files.

Since a network attack can often be traced to just one or a few user accounts, you can set traffic thresholds that are triggered by activities associated with a user account. Service access for a user account can be blocked without affecting other users.

User-identity settings are located in an authenticator. An authenticator may be associated with a single identity or many, depending on the nature of the credential. For instance, an authenticator that checks credentials by password (htaccess) file is associated with as many identities as there are username/password combinations in the file.

The credentials that can establish user identities include:

•IP address

•SSL/TLS Certificate

•Password-based credentials, including XPath password or WSS UsernameToken

•SAML Token

If the credential types in an authenticator do provide consumer identification, the user-identity configuration settings are not available.

Enabling Identity Reporting Features

User-identity reporting and threshold enforcement is enabled by authenticator. To enable user identity reporting and threshold limits:

Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu.

Step 2 Click on the authenticator for which you want to specify an access condition or create a new one.

Step 3 Click the Edit link next to Identity Reporting.

If the authenticator requires credentials that can identify a user, the Edit Identity Reporting page appears. If the authenticator does not use credentials that permit user identification, a message appears indicating that fact.

Step 4 Select the Enable Identity Reporting check box.

The other checkboxes on the page become enabled. The credential types used in this authenticator appear in the Service Users Identifiers area.

Step 5 Choose the credential types that the ACE XML Gateway should use to identify users from the Service Users Identifiers area.

For example, if you choose IP Address, the IP address of a validated consumer is retained and used to identify the consumer for purposes of user-specific alerting and thresholds.

You can choose more than one credential type, if desired. If you choose more than one, the values for all selected credentials must match across requests for the requests to be considered as originating from a single user. That is, if you select IP address and WSS UsernameToken as the identifiers, two requests that have the same username but different source IP addresses are not considered from a single user. However, if you only choose WSS Username as the user identifier, they are.

If you only want to view consumer identity-related statistics, you do not need to configure any other options in the authenticator. You can save and deploy to begin collecting and viewing identity-based activity logging. See "Viewing User Activity Information" section for more information.

Step 6 In the Alert Thresholds area, specify alerting and blocking thresholds for identified users, as follows:

a. To have a log event created based on user activity, select the Log a Warning-level event when a Service User authenticates via this Authenticator more than option, and configure the per-minute and burst for the option:

•times per minute is the number of authentication events per minute which, if exceeded, causes a log event.

•times at once ("burst") is the burst level, that is, the number of concurrent authentication attempts allowed.

Note For more information on these settings, see "Understanding Traffic Rate Thresholds" section on page 23-218.

b. You can cause subsequent authentication attempts to be blocked by choosing Block requests from any Service User who authenticates via this Authenticator more than. Configure the following settings for this option:

•times per minute is the number of authentication events per minutes which, if exceeded, results in the user being blocked.

•times at once ("burst") is the burst level, that is, the maximum number of relatively concurrent authentication attempts allowed.

Note For more information on these settings, see "Understanding Traffic Rate Thresholds" section on page 23-218.

•If a user is blocked as a result of the threshold settings, specify how long in seconds blocking should continue in the Block for at least field.

Step 7 Click Save Changes to commit your changes to the working policy.

Deploy the policy to have the changes take effect at the ACE XML Gateway.

Viewing User Activity Information

After enabling user identification features in the ACE XML Gateway policy, you can view statistics on activities by the user:

Step 1 Click the Performance Monitor link in the navigation menu (in the Reports and Tools area of the menu).

Step 2 Expand the handler group for which you would like to see user information. Usage statistics for identified users appear in the list by username.

Figure 6-7 User activity in the Performance Monitor

Note For information on the statistics in the Performance Monitor, view the online help page from the Performance Monitor page.

If message traffic logging is enabled for the service, you can search the traffic log by user, as follows:

Step 1 In the navigation menu, click the Message Traffic Log link in the Reports and Tools category.

Step 2 In the Simple Search pane of the message traffic log, click the User Search tab.

Traffic associated with identified users appears in the traffic list.

Step 3 To search for traffic for a particular user identity, type the username in the for User field and click Update View. The user search results appear in the page.

	Cisco ACE XML Gateway User Guide (Software Version 6.1)
	Controlling Access to Services
Cisco ACE XML Gateway User Guide (Software Version 6.1) Preface Introducing the Cisco ACE XML Gateway Basic Concepts First Steps Working with Virtual Services Working with Handlers, Routes, and Service Descriptors Controlling Access to Services Authenticating Requests to Backend Systems Editing and Maintaining Virtual Services Using Variables in Paths Validating Messages Processing SOAP Messages XML Encryption and XML Signature Transforming Messages with XSLT Configuring Destination Server Settings Working with Ports and Hostnames Working with JMS Traffic Working with TIB/RV and MQ Services Working with ebXML Traffic Securing Traffic with SSL/TLS Configuring Reactor Processing Caching Service Responses Mapping HTTP Error Responses Setting Global Traffic Rules Securing Web Applications Working with Virtual Web Applications Working with Profiles Developing Rules and Signatures Managing Resource Files Deploying the Policy Managing the Policy Publishing Service Information Monitoring System Status Managing Web Console Users Managing Gateway Clusters Configuring the Manager Web Console Using the ACE XML Manager SOAP API Troubleshooting Log Messages	Download this chapter Controlling Access to Services Download the complete book Cisco ACE XML Gateway User Guide Book-Length PDF (PDF - 10 MB) Feedback Table Of Contents Controlling Access to Services Overview of Access Control About Multiple Credentials and Credential Mediation Authentication in .NET Working with Authenticators and Authorization Groups Creating an Authenticator and Authorization Group Deleting Authenticators and Authorization Groups Changing an Authenticator's Authorization Group Provisioning Services Specifying Credential Requirements IP Address Conditions SSL/TLS Certificate Conditions Verifying by SSL Certificate Fingerprint Verifying by SSL Certificate Authority Verifying by LDAP Query HTTP(S) Basic Authentication Conditions WSS Username/Password Token Conditions WSS Password Digest Conditions SAML Token Conditions XPath Password Conditions Security Token Conditions Time-of-Day Conditions Verifying Password-Based Credentials Verifying Credentials with Active Directory LDAP Query Configuring Active Directory LDAP Query Verification Verifying Credentials with LDAP Using LDAP Bind Password Verification Using LDAP Query Password Verification Using Per-Authenticator XML Security Public Keys Identity Reports Enabling Identity Reporting Features Viewing User Activity Information Controlling Access to Services This chapter describes how to control access to services exposed by the ACE XML Gateway. It covers these topics: •Overview of Access Control •Working with Authenticators and Authorization Groups •Provisioning Services •Specifying Credential Requirements •Verifying Password-Based Credentials •Using Per-Authenticator XML Security Public Keys •Identity Reports Overview of Access Control The ACE XML Gateway and Manager provide a rich set of capabilities for composing and enforcing access control requirements in an application network. The ACE XML Gateway is capable of checking a wide range of credential types, including SSL certificate, SAML, WSS UsernameToken, and username/passwords in a variety of formats. The ACE XML Gateway can verify credential data itself or using an external resource, such as an LDAP directory or SOAP service. You can supplement the out-of-box capabilities of the ACE XML Gateway with the ACE XML Gateway SDK. The SDK lets you define new credential types and verification mechanisms for the policy. For more information on the SDK, see the Cisco ACE XML Gateway Developer Guide. About Multiple Credentials and Credential Mediation In credential mediation, an incoming credential is modified from one format to another for outgoing delivery. The ACE XML Gateway can mediate credentials to several formats, including HTTP Basic Authentication, NTLM header, WSS UsernameToken, and SAML token. The source credential can be any type of username/password type credential, a SAML Token Subject NameIdentifier, the DN of an SSL certificate, and more. You can set up credential mediation by configuring backend service authentication with an incoming credential as the source of the outgoing credential. For certain types of credentials, it may make sense for a given message to contain more than one instance of that type of credential. For example, a request may use multiple credentials to identify each of several participants who have contributed to the composition of the request. (In contrast, other types of credentials, such as IP address, can meaningfully occur only once in a request.) The ACE XML Gateway can evaluate and mediate multiple credentials in a request. Multiple credential mode is available for WSS UsernameToken and SAML credentials. It is important to note that multiple credential mode does not stipulate a minimum credential requirement. In other words, a request without credentials may be accepted by an authenticator in multiple credential mode. It should only be used if the intention is to evaluate multiple credentials, if present, but not require their presence. For this reason, the ACE XML Manager prevents you from provisioning a handler that has already been provisioned to an authenticator in multiple credential mode to any other authenticator. Attempting to do so raises this policy compilation warning: "A handler that is provisioned to an authenticator that uses optional credentials cannot be provisioned to any additional authenticators." Credential mediation is available for messages with multiple credentials. In general, the multiple credential handling scenarios supported by the ACE XML Gateway include: •Mapping username/password credentials from an incoming request to credentials of type WSS UsernameToken, HTTP Basic Authentication, or SAML token in the outgoing request. •Mapping multiple WSS UsernameToken credential values to SAML assertions. Custom attributes of the UsernameToken element (that is, attributes not in the WSS namespace) can be mapped to attributes in generated SAML attribute statements as well. •Checking multiple SAML assertions, and either passing through or stripping out the assertions. •Mapping user attributes acquired from an LDAP lookup to multiple SAML assertions. For more information on credential mediation and setting up backend authentication, see Chapter 7, "Authenticating Requests to Backend Systems." Authentication in .NET In .NET, clients typically send their initial requests without authentication credentials. The client is expected to provide credentials if it receives back an HTTP 401 response with a WWW-Authenticate: Basic header. By default, the ACE XML Gateway includes this header in authorization error responses, so that .NET clients are prompted to supply credentials in a subsequent request. When configuring settings for .NET infrastructure in which HTTP Basic Authentication is required by the backend, be sure to configure credential passthrough on the service descriptor. To do so, in the Service Authentication configuration, choose the option Send Basic Auth header with username and password from consumer credential. For more information, see Chapter 7, "Authenticating Requests to Backend Systems." Working with Authenticators and Authorization Groups To define access conditions for services, you use a policy object called an authenticator. An authenticator contains access conditions based on one or more credential type. The conditions defined in an authenticator are applied to service access through another policy object called an authorization group. After creating the authenticator in an authorization group, you apply its requirements to a service by associating the authorization group with a virtual service. Figure 6-1 shows authenticators, authorization groups, and handlers as portrayed in the Access Control page. Figure 6-1 Authenticators, Authorization Group, and Handler Creating an Authenticator and Authorization Group The first step in setting up access control rules is creating the authenticator. To create an authenticator: Step 1 While logged in to the web console as an Administrator or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu. If there are any handlers or basic virtual services in the policy, they appear in the Access Control Browser (Figure 6-2). They are displayed by access status—either unprovisioned (which are inaccessible), publicly available, or assigned to an authorization group. Figure 6-2 Access Control Browser Step 2 Click the Add an Authenticator button. Step 3 In the Edit General Information page, type a name for the authenticator in the Authenticator Name field. It is important for the name to be distinctive, since this name is used in descriptions in the event and message traffic logs for successful access attempts. If associating an XML Security Public Key with the authenticator, you do not need to specify a name for the authenticator. Instead, log events and other activities associated with this authenticator can be identified by the Common Name (CN) in the client certificate validated for a given request. To associate an XML Security Public Key with the authenticator: a. Expand the Advanced Options control. b. Click the checkbox labeled Set the name of this authenticator to the CN from this Consumer Certificate. Note For more information, see "Using Per-Authenticator XML Security Public Keys" section. Step 4 Specify the authorization group in which the authenticator should be added. •To add the authenticator to an existing authorization group, choose the group from the Authorization Group menu. Keep in mind that requests that meet the conditions of this authenticator will be able to access the services to which the existing authorization group is associated. •To create a new authorization group to contain the authenticator, with Create in new authorization group named selected in the Authorization Group menu type the name of the new authorization group in the field next to the Authorization Group menu. Step 5 Click Create to add the authenticator to the working policy. By default, an authenticator with no access conditions blocks all requests. For information on adding access conditions, see "Specifying Credential Requirements" section. After adding access conditions, you can configure identity reporting features, as described in "Identity Reports" section. Deleting Authenticators and Authorization Groups An authorization group can only be deleted if it does not contain authenticators or references to virtual services. If it does, you need to remove these dependencies before attempting to delete the authorization group. In general, you can remove dependencies as follows: •To remove a relationship between an authorization group and a handler, click on the authorization group name, and in the table on the resulting page uncheck all the handlers that are provisioned to it. •To delete an authenticator, click on its name in the Access Control Browser and click the Delete This Authenticator button at the bottom of the page. •To delete an authorization group, click on the name of the authorization group in the Access Control Browser and click the Delete Authorization Group button at the bottom of the page. Changing an Authenticator's Authorization Group As described in "Creating an Authenticator and Authorization Group" section, when creating an authenticator you must specify the authorization group to which it belongs. The authorization group for an existing authenticator can be changed later as follows: Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu. Step 2 In the Access Control Browser, click the name of the authenticator to be configured. Step 3 In the Authenticator information page, click the Edit link in the General section of the page. Step 4 In the Authorization Group menu, choose a new authorization group for the authenticator. An authenticator can only be in one authorization group at a time, so adding it to a new group removes it from the previous one. Step 5 Click Save Changes to commit your changes to the working policy. Provisioning Services After creating an authenticator, you can enforce its conditions by associating it to virtual services (via an authorization group). There are several requirements for associating authenticators with virtual services: •The authenticator must only contain conditions for credential types that are supported by the protocol of the virtual service. For example, authenticators that require XML-based credentials, such as SAML, can only be assigned to services based on XML protocols, such as SOAP or HTTP Post Body. •If the credential is passed as a SOAP header (such as WSS UsernameToken or SAML token), SOAP header processing must be enabled in the virtual service. If not, a policy compilation error will prevent you from deploying the policy. To apply an authenticator to virtual services through an authorization group: Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu. Step 2 In the Access Control Browser, click the name of the handler or virtual service to provision. Step 3 Click the Access is restricted to the following authorization groups button. The checkboxes in the Allow Access column are enabled. Alternatively, you can specify unrestricted public access by clicking the Public button. To make the service inaccessible to consumers, click the No access button. Step 4 To impose the access conditions within an authorization group to a virtual service, click the checkbox for the authorization group. You can select as many authorization groups as desired. Step 5 Click Save Changes to commit the changes to the working policy. After you deploy the policy, only requests that meet the requirements of the authenticator can access the service. Specifying Credential Requirements An authenticator defines conditions for accessing a service. The ACE XML Gateway supports these types of access conditions: •IP Address Conditions •SSL/TLS Certificate Conditions •HTTP(S) Basic Authentication Conditions •WSS Username/Password Token Conditions •WSS Password Digest Conditions •SAML Token Conditions •XPath Password Conditions •Security Token Conditions •Time-of-Day Conditions A single authenticator can contain multiple conditions based upon different credential types. A request must meet all conditions in an authenticator to be accepted by the authenticator. In other words, the conditions in the authenticator are and'd. You can effect or'd conditions by using more than one authenticator with a service. In this case, a request needs to satisfy all conditions in only one of the authenticators to be accepted. You can supplement the built-in credential types in two ways: with pre-built extensions provided by Cisco and with extensions you create with the ACE XML Gateway SDK. Cisco extensions are separately distributed modules that extend the ACE XML Gateway to support additional types of credentials. Extensions exist for the following types: •Netegrity tokens (Netegrity SiteMinder and TransactionMinder) •Integrated Windows Authentication (Kerberos) Note For more information on the extensions published by Cisco, contact your Cisco support representative. For more information on creating extensions, see the Cisco ACE XML Gateway Developer Guide. An authenticator can have only one condition based upon IP address, time-of-day, or WSS Password Digest credentials. For other credential types, it can have multiple conditions for the same type. In effect, this allows you to test a single credential instance, such as a username/password combination, in multiple ways. (It is not intended to support checking multiple username/password combinations in a single request.) For example, you can have an authenticator test a password credential with LDAP bind in one condition and have it checked against an access control verifier extension in another. IP Address Conditions The IP address credential enables you to control access based on the IP address of the requester. You can specify that the requester must have a specific IP address or an address that falls within a range of acceptable addresses. To set up an IP address requirement: Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu. Step 2 Click on the authenticator in which you want to add the credential requirement, or create a new one as described in "Working with Authenticators and Authorization Groups" section. Step 3 Choose IP Address from the Add Credential menu and click Add. Step 4 Type the range of addresses that are to be accepted by the credential requirement in the text fields in dotted-decimal format. For example: 10.1.0.101 - 10.1.0.201 For a single address, type the same IP address in both fields. Step 5 Click the Add a New IP Address Row button to include additional, non-contiguous ranges. Step 6 Click Save Changes to commit the changes to the working policy. The new credential requirement appears in the Required Credentials area of the authenticator page. SSL/TLS Certificate Conditions With an SSL/TLS credential requirement, the ACE XML Gateway authenticates consumers based on X.509 client certificates submitted in requests. A client certificate can be validated in several ways. You can have the client certificate fingerprint compared to the fingerprint of a certificate stored in the policy, accepting the credential if the certificates match. You can verify the issuer of the certificate to ensure that it is a trusted Certificate Authority. You can also use a value from the certificate to retrieve user data from an LDAP directory. The values available include: •Subject DN •Subject Alternative Name •Subject Key Identifier •Certificate Fingerprint A portion of these values can be used as well, since the policy can apply a regular expression to a value before it is used in the LDAP query. Therefore, the CN can be extracted from the DN, for instance. If a record for the user is found, the returned data can be further evaluated to arrive at an authorization decision. To specify an SSL certificate requirement: Step 1 As an Administrator user or a Privileged user with the Access Control role in the console, click the Access Control Browser link in the navigation menu. Step 2 Click on the authenticator in which you want to add the credential requirement, or create a new one as described in "Working with Authenticators and Authorization Groups" section. Step 3 Choose SSL/TLS Certificate from the Add Credential menu and click Add. Step 4 In the SSL/TLS Certificate page, choose how you want the incoming SSL/TLS Certificate to be verified from the Verify Using menu, from these options: •SSL Certificate Fingerprint (see "Verifying by SSL Certificate Fingerprint" for details) •SSL Certificate Authority (see "Verifying by SSL Certificate Authority" for details) •Certificate-Based LDAP Query (see "Verifying by LDAP Query" for details) Step 5 If you want the certificate to be verified if present, but do not want to require requests to include a certificate, enable the option Verify only when a client certificate is present (allow requests without client certificates). Requests are blocked in this case only if they include a certificate that does not meet the configured criteria. Step 6 Click Save Changes to commit the changes to the working policy. The new credential requirement appears in the Required Credentials area of the authenticator page. You can add more than one certificate condition to an authenticator, all of which must be met by a request for the request to be accepted. Therefore, you can verify by fingerprint match, for example, as well as by certificate authority on single certificate in a request. Verifying by SSL Certificate Fingerprint A certificate in an incoming request can be verified by comparing its fingerprint to that of a consumer certificate that has already been loaded in the policy. If the fingerprints match, the request is accepted. For fingerprint matching to work properly, the CA that issued the certificate to be matched needs to be specified as a trusted CA in the policy. (During SSL negotiation, the ACE XML Gateway indicates to the client which CA's it will trust. Some types of clients do not send a certificate without this hint, which means that if the CA is not listed as a trusted CA, the client will never submit the certificate.) To require the client certificate to match one that has been uploaded into the policy: Step 1 Choose require a client certificate that is identical to this certificate. Step 2 Choose the certificate to be matched, uploading it if it is not already identified as a resource. If it is not already uploaded, upload the CA certificate for the issuer of the certificate for which you are configuring fingerprint matching. Verifying by SSL Certificate Authority You can choose to trust a certificate based on the identify of the Certificate Authority who issued the client certificate. To verify certificates by CA, the CA certificate must be loaded as a trusted CA certificate into the policy. By default, the ACE XML Gateway is not set up to trust any CA. You can specify CA's to be trusted in the trusted authority resource page. For more information, see "Uploading a Certificate Authority Resource" section on page 28-286. To require the client certificate be signed by a trusted CA: Step 1 Choose require a client certificate that is signed by. Step 2 Choose whether you want the certificate to be signed by any of the certificate authorities that are configured in the policy or the CA's you select. Step 3 Optionally, specify additional constraints for the certificate by choosing from these options: •Also require that the client certificate subject's Distinguished Name matches, to match the client certificate subject's DN against a regular expression you specify. •Also require that the client certificate issuer's Distinguished Name matches, to match the client certificate issuer's DN against a regular expression you specify. •Also require that the client certificate subject's Distinguished Name exactly matches this certificate, to require a match between the client certificate subject's DN and a certificate you choose. Verifying by LDAP Query The ACE XML Gateway supports LDAP as a verification mechanism for an SSL certificate subject. The condition can simply check that a record exists for a user in the directory or, as an additional check, evaluate a property of the user once the user's record is found. An LDAP certificate check should usually be used with an authenticator condition that checks the CA of the certificate or a fingerprint match, since by itself this check does not validate the authenticity or trustworthiness of the certificate. Also note that this type of verifier can be used to verify credentials if present, but not specifically require the credential in the request. In this way, this verifier is similar to multiple credential mode authenticators, such as multiple WSS UsernameToken and multiple SAML conditions, which do not require a credential, but verify the credentials if present. An LDAP record is matched to a certificate subject using an identifying property from the certificate. This implies that the LDAP directory includes a value from the user certificate as a user attribute, such as the fingerprint of the user's public key, subject alternative name, or subject key identifier. Alternatively, you can use the Subject DN of the certificate, and apply a regular-expression-based text replacement to the DN, so that it matches the form of a valid user record in the directory. The general steps for verifying certificates by LDAP are: •Step 1: Identify the LDAP directory to use. •Step 2: Specify the value from the certificate you want to be used to find the user record in the LDAP directory. •Step 3: Specify the filter to be executed in the LDAP directory. The query should return the data from a user record that can be used in the access decision, or simply the user record to check for a valid user account in the directory. •Step 4: Specify a regular expression that, when applied to the data returned by the filter, returns a result for a valid user. The procedures for verifying a client's SSL certificate by LDAP directory are detailed below. Example configuration values follow these steps. Step 1 Select Certificate-based LDAP Query in the Verify Using menu. Step 2 Choose the option Verify only when a client certificate is present if you want to validate the certificate if present in the request, but not specifically require that a credential be present. That is, requests without the credential will be accepted by this authenticator, but if included, the credential must be verifiable as specified by this authenticator. Step 3 From the Server menu, choose the LDAP server against which the credential will be verified. If the server you want to use does not appear in the list, click New LDAP Server and configure the connection to the LDAP directory. Step 4 In Certificate Field, choose the property of the client certificate that contains data to be used for verification. This will be the data bound to the %d variable, which is the system variable that identifies a user or application. Step 5 If the certificate field value cannot be used "as is" in the LDAP filter (as would usually be the case when using the Subject DN), the value needs to be converted to a form that matches the compared data in the LDAP directory. Enable this conversion by selecting the Apply regular expression substitution to the certificate field value option and entering a regular expression and substitution string. (If the certificate value does not need to be modified before the ACE XML Gateway runs the query, you can leave the regular expression option disabled.) With this option selected, the regular expression is applied to the certificate property you choose, with the resulting data being used to populate the %d variable. Data matched by the regular expression is available as backslash variables, which have the form "\1" and "\2" (which would be the first and second regular expression matches from the source value). The result should be a DN in the form suitable for comparison with the LDAP data. To apply a regular expression to the source value: a. Select the Apply regular expression substitution to the certificate field value checkbox. b. Enter the regular expression to use in the Regex field. The regular expression should match the portion of the field you want to use in the LDAP query. c. In the Replace With field, use static text and back-reference variables to compose the source comparison value. For an example, see the discussion following these steps. If the regular expression does not produce a match against the property value, the property value is not changed. To help you troubleshoot composition of the regular expression, the event log shows the results of the regular expression comparison, whether a match and replacement occurred or no data was matched. Step 6 In the User DN and Bind with Password fields, specify credentials the ACE XML Gateway should use to log onto the LDAP directory to verify the user. This should be the user DN and password of a known-good user account with query permissions in the directory. It is recommended that you create a dedicated user account in the directory for the ACE XML Gateway to use for this purpose. Step 7 In the Base DN field, specify the location of the directory in which you want the query filter to be applied. In most cases, this should be %d, which will have the value specified in the Client Certificate Settings (often the Subject DN of the certificate after processing by the Regex and Replace With result). Step 8 In Filter, enter an LDAP query to be executed at the Base DN. This could be a record under the one identified by the Base DN, or if the Base DN identifies the user record to be evaluated, it may be a filter that simply passes through the result (that is, a no-op filter), such as {{{(objectClass=)}}}. This would return the entire record for the Base DN. Step 9* Optionally, use the Attributes field to reduce the information returned by the filter to the value of specific LDAP attributes. This can simplify the Match Regex needed to validate the results. For example, to use the e-mail addresses of sales people and no other data, enter mail in the Attributes field. This returns only the list of mail attributes for each record returned by the query. You can specify more than one attribute to get multiple values. Use spaces to separate multiple attribute names. The attribute results are available for populating SAML credentials generated for outgoing requests (enabled in the SAML generation page with the option labelled Include LDAP records, if available, as SAML Attribute Statements). Step 10 In the Match Regex field, enter a regular expression to be run against the attribute result or filter result, if no attribute is specified. This expression can test an attribute of the user record that has been returned, such as group membership. If applying the regular expression produces a match, the authentication/authorization is considered successful. Step 11 Click Save Changes to commit your changes to the working policy. For example, given an LDAP directory that contains the fingerprint of each user's certificate in an attribute called certFingerprint, you could set up verification settings as follows: •Certificate field: Certificate Fingerprint (SHA-1) •Regular expression substitution: disabled •Base DN: dc=cisco,dc=com •Filter: (certFingerprint=%d) The certificate field value used is the certificate fingerprint, which populates the %d variable. The filter checks this value against the certFingerprint. If the certFingerprint in the directory matches %d, the filter is satisfied and this condition met. If using the Subject DN as the match value, it is important to understand how the ACE XML Gateway renders the DN. When the ACE XML Gateway processes a certificate, it creates a string representation of the certificate's Subject DN. Before starting, you should send a request with the certificate to the ACE XML Gateway with debug-level logging enabled. The normalized DN in the certificate will appear in the event log. This is the value against which your regular expression will run. For example, a request that contains the certificate from the sample certificate, beagle.cer, produces an entry with the following description: DN of client certificate subject is emailAddress=operations@beaglepartners.com,CN=Beagle Partners Inc.,OU=Operations,O=Beagle Partners Inc.,L=Hampton,ST=Virginia,C=US This is the value against which the regular expression would be run. Accordingly, the regular expression needs to be designed with this DN format in mind. For example, to covert this source Subject DN into the following value: CN=Beagle Partners Inc.,OU=Operations,O=Beagle Partners Inc.,ST=Virginia Would require a regular expression of: emailAddress=[^,],CN=([^,]),OU=([^,]), O=([^,]),L=[^,],ST=([^,]),. The emailAddress is ignored (since the regular expression not parenthesized). The next steps of the expression put the value after CN= into the variable \1, the value after OU= into \2, and so on. The L value is, like the email address, ignored. The Replace With value would be: CN=\1, OU=\2, O=\3, ST=\4 Figure 6-3 shows this sample configuration. Figure 6-3 Regular expression configuration HTTP(S) Basic Authentication Conditions Authenticator can be configured to evaluate HTTP Basic Authorization credentials. In this type of credential, username/password credentials are passed in the header of the message. To require an HTTP Basic Authorization credential: Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu. Step 2 Click on the authenticator in which you want to add the requirement or create a new one as described in "Working with Authenticators and Authorization Groups" section. Step 3 Choose HTTP(S) Basic Authentication from the Add Credential menu and click Add. Step 4 Choose how you want the credential to be verified by choosing it from the Verify Using menu. For more information, see "Verifying Password-Based Credentials" section. Step 5 Click Save Changes to commit the changes to the working policy. The new credential requirement appears in the Required Credentials area of the authenticator page. WSS Username/Password Token Conditions WSS UsernameToken is an authentication mechanism defined in WS-Security specification "Web Services Security UsernameToken Profile 1.0." This type of token appears in the SOAP header portion of a SOAP envelope, as shown in the example token in Example 6-1. Example 6-1 WSS UsernameToken credential ... <soap:Header xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"> <wsse:Security> <wsse:UsernameToken> <wsse:Username>username</wsse:Username> <wsse:Password Type="wsse:PasswordText">password</wsse:Password> </wsse:UsernameToken> </wsse:Security> ... WSS Username credentials are available as source credentials for credential mediation. That is, the username/password values from an incoming request can be used to generate a basic auth or SAML token in the outgoing request. Further, any custom WSS Username attributes in the WSS Username element can be mapped to attributes in generated SAML AttributeStatements. To enable this option, configure the mapping option labeled Send extension attributes from WSS UsernameTokens as attributes in generated SAML AttributeStatements on the System Management > Gateway Settings page. A request can contain more than one WSS UsernameToken, each of which can represent a participant in generating the request. For example, a request may have one credential for the end user who generated the request and another for the application used. You can configure an authenticator to qualify multiple credentials in a request. To qualify multiple credentials, enable multiple credential mode in the WSS UsernameToken authenticator. The configuration needs to specify the number of credentials that the ACE XML Gateway should expect in the message. This is the number of credentials checked and available for credential generation. If a request contains more than this number, the additional credentials are ignored. Once the multiple credential mode is enabled, you can add additional conditions based on the WSS UsernameToken credential. If you only specify one condition, all credentials need to meet that condition. In this case, the condition would probably use a verification mechanism that can verify multiple identities, such as LDAP query. If you specify two conditions, on the other hand, a request with two credentials that meet just one of the conditions will be accepted. In other words, all credentials in the request must meet all conditions of at least one authenticator to be accepted. It is important to note that multiple credential mode does not require a credential to be present. If a request does not contain a credential, it will be accepted by the authenticator. This can have the effect of making the service associated with this type of authenticator publicly accessible. You should use this mode only to process and validate credentials, if present, but not to enforce minimum credential requirements. Also note that any virtual service to which this authenticator is applied must have SOAP header processing enabled. To set up a WSS UsernameToken requirement in an authenticator: Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu. Step 2 Click on the authenticator in which you want to add the credential requirement, or create a new one as described in "Working with Authenticators and Authorization Groups" section. Step 3 Choose WSS Username/Password from the Add Credential menu and click Add. Step 4 To enable multiple credential validation, follow these steps: a. Click the configure multiple WSS UsernameToken mode link. b. Select the Enable multiple WSS UsernameToken mode, verifying at most option, and specify the number of tokens expected in the message in the verifying at most field. The ACE XML Gateway will process the number of tokens you specify. If the message has additional credentials, they are ignored. With this option enabled, the ACE XML Gateway will always check for at least one credential, even if 0 or a negative number is specified as the number of tokens per message to be verified. c. Click Save Changes in the Multiple WSS UsernameToken Mode page. You can now add multiple conditions for WSS UsernameToken credentials to the authenticator. Step 5 In the authenticator page, again add a WSS UsernameToken requirement. Step 6 Use the Verify using menu to specify how the username and password values are to be verified. For more information, see "Verifying Password-Based Credentials" section. Step 7 Click Save Changes. Since WSS username/password credentials are passed in the header of the message, you must enable SOAP header processing on all message handlers to be associated with the authenticator. Step 8 If SOAP header processing is not already enabled, in the Virtual Services browser, click the name of the handler or virtual service that uses the authenticator. Step 9 In the Request Processing area of the page, click the edit link next to SOAP Header Processing. Step 10 If it is not already enabled, check the Process header elements for SOAP role check box. If not configuring other header processing tasks, you can retain the default values for the other settings. Step 11 Click Save Changes to commit the changes to the working policy. WSS Username/Password credential checking is now enabled. Deploy the policy to have the ACE XML Gateway enforce this change. WSS Password Digest Conditions By default, the WSS Username/Password credential described in the previous section resides in the message header unencrypted. Assuming transport-level encryption is used to secure the message as it crosses the network, the password nevertheless is unprotected once it arrives at its destination. For more security, you can encrypt the credential through the use of WSS Password Digest. WSS Password Digest encrypts the password value, making it secure at the endpoint as well as in transit. Note In addition to password encryption, WSS Password Digest is intended to prevent replay attacks through the use of a nonce, an arbitrary value that must be unique across requests. However, nonce values are not retained at the ACE XML Gateway, so nonce uniqueness is not enforced. Also note that the ACE XML Gateway does not check digest expiration. In a SOAP envelope header, a password digest looks as follows: Example 6-2 WS Security Password Digest credential ... <soap:Header> <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/ oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/ oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsse:UsernameToken> <wsse:Username>jdoe</wsse:Username> <wsse:Password>Ikky9DZH7lZ52JGDaZDys8ALbbM=</wsse:Password> <wsse:Nonce>MQ==</wsse:Nonce> <wsu:Created>2006-02-13T15:43:46Z</wsu:Created> </wsse:UsernameToken> </wsse:Security> </soap:Header> ... Notice the values of the Password and Nonce elements in the header. As indicated by the WS-Security specification, the password token is generated by combining and encrypting (SHA1) the concatenated, Base64-encoded nonce, timestamp, and password. To evaluate a token, therefore, the ACE XML Gateway applies Base64 decoding of the Password from the message, producing a hexadecimal result. It then decodes the Nonce and combines it with the timestamp in the message and password (stored in the authenticator configuration). It then applies SHA1 encryption to the concatenated result. The hexadecimal results are compared to the decoded digest value. If they match, the request is validated. To get a WSS Password Digest credential requirement, a virtual service must be configured for SOAP header processing. The settings for enabling SOAP header processing are in the Request and Response processing settings for the virtual service. To set up a WSS Password Digest credential requirement: Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu. Step 2 Click on the authenticator in which you want to add the credential requirement, or create a new one as described in "Working with Authenticators and Authorization Groups" section. Step 3 Choose WSS Password Digest from the Add Credential menu and click Add. Step 4 Type the username and password values to be accepted in the appropriate fields and click Save Changes. The password should be the un-encoded password value, that is, the one used to generate the digest password by the client. Step 5 Since WSS username/password credentials are passed in the header of the message, SOAP header processing must be enabled for handlers associated with the authenticator. If it is not already enabled, enable header processing as follows: a. In the Virtual Services browser, click the name of the handler or virtual service that uses the authenticator. The message specification settings for the service handler appear. b. In the Request Processing area of the page, click the edit link next to SOAP Header Processing. c. If it is not already selected, click the checkbox next to Process header elements for SOAP role. If no other header processing tasks are required, the remaining settings can remain at their default values. Step 6 Click Save Changes to commit the changes to the working policy. WSS Password Digest credential checking is now enabled. To make the ACE XML Gateway enforce this change, deploy the policy. SAML Token Conditions SAML (Security Assertion Markup Language) is an XML-based protocol for exchanging security information. SAML is intended to provide single sign-on capabilities across organizational boundaries. A SAML credential takes the form of a token element in the WS-Security header block of a message. The ACE XML Gateway can act as a relying party or asserting party for SAML credentials. That is, you can configure authenticator conditions based upon SAML assertions or add assertions to outgoing messages. The ACE XML Gateway supports SAML versions 1.0, 1.1, and 2.0. For a SAML assertion to be trusted by the ACE XML Gateway, its integrity must be ensured either by XML Signature or through SSL encryption of the connection between the consumer and Gateway. Thus, for an SSL requirement, the virtual service must be configured to use an SSL-secured port. As with other types of credential requirements, a SAML requirement is specified in an authenticator. You can set up an authenticator to require a single SAML token or multiple tokens in an incoming request. By default, the SAML tokens are consumed by the ACE XML Gateway, meaning they are taken out of the request after validation. To configure passthrough, specify backend service authentication for the service interface definition. A SAML condition must require at least one of the following elements in the SAML assertion: •authentication statement •authorization decision statement •attribute statement The authenticator can specify various properties the element needs to have to be accepted. For example, it may require the assertion to have an authentication statement that indicates the subject was authenticated by password. Timestamp conditions in SAML assertions are automatically validated by the ACE XML Gateway. NotBefore and NotOnOrAfter conditions, for example, are checked for conflict against the ACE XML Gateway's internal system clock and, if invalid, cause the assertion to be rejected. Note The ACE XML Gateway can cache SAML assertion validation results, avoiding the performance burden of validating identical assertions. Enable SAML assertion caching from the System Management > Gateway Settings page. SAML Assertion Caching settings appear near the bottom of the page. To configure a SAML token requirement: Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu. Step 2 Click on the authenticator for which you want to add the SAML credential requirement or create a new one as described in "Working with Authenticators and Authorization Groups" section. Step 3 From the Add Credential menu, choose SAML Token and click Add. Step 4 In Verify Using menu, choose the SAML version of the credential to be authenticated: •SAML 1.0 •SAML 1.1 •SAML 2.0 Your selection affects the options available on the page, reflecting the differences between SAML versions. Use the options to specify the characteristics of the assertion this authenticator requires. Step 5 A request can contain multiple SAML assertions. Choose whether this condition should apply to a specific number of credentials in the request or to all credentials by choosing from: •At least allows you to specify a minimum number of required credentials in the request which must meet this condition. If a request has fewer valid assertions than the configured amount, it is blocked. •All specifies that all assertions in the request must meet this condition. Important to note is that all does not require a minimum number of credentials in the request. If a request does not contain a SAML assertion, it will be accepted by the authenticator. This can have the effect of making the service associated with this type of authenticator publicly accessible. You should use this mode only if you want to process and validate credentials, if present, but not to enforce minimum credential requirements. Step 6 If appropriate for the SAML assertions to be accepted, specify Audience conditions as follows: a. Select the checkbox labelled Require an Audience Condition that matches any one of the following. b. In the entry field beneath the Require an Audience Condition checkbox, type the audience URI required for the assertion. c. Add requirements for additional Audience conditions if needed. A message can contain multiple Audience elements, any of which can be required by an authenticator. If an assertion includes Audience elements not specifically required by the authenticator, the elements are ignored. Step 7 The Subject of an assertion refers to the user, application, or other party for whom the assertion attests. Optionally, you can specify requirements for the Subject by setting a NameIdentifier requirement: a. Click the NameIdentifier is button. b. In the field next to NameIdentifier is, type the subject NameIdentifier value that the authenticator is to require. c. If needed, qualify the NameIdentifier value with an administrative or security domain by selecting the with NameQualifier checkbox and typing the NameQualifier value in the text field. A name qualifier specifies an administrative or security domain. It provides a means of federating names from disparate user stores to avoid collisions. d. Specify the format of the NameIdentifier value by choosing the with Format checkbox and choosing an option from the with Format menu. The options vary by SAML version, but in general they are: –#emailAddress requires the NameIdentifier value to be in the local-part@domain format of an email address as specified by "addr-spec" in IETF RFC 2822, such as: <NameIdentifier Format="urn:oasis:names:tc: SAML:1.0:assertion#emailAddress"> jdoe@example.com </NameIdentifier> –#X509SubjectName requires the NameIdentifier to be in the form of an X.509 Subject DN. –#WindowsDomainQualifiedName requires the NameIdentifier value to be in the DomainName\UserName format of a domain-qualified user name for the Microsoft Windows™ platform. Optionally, the domain name and "\" separator may be omitted. To ignore the NameIdentifier element, click the Ignore the NameIdentifier value button. Step 8 The Subject Confirmation settings control how the integrity of the assertion is to be evaluated by the ACE XML Gateway. To configure how the Subject is confirmed: •Choose the confirmation method to be accepted in incoming assertions from: –Sender Vouches allows the "sender vouches" confirmation method. The sender vouches confirmation method implies that the relying party (the ACE XML Gateway in this case) has an existing trust relationship with the sender or that the backend service does not require a more stringent requirement level than that implied by sender vouches. –Holder-of-key means that the subject may be authenticated by the holder-of-key confirmation method, in which key information is passed in the element SubjectConfirmationData. The ACE XML Gateway verifies the referenced key against the SSL/TLS certificate requirement for the authenticator. –Artifact directs the Gateway to extract from the message a SAML artifact that it can use to verify the identity of the sender. –Bearer (for SAML 1.1) specifies that the subject of the assertion may confirm itself, subject to any optional constraints on the confirmation that are specified in the SubjectConfirmationData element. The URI prefixes for the methods are: –urn:oasis:names:tc:SAML:1.0:cm applies to sender-vouches, holder-of-key, artifact, and bearer –urn:oasis:names:tc:SAML:2.0:cm applies to sender-vouches, holder-of-key, artifact, bearer For example, an incoming message would indicate holder-of-key as follows: <SubjectConfirmation Method="urn:oasis:names: tc:SAML:1.0:cm:holder-of-key"> <SubjectConfirmationData> ... </SubjectConfirmationData> </SubjectConfirmation Method> •To specify the method by which the message integrity is ensured, choose an item from the Integrity Protection menu: –SSL (HTTPS) means that the connection used to make the request must be secured by SSL. Note For increased security, configure the authenticator to test SSL/TLS credentials (see "SSL/TLS Certificate Conditions" section) if you choose this confirmation method. –XML Signature means that the message must supply a public key that the authenticator can use to verify the signed elements of the message. Step 9 Choose a Subject Statement the assertion must have. You must require at least one subject statement: •Require an Authentication Statement. Select this option to require an authentication statement, of any type or one that indicates a particular authentication method. If you specify an authentication method, the assertion needs to reflect that authentication method. If it does not, the message is rejected. The following methods are available: –Password method indicates that a password was used to authenticate the subject. If another authentication method was used, the authenticator rejects the message. –Kerberos requires that Kerberos was used to authenticate the subject. –Secure Remote Password requires that the Secure Remote Password protocol was used to authenticate the subject (see RFC 2945). –Hardware Token requires that a hardware token was used to authenticate the subject. –SSL/TLS Certificate requires that either of the SSL or TLS protocols was used to perform certificate-based client authentication. –X.509 Public Key requires that a mechanism based on an X.509 public key was used to authenticate the subject. –PGP Public Key requires that a mechanism based on a key authenticated by means of a PGP web of trust was used to authenticate the subject. –SPKI Public Key requires that a mechanism based on SPKI public key infrastructure was used to authenticate the subject. –XKMS Public Key requires that a mechanism based on an XKMS trust service was used to authenticate the subject. –XML Digital Signature requires that an XML digital signature was used to authenticate the subject. –Unspecified can be used if the assertion may indicate "unspecified" as the confirmation method. •Click the Require an Authorization Decision Statement that permits access to option to specify a statement based on an authorization decision statement that permits access to a specified resource. •To require attribute statements in assertions, click the Require Attribute Statement(s) checkbox and specify attribute requirements using these fields: –Attribute Name is the name of the required attribute. –Attribute Namespace is the namespace in which the AttributeName element is interpreted. –Attribute Value field is a text value of the attribute. Step 10 Click Save Changes to commit your changes to the working policy. Once the policy is deployed, the authenticator rejects messages that do not meet all of the attribute statement criteria you specify. XPath Password Conditions The XPath Password credential is one of several types of password-based credentials in the ACE XML Gateway. It is verified by one of the mechanisms described in "Verifying Password-Based Credentials" section. An XPath password credential requirement tests two values at a location identified by XPath in the message. For mediation and identity tracking purposes, the values are interpreted as username and password values. Note XPath password checking does not work for incoming messages that are encrypted. Since this type of credential check occurs before messages are decrypted, the requirement cannot be satisfied by an encrypted message. To set up an XPath username/password authentication requirement: Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu. Step 2 Click on the authenticator for which you want to specify an access condition or create a new one. Step 3 From the Add Credential menu, choose XPath Password and click Add. Step 4 Type the location where the credentials are expected to appear in the body of the message by XPath expression. For example, a username at the following location of an incoming XML message: //Envelope/Body/retrieveQuote/user Can be extracted with the following XPath expression: //[local-name()='Envelope']/[local-name()= 'Body']/[local-name()='retrieveQuote']/ [local-name()='user']/text() Note The local-name() function is a standard XPath function that lets you avoid having to qualify each element name by namespace. Step 5 The ACE XML Gateway will extract username and password values for the location identified by the XPath. Configure how you want to have the values verified by choosing the appropriate method from the Verify Using menu. Step 6 Click Save Changes to commit the changes to the working policy. The new credential requirement appears in the Required Credentials area of the authenticator page. Security Token Conditions A security token is a single-part value from either the HTTP header, GET or POST argument, or a portion of the message identified by XPath. You can configure authentication based on the token value. The requirement can verify the token by regular expression or by an external SOAP service. Note Security token checking does not work for incoming messages that are encrypted. Since this type of credential check occurs before messages are decrypted, the requirement cannot be satisfied by an encrypted message. In verifying a token by SOAP service, the ACE XML Gateway sends the token to the service in the form of a SOAP request and expects an access decision in the response. If the term "Permit" (case-sensitive) appears as the content of the first element under the SOAP body element of the response, the user is considered accepted by this condition. If "Permit" does not appear at this location of the response, the request is considered to be rejected. The ACE XML Gateway generates the access decision request based on the configuration for the requirement. The request can include information on the consumer request, such as the service requested, which can be used to inform the decision. A sample request appears as follows: Example 6-3 Sample SOAP authentication request (line breaks added for readability) <?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soap:Body soap:encodingStyle= "http://schemas.xmlsoap.org/soap/encoding/"> <authService> <token xsi:type="xsd:string">[tokenvalue]</token> <path xsi:type="xsd:string">/service/order.asmx</path> <action xsi:type="xsd:string"> "http://oakinsurance.com/order/retrieveQuote" </action> <method xsi:type="xsd:string">retrieveQuote</method> <methodns xsi:type="xsd:string"> http://oakinsurance.com/order/ </methodns> </authService> </soap:Body> </soap:Envelope> In the sample request: •authService is the Method value in the authenticator condition configuration. •token is the value extracted at the XPath (or HTTP header) of the consumer request. •path is the path on the ACE XML Gateway for the service requested by the consumer. •action is the SOAPAction in the original consumer request. •method is the service method requested in the original consumer request. •methoddns is the method name space in the original request. The service that receives the request can use these values in any way desired to make an access decision. From the ACE XML Gateway's point-of-view, it must simply return a response in the expected form. A suggested structure for the response is described in the WSDL file available for downloading from the security token configuration page in the ACE XML Manager. A positive response from the service to the Gateway must contain the word "Permit" as the content of the first subelement of the first element under the SOAP Body. The ACE XML Gateway will block the consumer request otherwise. For example, the ACE XML Gateway would interpret the following as a positive response. Example 6-4 Access Permitted <?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <AuthenticationService> <response>Permit</response> </AuthenticationService> </soap:Body> </soap:Envelope> In this case, "Permit" appears in an element named response. However, the element name is unimportant to the ACE XML Gateway; it may be named anything, as may the decision element's parent element. What is important is that "Permit" appears in the content of the first element below the first SOAP Body subelement of a positive response. Any other text will result in the consumer's request being blocked. The ACE XML Gateway locates the decision in the response with the following XPath: /[local-name()='Envelope']/[local-name()='Body']/[1]/[1]/text() The following also indicates a positive decision. Example 6-5 Access Permitted by myAuthService <?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <myAuthService> <decision>Permit</decision> </myAuthService> </soap:Body> </soap:Envelope> To configure a security token requirement: Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu. Step 2 Click on the authenticator for which you want to specify an access condition or create a new one. Step 3 Choose Security Token from the Add Credential menu and click Add. Step 4 Identify the source of the token, from these options: •HTTP argument. An HTTP argument value drawn from the query string of a GET request or the body of a form POST (where the content is of type application/x-www-form-urlencoded). •HTTP header. The value of an HTTP header in the message. •XPath expression. Any content from the message identified by XPath expression. Step 5 Choose how the token is to be verified, using either: •a regular expression •an external service Step 6 To use an external service, follow these steps: a. Choose SOAP Callout from the Verify Using menu. b. Enter the values for the authorization service: –Service Host is the host name of the machine that hosts the authorization service. –Port is the port on which the service host listens for authorization requests. –Path is the path of the authorization service on the host. –SOAPAction is the SOAPAction value to use in the request. c. Enter the name of the method that performs the authorization and a method namespace. d. If desired, have SOAP arguments namespace-qualified (for Document-style services) and enable response caching. Step 7 Click Save Changes. The new credential requirement appears in the Required Credentials area of the authenticator page. When needed, you can have the WSDL generated for the authorization service by clicking the Show WSDL for this Authorization Service button. By generating service code from this WSDL in an IDE, you can quickly create the skeleton code for an authorization service. Time-of-Day Conditions Making a service available only during the normal business hours of its expected audience can contribute to the security of backend systems. The ACE XML Gateway system allows you to specify an authenticator requirement based on the time of day. The system uses its internal system clock to evaluate requests. Requests outside permitted times are rejected by the authenticator. To set up a time-based check: Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu. Step 2 Click on the authenticator for which you want to specify an access condition or create a new one. Step 3 Choose Time-of-Day from the Add Credential menu and click Add. Step 4 In the Time-of-Day edit page, click the accept the message only during button. Step 5 In the From and To fields, enter the time range in which you want the authenticator to accept messages as Greenwich Mean Time (GMT). The range must be in GMT even if the Manager web console is set to display times using another time zone. This value must be in the form NN:NN, in which N is a whole number greater than 1 and less than 12. Step 6 From the menu next to the From field, choose AM or PM. Step 7 In the To field, type the hour of the day at which to stop accepting messages. This value must be of the form NN:NN, in which N is a whole number greater than 1 and less than 12. It must be Greenwich Mean Time (GMT), even if the Manager web console displays a different time zone. Step 8 From the pull-down menu next to the To field, choose AM or PM. Step 9 To specify the days of the week on which to accept messages, click one or more checkboxes to represent the days on which to accept messages. Step 10 Click Save Changes to commit the changes to the working policy. The Time-of-day credential condition appears in the Authenticator settings. Deploy your changes to have them take effect at the ACE XML Gateway. Verifying Password-Based Credentials Several credential types in the ACE XML Gateway are based on passwords. These include HTTP Basic Authentication, WSS Username/Password, and XPath Password. In addition, custom credentials created through the ACE XML Gateway SDK can extend the generic username/password credential type. Password-based credentials can be verified with the following verification mechanisms: •fixed values stored in the policy •a password file •an Active Directory^® server •an LDAP server A fixed value is an explicitly set username/password combination in the authenticator that the consumers' credentials must match. A password file is an Apache-style htpasswd file that contains the username and password combinations to be accepted. To be available in the credential interface, the file must first be uploaded as a resource in the ACE XML Manager. To upload the file, click the Password Files link in the navigation menu and from there add a password file as indicated by the ACE XML Manager interface. For Active Directory and LDAP verification, several modes of verification are available. These modes and the steps for setting them up are described in the following sections. Verifying Credentials with Active Directory LDAP Query The ACE XML Gateway supports Active Directory directory service as a verification mechanism for password-based credentials passed in service requests. The ACE XML Gateway can verify user credentials with Active Directory in two ways: •The ACE XML Gateway can try to bind to the Active Directory server with the user's DN and password passed in the request. Success indicates that the credentials match a directory account. •In addition to the bind attempt, the ACE XML Gateway can check the user's memberOf attributes for a particular value. For verification to work, the username passed in the service request must be either the DN of the Active Directory user account or a value that can be mapped to the DN through another attribute (such as a sAMAccountName or mail attribute). In practice, it's unlikely that usernames in service requests will be identical to the DN of accounts in the Active Directory server (such as cn=Joe User,cn=Users,dc=Cisco,dc=Com). But if the username does map to another user attribute, such as sAMAccountName, you can configure a mapping query that enables the ACE XML Gateway to retrieve the DN prior to the bind attempt. To issue the mapping query, the ACE XML Gateway first binds to the Active Directory server with a known-valid account. It is recommended that you create a dedicated account in the Active Directory server specifically for the ACE XML Gateway. Figure 6-4 illustrates the interaction between the ACE XML Gateway and the Active Directory server if verification is configured in this three-step process. In the sequence shown, verification is successful. A failure at any point, such as the inability to match an attribute for the mapping query, would of course abbreviate the process. Figure 6-4 Active Directory Verification Sequence Configuring Active Directory LDAP Query Verification To configure username/password credential verification with an Active Directory server: Step 1 After setting up an authenticator condition for one of the password credential types (such as HTTP Basic Authentication, WSS Username, or XPath password), choose the Active Directory Query option from the Verify Using menu. Step 2 Choose the Active Directory server to verify user credentials from the Server menu. If the directory you want to use appears in the Server menu, choose it from the list. If not, click the New LDAP Server button and configure a connection to the Active Directory server. Step 3 In the simplest verification mode you can configure, the ACE XML Gateway simply attempts to log in with the username and password supplied in the request. To use this method, choose the option labeled No lookup; use credential username as the full user DN. Note that the username supplied in the service request must be a full DN that can be used to bind to the Active Directory server. Step 4 If the usernames supplied in service requests do not directly correspond to DN's in the directory but would match another attribute of the user, you can use a username-mapping query to acquire the user's DN, which is then used in a bind attempt. To set up a mapping query: a. Select the Map credential username to option. b. From the menu, choose the attribute whose value will match the username of a valid user. The most likely attribute options are preconfigured, and include mail, sAMAccountName, and userPrincipalName. However, you can select other LDAP attribute and specify any attribute name desired. The ACE XML Gateway creates a filter based on your choice, such as (sAMAccountName=juser). c. Specify valid credentials for the ACE XML Gateway to use to bind to the directory to perform the query. From the Bind menu, choose: –anonymously if the directory accepts anonymous binds and the anonymous account is configured with privileges that enable finding user records. –with DN specified to have the ACE XML Gateway bind with a specific account. In this case, enter a valid distinguished name in the Bind with DN field and its password. Note It is recommended that you create a dedicated account in the directory for the ACE XML Gateway to use for this purpose. If you have done so, enter the DN and password for the ACE XML Gateway's account. d. In the Base DN field, enter the "folder" that contains the user accounts you want to query. A sample value would be something like: cn=Users,dc=Cisco,dc=Com Step 5 Optionally, further qualify authenticated users by checking their memberOf attribute for a particular value. To do so, click the checkbox labeled Verify that user is a member of a group with name and type the value of the memberOf attribute that qualifies the user for the authenticator. Step 6 The Error Handling option allows a client to get an extended error code received from the LDAP system. The option is introduced for the following types of authenticators: ·Active Directory LDAP Query ·LDAP Bind Success ·LDAP Query In order to add the LDAP error code to the response the exception mapping must be configured. The %s should be added to the Message Body field for "Authentication or authorization failure". For more information, see "Configuring Global Exceptions" section on page 22-212. Step 7 Click Save Changes to commit changes to the working policy. The credential condition appears in the authenticator settings. Deploy your changes to have them take effect at the ACE XML Gateway. Verifying Credentials with LDAP The steps for verifying password-based credentials with an LDAP server are similar to those described for Active Directory verification in "Verifying Credentials with Active Directory LDAP Query" section. As for Active Directory verification, the ACE XML Gateway can verify credentials for LDAP through several methods: •In the simplest case, the ACE XML Gateway attempts to bind to the LDAP server with the username and password in the request. If the bind attempt succeeds, the request is considered to meet this condition. •With or without a bind attempt, the ACE XML Gateway can query the directory for the value of a particular user attribute. In the bind attempt, the ACE XML Gateway can submit as the username a DN you specify or a DN acquired through a setup query. The setup query maps the user identifier from a service request (such as jdoe2) to the distinguished name (DN) used in the LDAP server (such as cn=Jane Doe, cn=Users, dc=Cisco, dc=com). Using LDAP Bind Password Verification In the simplest password verification mode with LDAP, the ACE XML Gateway simply attempts to log in with the DN of the user and password supplied in the request. In most cases, the usernames passed in requests will not directly match the form of user DN's in the LDAP directory. Therefore, the username passed in the request must be mapped to a DN somehow. You can do this in several ways: •If the username corresponds to another user attribute (such as a userPrincipalName), you can have the ACE XML Gateway acquire the DN by issuing a Setup Query that searches for the attribute, getting back (if found) the full LDAP name of the matching record. •If username values in requests will reliably match a portion of the DN, such as its common name (cn), you can avoid a setup query by specifying a "parameterized" DN. The value of the username from the request can be added to the DN as a substitution variable, such as: cn=%u,cn=Users,dc=Cisco,dc=Com At runtime, %u will be replaced with the username from the request. The following steps describe how to configure LDAP bind verification with and without a setup query: Step 1 In the authenticator condition for a password credential type (such as HTTP Basic Authentication or WSS Username), choose LDAP Bind Success from the Verify Using menu. The Server, Setup Query, and Bind settings appear. Step 2 If the connection to the LDAP server you want to use is already defined in the policy, choose it from the Server menu. If it is not yet defined, click the New LDAP Server button and configure the connection to the LDAP server. Step 3 To have the ACE XML Gateway use a setup query to acquire the DN with which to make the bind attempt, perform these steps: a. Click the checkbox labelled Perform setup query, storing result DN in substitution variable %d. b. Specify how the ACE XML Gateway will bind to the directory to perform the setup query by choosing from the Bind menu: –anonymously if the directory supports anonymous access and the account has privileges to find the user records. –with DN specified to have the ACE XML Gateway bind with a specific account. Enter a valid distinguished name in the User DN field and its password. Note It is recommended that you create a dedicated account in the directory for the ACE XML Gateway to use for this purpose. If you have done so, enter the DN and password for the ACE XML Gateway's account. c. In the Base DN field, enter the "folder" that contains the user accounts you want to query. A sample value would be something like: cn=Users,dc=Cisco,dc=Com If you have a very complicated Active Directory instance with multiple trees and forests, you will probably have to use an LDAP browser to figure out the correct DN to use. d. In the Filter field, specify the LDAP filter expression that tests a particular user property, with the goal of matching the account of the user who submitted the service request. This mapping is aided by the %u variable, which contains the value of the username from the request. For example: (\|(cn=%u)(uid=%u)) If the value of a cn or uid property under the specified base DN matches the username from the request, the ACE XML Gateway gets back the full DN of the matched record. The DN gets populated into the %d variable, which is subsequently available to the ACE XML Gateway in its bind-as-user attempt. Step 4 In the Bind settings, configure the username the ACE XML Gateway will use to bind to the directory with the password from the request: •If you have configured a setup query, you would most likely enter %d in this field (the variable populated with the full DN from the setup query). •If not using a setup query, configure a parameterized DN. For example: cn=%u,cn=Users,dc=Cisco,dc=Com The %u variable will be replaced with the username from the request. Step 5 Click Save Changes to commit your settings to the working policy. The password requirement should appear in the authenticator page with LDAP Bind Request listed as the verification method. Using LDAP Query Password Verification In the query mode of LDAP password verification, the ACE XML Gateway queries the LDAP directory for records matching a specified filter, checks the results with a regular expression, and makes an access decision based on the results. To perform the query, the ACE XML Gateway may optionally bind to the directory with the user credentials. This has the effect of validating the password supplied in the request. If you do not want the ACE XML Gateway to bind to the directory as a user, it can be configured to bind with its own account. If the usernames as received in requests do not match the DN needed to bind to the directory, you may need to configure a setup query that retrieves the user DN from the LDAP directory first. The following figure illustrates the interaction between the ACE XML Gateway and LDAP server given a configuration that reflects the most stringent verification requirements. Figure 6-5 LDAP Query Verification Sequence The following steps describe how to configure LDAP bind verification with or without a setup query: Step 1 In the authenticator condition for a password credential type (such as HTTP Basic Authentication or WSS Username), choose LDAP Query from the Verify Using menu. The Server, Setup Query, Query and Result Processing settings appear. Step 2 If the connection to the LDAP server you want to use is already defined in the policy, choose it from the Server menu. If it is not yet defined, click the New LDAP Server button and configure the connection to the LDAP server. Step 3 To use a setup query to acquire the user DN the ACE XML Gateway uses to bind to the directory, perform the following steps (alternatively, you can have the ACE XML Gateway bind to the directory with its own account to run the verification query, in which case you can skip this step): a. Click the checkbox labelled Perform setup query, storing result DN in substitution variable %d. b. Specify how the ACE XML Gateway will bind to the directory to perform the setup query by choosing from the Bind menu: •anonymously if the anonymous account is enabled in the directory and is configured with privileges that enable the anonymous user to find the user records. •with DN specified to have the ACE XML Gateway bind with a specific account. Enter a valid distinguished name in the User DN field and its password in the Password and Repeat Password fields. Note It is recommended that you create a dedicated account in the directory for the ACE XML Gateway to use for this purpose. If you have done so, enter the DN and password for the ACE XML Gateway's account. c. In the Base DN field, specify the location of the user account data in the directory, in DN format, such as cn=Users,dc=Cisco,dc=Com If you have a very complicated LDAP instance with multiple trees and forests, you will probably have to use an LDAP browser to determine the correct DN to use. d. In the Filter field, specify the LDAP filter expression that tests a particular user property, with the goal of matching the account of the user who submitted the service request. This mapping is aided by the %u variable, which contains the value of the username from the request. For example: (\|(cn=%u)(uid=%u)) If the value of a cn or uid property under the specified base DN matches the username from the request, the ACE XML Gateway gets back the full DN of the matched record. The DN gets populated into the %d variable, which is subsequently available to the ACE XML Gateway in its bind-as-user attempt. Step 4 In the Query settings, configure the query for evaluating the user attributes. The result of the query will be, in the positive case, an LDIF (Lightweight Directory Interchange Format) match result, which is tested by a result processing expression you configure. Like the setup query, a verification query is made up of bind settings and a filter. The bind attempt can be performed with known-good credentials (for example, of an account created for the ACE XML Gateway) or with credentials from the service request. In most cases, the service request credentials will be used for this step, which has the effect of validating those credentials. To configure the verification query: a. Specify how the ACE XML Gateway will bind to the directory to perform the verification query from the Bind menu: •anonymously if the anonymous account access is enabled in the directory with query privileges and you do not want to validate user credentials. •with DN specified, to have the ACE XML Gateway bind with a specific account. In this case, further specify either a valid distinguished name in the User DN field and its password (for example, for the account created for the ACE XML Gateway). To validate the credentials supplied in the request, pass the DN of the requesting user, either as acquired from a setup query (%d) or using a parameterized DN (see "Using LDAP Bind Password Verification" section). If passing the user's DN, choose the option labelled Use password provided by consumer for this credential to have the ACE XML Gateway bind with the password supplied in the service request. b. In the Base DN field, type the directory that contains the user accounts you want to query. A sample value would be: cn=Users,dc=Cisco,dc=Com If you have a very complicated LDAP instance with multiple trees and forests, you will probably have to use an LDAP browser to figure out the correct DN to use. c. In the Filter field, specify an LDAP filter expression that queries attributes of the user. As for the user DN used to bind to the directory, you may need to use substitution variables to define a useful filter. For example: (&(Name=Sales)(Member=%d)) This means that the "Name" of the group must be "Sales" and it must have a "Member" attribute equal to the user DN. This should return an LDIF-formatted query result similar to: "cn=support,cn=users,dc=Cisco,dc=com" d. Use the Attributes field, if desired, to reduce the information returned by the filter to the value of specific LDAP attributes. You can specify more than one attribute to get multiple values. To do so, use a space to separate the attribute names. For example, to use the e-mail addresses of sales people and no other data, enter mail in the Attributes field. This would just return the list of mail attributes for each record returned by the query. Using the Attributes field to narrow the filter return results can simplify the Match Regex you need to specify to validate the results. Step 5 The result of the verification query is one or more records from the directory. You can check the results with the result processing expression. The result processing expression serves to validate the results returned by the filter. Type a regular expression that tests the user data; that is, if it produces a match in the data, permits the user in this authenticator condition. For example, to ensure that the group returned is the sales group, type .sales. LDIF output is always all lowercase, so make sure your regular expression matches the lowercase version of the string. Note Depending on your LDAP schema and requirements, arriving at the correct filter and result processing expression to use may not be a simple matter. To help, you can use an LDAP tool such as Softerra™ LDAP Browser (http://www.softerra.com) to send the query and then tailor a regular expression that best suits your requirements. Step 6 Click Save Changes to commit your settings to the working policy. The password requirement should appear in the authenticator page with LDAP Query listed as the verification method. Using Per-Authenticator XML Security Public Keys By associating a consumer public key to an authenticator, the consumer's certificate can be used in XML encryption and XML signature verification tasks for messages accepted by the authenticator. This feature allows a virtual service to accept incoming messages from a variety of consumers while using certificates of various consumers for XML security processing tasks. That is, instead of requiring a separate virtual service for each service consumer (in order to accommodate the different client keys), this specialization can be located in the authenticators. Note This authenticator key is used only to process message content. A different setting specifies the X.509 public key the ACE XML Gateway uses to establish an HTTPS connection with consumers for this authenticator (configurable by adding an SSL/TLS Certificate condition to the authenticator). After the authenticator key is configured, you can apply it to message processing by choosing the consumer's XML security public key option in the appropriate area of the service handler configuration, as in Figure 6-6. The figure shows the option in the XML signature configuration settings, accessible from the SOAP Header Processing page of any SOAP service object. Figure 6-6 Verifying XML signatures with the consumer key To configure an XML security public key for an authenticator: Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu. Step 2 Click on the authenticator for which you want to specify an access condition or create a new one. Step 3 Click the Edit link in the General section of the information page. Step 4 If the public key resource does not appear in the XML Security Public Key menu, click the Upload button and use the Upload Consumer Certificate Resource page to add it to the list of consumer certificates. Step 5 Choose the new XML Security Public Key resource name from the menu on the Edit General Information page. Step 6 Optionally, have the name of the authenticator taken from the CN value of the certificate by choosing the option labelled Set the name of this Authenticator to the CN from this Consumer Certificate. In the event log, this name is used to identify service access events permitted by this authenticator. Step 7 Click Save Changes to save the changes to the working policy. You can now configure message processing specifications in the virtual services associated with the authenticator to use the consumer certificate configured for the authenticator. Identity Reports The ACE XML Gateway can report usage information based on consumer identity. Identity reporting is available if a credential validated by an authenticator can be tied to a given consumer, such as the username of a username/password credential or the subject identifier of a SAML token (in contrast, a time-of-day authenticator check cannot be tied to a given user). The ACE XML Gateway can report activities by consumer identity, such as number of requests, request size, and so on. This information appears in the Performance Monitor and in exported performance statistics files. Since a network attack can often be traced to just one or a few user accounts, you can set traffic thresholds that are triggered by activities associated with a user account. Service access for a user account can be blocked without affecting other users. User-identity settings are located in an authenticator. An authenticator may be associated with a single identity or many, depending on the nature of the credential. For instance, an authenticator that checks credentials by password (htaccess) file is associated with as many identities as there are username/password combinations in the file. The credentials that can establish user identities include: •IP address •SSL/TLS Certificate •Password-based credentials, including XPath password or WSS UsernameToken •SAML Token If the credential types in an authenticator do provide consumer identification, the user-identity configuration settings are not available. Enabling Identity Reporting Features User-identity reporting and threshold enforcement is enabled by authenticator. To enable user identity reporting and threshold limits: Step 1 While logged in to the web console as an Administrator user or a Privileged user with the Access Control role, click the Access Control Browser link in the navigation menu. Step 2 Click on the authenticator for which you want to specify an access condition or create a new one. Step 3 Click the Edit link next to Identity Reporting. If the authenticator requires credentials that can identify a user, the Edit Identity Reporting page appears. If the authenticator does not use credentials that permit user identification, a message appears indicating that fact. Step 4 Select the Enable Identity Reporting check box. The other checkboxes on the page become enabled. The credential types used in this authenticator appear in the Service Users Identifiers area. Step 5 Choose the credential types that the ACE XML Gateway should use to identify users from the Service Users Identifiers area. For example, if you choose IP Address, the IP address of a validated consumer is retained and used to identify the consumer for purposes of user-specific alerting and thresholds. You can choose more than one credential type, if desired. If you choose more than one, the values for all selected credentials must match across requests for the requests to be considered as originating from a single user. That is, if you select IP address and WSS UsernameToken as the identifiers, two requests that have the same username but different source IP addresses are not considered from a single user. However, if you only choose WSS Username as the user identifier, they are. If you only want to view consumer identity-related statistics, you do not need to configure any other options in the authenticator. You can save and deploy to begin collecting and viewing identity-based activity logging. See "Viewing User Activity Information" section for more information. Step 6 In the Alert Thresholds area, specify alerting and blocking thresholds for identified users, as follows: a. To have a log event created based on user activity, select the Log a Warning-level event when a Service User authenticates via this Authenticator more than option, and configure the per-minute and burst for the option: •times per minute is the number of authentication events per minute which, if exceeded, causes a log event. •times at once ("burst") is the burst level, that is, the number of concurrent authentication attempts allowed. Note For more information on these settings, see "Understanding Traffic Rate Thresholds" section on page 23-218. b. You can cause subsequent authentication attempts to be blocked by choosing Block requests from any Service User who authenticates via this Authenticator more than. Configure the following settings for this option: •times per minute is the number of authentication events per minutes which, if exceeded, results in the user being blocked. •times at once ("burst") is the burst level, that is, the maximum number of relatively concurrent authentication attempts allowed. Note For more information on these settings, see "Understanding Traffic Rate Thresholds" section on page 23-218. •If a user is blocked as a result of the threshold settings, specify how long in seconds blocking should continue in the Block for at least field. Step 7 Click Save Changes to commit your changes to the working policy. Deploy the policy to have the changes take effect at the ACE XML Gateway. Viewing User Activity Information After enabling user identification features in the ACE XML Gateway policy, you can view statistics on activities by the user: Step 1 Click the Performance Monitor link in the navigation menu (in the Reports and Tools area of the menu). Step 2 Expand the handler group for which you would like to see user information. Usage statistics for identified users appear in the list by username. Figure 6-7 User activity in the Performance Monitor Note For information on the statistics in the Performance Monitor, view the online help page from the Performance Monitor page. If message traffic logging is enabled for the service, you can search the traffic log by user, as follows: Step 1 In the navigation menu, click the Message Traffic Log link in the Reports and Tools category. Step 2 In the Simple Search pane of the message traffic log, click the User Search tab. Traffic associated with identified users appears in the traffic list. Step 3 To search for traffic for a particular user identity, type the username in the for User field and click Update View. The user search results appear in the page.
	Terms & Conditions \| Privacy Statement \| Cookie Policy \| Trademarks