Surrogate Agents and the Oracle® Enterprise Session Border Controller

In the case where a surrogate-agent is configured for the IP-PBX, you do not have to configure digest authentication attributes in the session-agent object for the same IP-PBX. The surrogate-agent authentication configuration takes precedence over the session-agent authentication configuration and so it is ignored.

The following illustration shows an example of a surrogate-agent with a session-agent in the network.

This image depicts a surrogate agent with a session agent in the network.

Surrogate Agent Authentication Across Realms

The ESBC uses an authentication attribute element in realms to support surrogate agent authentication requests initiated from other realms. This is a multi-instance element that supports the authentication of non-REGISTER traffic to surrogate agents with different authentication detail. The key for these lookups is the combination of the authentication realm and the authentication user lookup configurations. If you do not configure authentication attribute element in the realm, the ESBC handles surrogate agent authentication using the authentication table setup on the IP-PBX session agent, which supports this traffic in a single realm only.

This feature resolves two key surrogate agent authentication issues:

In a multi-tenanted environment, there might be multiple IP-PBX systems or realms trying to use the same surrogate agent function. Therefore, there is a need to authenticate traffic to surrogate agents by the ESBC on the SIP Trunk Realm with no association or relation to the IP-PBX system or realm.
In addition, some SIP Trunk providers send 401/407 challenges to all outbound calls. The ESBC utilizes the authentication table setup on the session-agent for username/password to response to the 401/407 challenge. However, if the auth-realm value is the same for all customers, then the ESBC cannot provide the correct username/password in response to the 401/407 challenge. When this feature is not set up, the ESBC always uses the first entry on the auth-attributes in the session agent's table for all outbound calls.

You configure the ESBC to populate the authentication headers using your configuration from either the softswitch's surrogate agent or realm during a 401/407 authentication challenge. The ESBC uses these tables to look up the authentication realm and obtain the username and password. The ESBC uses the username and password to authenticate the request.

Note:

The device initiating the authentication challenge to the surrogate agent does not need to be a softswitch.

The ESBC chooses the table based on your configuration:

If you have configured the auth-user-lookup parameter in the local-policy attribute, then the ESBC builds the authentication headers from the realm-config configuration.
If the auth-user-lookup parameter in the local-policy attribute is empty, then the ESBC builds the authentication headers from the IP-PBX session-agent configuration.

The ESBC uses the following objects to perform this feature's function:

A local-policy that forwards traffic to the target softswitch, which may or may not reside in a different realm from the source traffic. Further configuration supports intra-realm surrogate agent authentication.
The policy-attributes within that local-policy that includes the target auth-user-lookup value and the target realm of the surrogate agent.
An auth-attributes sub-element in the target realm-config. This sub-element includes:
- The realm of the surrogate agent. This is the host realm initiating the authentication challenge. This value defines the protected space in which the digest authentication is performed.
- An auth-user-lookup value that matches the auth-user-lookup in the local-policy.
- The username and password that provide access to the target surrogate agent.

Cross Realm Surrogate Agent Authentication Operation

After configuration, the ESBC authenticates applicable cross-realm surrogate agent authentication, allowing registration and call traffic.

When the ESBC receives traffic that triggers your local-policy, it uses the policy's auth-user-lookup value in combination with the target realm of the local-policy to prepare for authentication.

The key used for these lookups is a combination of the authentication realm and the user lookup. Typical behavior during operation includes:

If the auth-user-lookup in the policy-attribute is empty, the ESBC gets the configured password for authorization from the softswitch session-agent configuration.
If the auth-user-lookup in the policy-attribute is not empty, the ESBC selects the AuthAttributes (username/password) for the matching auth-user-lookup in the realm-config.
If the auth-user-lookup in policy-attribute is not empty, but there is no corresponding entry in realm-config, then the call fails as unauthorized. Additionally, the ESBC displays a warning during verify-config.

When operating with the auth-user-lookup from the local-policy attributes, the ESBC uses the returned value of username and password for authenticating the request. During the processing of the INVITE request, a reference to the selected local policy route is stored along with the route.

Additional Notes on Operation

The following are additional notes that describe the digest authentication process:

The ESBC always challenges the first LOGIN request, and initial authentication begins with that request. The selected authorization key — the credentials — are then included in every subsequent request.
If the ESBC does not receive any communication from the client within the expiration period, the ESBC logs the client out and tears down the transport connection. Faced with interface loss, the ESBC default behavior is to flush all warrant information from the target database. This response necessitates that the client first login/re-register with the ESBC, and then repopulate the empty database using a series of ADD requests. This behavior ensures that client and ESBC target databases are synchronized.   Alternatively, when faced with interface loss, the ESBC can retain all warrant information within the target database. This response necessitates only that the client first login/re-register with the ESBC. After successful registration the client should, but is not required to, use a series of GET, ADD, and DELETE requests to ensure that the ESBC and client target databases are synchronized.
The ESBC ignores the Authentication-Info header that comes in the 200OK response after digest authentication is complete. The ESBC receives a 401/407 response from the client. However, some surrogate-agents may process the Authentication-Info header in a single challenge.

Configure Authentication Attributes on a Realm

In the Oracle® Enterprise Session Border Controller ACLI, you can access the Digest Authentication object at the path media-manager, realm-config, auth-attribute. If enabled, this feature uses the attributes and values listed in this table. You perform this configuration to the realm-config on which the softswitch resides.

Note:

If enabling Digest Authentication, all attributes listed below are required except for the in-dialog-methods attribute, which is optional.

To configure digest authentication on the Oracle® Enterprise Session Border Controller:

In Superuser mode, type configure terminal and press Enter.
```
ORACLE# configure terminal
```
Type media-manager and press Enter to access the media manager-related objects.
```
ORACLE(configure)# media-manager
ORACLE(session-router)#
```

Type realm-config and press Enter.

ORACLE(media-manager)# realm-config
ORACLE(realm-config)#

Create or select the realm-config on which the softswitch resides.
Type auth-attributes and press Enter to access the digest authentication-related attributes.
```
ORACLE(realm-config)# auth-attributes
ORACLE(auth-attributes)#
```
auth-realm — Enter the identifier of this realm, which initiates the authentication challenge. This value defines the protected space in which the digest authentication is performed. Valid value is an alpha-numeric character string. Default is blank.
```
ORACLE(auth-attribute)# auth-realm realm01
```
username — Enter the username of the client. Valid value is an alpha-numeric character string. Default is blank.
```
ORACLE(auth-attribute)# username user
```
auth-user-lookup — Enter a name for this auth-user-lookup. You use this same name when configuring the auth-user-lookup within the attributes of the local-policy you use for this surrogate agent. Default is blank.
```
ORACLE(auth-attribute)# auth-user-lookup user
```
password — Enter the password associated with the username of the client. This is required for all LOGIN attempts. Password displays while typing but is saved in clear-text (i.e., *****). Valid value is an alpha-numeric character string. Default is blank.
```
ORACLE(auth-attribute)# password *******
```
in-dialog-methods — Enter the in-dialog request method(s) that digest authentication uses from the cached credentials. Specify request methods in a list form separated by a space enclosed in parentheses. Valid values are:
- INVITE
- BYE
- ACK
- CANCEL
- OPTIONS
- SUBSCRIBE
- PRACK
- NOTIFY
- UPDATE
- REFER
```
ORACLE(auth-attribute)# in-dialog-methods (ack invite subscribe)
```
If you do not specify any in-dialog-method value(s), digest authentication does not add challenge-responses to in-dialog requests within a dialog. This attribute setting applies to in-dialog requests only.

Note:
The methods not in this list are still resubmitted if a 401/407 response is received by the Oracle® Enterprise Session Border Controller.
Type done to save changes to this realm-config.
Save and activate your configuration.

Configure the applicable local-policy. This configuration includes setting the auth-user-lookup parameter in the applicable local-policy-attribute with the same value as the auth-user-lookup above.

Configure a Local Policy for Authenticating Surrogate Agent Traffic

To configure a local policy to support intra-realm surrogate agent authentication, you configure the local policy that directs traffic from the surrogate agent to the softswitch, which initiates the authentication challenge for any traffic coming from the surrogate agent (usually a PBX without the ability to authenticate itself).

In Superuser mode, type configure terminal and press Enter.
```
ACMEPACKET# configure terminal
```
Type session-router and press Enter.
```
ACMEPACKET(configure)# session-router
```
Type local-policy and press Enter. The system prompt changes to let you know that you can begin configuring individual parameters.
```
ACMEPACKET(session-router)# local-policy
ACMEPACKET(local-policy)#
```
from-address—Indicate the originating address information by entering a From address value. You can use the asterisk (*) as a wildcard to indicate this policy can be used with all originating addresses.

Note:
After entering the from-address value, the Oracle Communications Session Delivery Manager automatically saves it to the configuration when exiting from local policy.
to-address—Indicate the destination address by entering a To address value. You can use the asterisk (*) as a wildcard to indicate all this policy can be used for any destination address.

Note:
After entering the to-address value, the Oracle Communications Session Delivery Manager automatically saves it to the configuration when exiting from local policy.
source-realm—Enter the identifier of the realm on which the surrogate agent resides.
state—Indicate whether you want the local policy to be enabled or disabled on the system. The default value is enabled. The valid values are:
- enabled | disabled
policy-attribute—Configure local policy attributes required for this feature. All other attributes are optional.
next-hop—Identify the next signaling host by entering the next hop value. For this feature, then next hop is the soft switch.
realm—Identify the egress realm (the realm used to reach the next hop) if the system must send requests out from a specific realm.
lookup—Set this parameter to single.
auth-user-lookup—Enter the name of the target auth-user-lookup you have configured for this surrogate agent on the Softswitch realm.
Type done twice to save changes to your policy-attributes and your local policy.
Save and activate your configuration.