1. ACLI Configuration Guide
  2. SIP Signaling Services
  3. Routing Calls from an IP-PBX using a Surrogate Agent
  4. Matching an INVITE to a Surrogate Agent

Matching an INVITE to a Surrogate Agent

You can configure the ESBC to perform authentication for an end station sending an INVITE through its surrogate agent in two ways. These methods match information in your surrogate-agent, and in some cases session-agent configurations, with source information in the request. The ESBC uses this function for requests needing authentication, except REGISTERs. This processing is not relevant to calls sent to a surrogate-agent.

Assuming configuration, to confirm and authenticate requests originating from a surrogate agent, the ESBC matches:

  1. Information in the FROM header in the request to a registered user, and then your register-user and register-host configuration in your surrogate-agent. These matches confirm the surrogate-agent from which the request came. If these do not match, the ESBC does not continue with authentication.

    Note:

    The FROM header should contain the user portion of one of the Associated-URIs that it received from the registrar in the 200 (OK) responses to REGISTER requests. It should also have a hostname.

    Note:

    Should the register-host match fail, the ESBC tries to match the host portion with your customer-host configuration.
  2. IP source addressing to the source-ip-prefix parameter within the surrogate-agent element. This confirms that the ESBC can perform the authentication. If you have configured this parameter and there is no match, the ESBC does not authenticate the request.
  3. If there is no source-ip-prefix configuration, the ESBC tries to match the customer-next-hop configuration in the surrogate-agent with the source of the incoming request. This can also confirm that the ESBC can perform the authentication.

To perform this step, the ESBC compares the source IP of the request with the customer-next-hop parameter. You can configure the customer-next-hop parameter with a session-agent name, a session-agent-group or any IP address. That value must match:

  • The hostname Session Agent, or the group-name of the Session Agent Group.
  • If configured with an IP address, your value must match the source IP of the request.

The source-ip-prefix configuration provides the ESBC with the flexibility to perform the authentication against specific IP addresses, multiple prefixes and/or IP ranges. The customer-next-hop configuration allows for only a single entry, attempting to match to a single address, a hostname configuration on a corresponding session-agent or the group name of the SAG to which the session agent belongs.

Note:

If source-ip-prefix is not configured and the customer-next-hop matches a session-agent-group, the ESBC uses that group to choose a specific session-agent.

Process Detail

The steps below present ESBC behavior when it receives a request from a surrogate-agent that needs authentication, other than a REGISTER. The steps use an INVITE as an example. To support these calls the ESBC:

  1. Determines if there is a surrogate-agent match by ensuring the FROM matches the register-user and the register-host or customer-host in the surrogate-agent agent configuration.

    Note:

    If there is no match with the register-host, the ESBC attempts to match the applicable host portion with the customer-host configuration.
    • If not, the ESBC attempts to use other configuration to proceed with the call, such as local policy. If those processes do not find a route, the ESBC sends the caller with a 480 - No routes found message.
    • If so, the ESBC attempts to verify the source of the INVITE to determine whether or not it can perform the authentication on behalf of the IP-PBX.
  2. To determine if it should perform the authentication, the ESBC checks whether the surrogate-agent has a source-ip-prefix configuration:
    • If so, the ESBC matches the source IP address with any of your source-ip-prefix settings in the surrogate-agent.
      • If there is a match, the ESBC considers the INVITE as originated from a trusted source and it can perform authentication on behalf of the surrogate-agent.
      • If it does not match, the ESBC does not perform authentication on behalf of the surrogate-agent, and forwards a 401 with challenge towards the IP-PBX.
  3. If you have not configured the source-ip-prefix, the ESBC can next refer to your customer-next-hop configuration and check for a match. to the surrogate-agent. Detail on matching criteria is above.
    • If there is a match, the ESBC considers the INVITE as originated from a trusted source and performs authentication on behalf of surrogate-agent.
    • If it does not match, the ESBC does not perform authentication on behalf of surrogate-agent, and forwards 401 with challenge towards the endpoint.
  4. If there is a match, the ESBC generates an INVITE with authentication parameters and sends it to the REGISTRAR to confirm the authentication.
  5. If the authentication is successful, the ESBC sends a 200 OK to the IP-PBX, and routes the call to the callee.
  6. If the authentication fails, the ESBC sends a 401 with challenge to the IP-PBX.
  7. At this point, the endpoint may or may not attempt to authenticate itself directly with the REGISTRAR.
    • If not, the call does not proceed.
    • If so, and the authentication is successful, media may proceed between the caller and callee.
    • If so, and the authentication fails, the REGISTRAR replies to the IP-PBX directly with (an authentication failed message), and the call does not proceed.

Configuration Detail on Verifying Source IP

You configure the source-ip-prefix and the customer-next-hop parameters on the applicable surrogate-agent. The source-ip-prefix accepts any number of IP addresses and IP address prefixes in the format <ip>/<subnet>. If you set multiple values, separate them with a space and enclose them with parenthesis (). Addressing can be IPv4, IPv6 or a combination of both. The ESBC performs individual match checks in the same order as your configuration.

For example, to configure the agent to trust IPs 192.168.1.0, 172.16.10.10 and 172.168.x.x, you can configure the parameter as follows. 

ORACLE(surrogate-agent)#source-ip-prefix (192.168.1.0 172.168.0.0/16 172.16.10.10)

In contrast, the customer-next-hop parameter accepts a single entry as an IP address, FQDN, Session Agent name, or Session Agent Group name. 

ORACLE(surrogate-agent)#customer-next-hop 192.168.1.0

The ESBC prevents you from configuring parameters using an incorrect format.

Related Configuration

Note the following configurations and their impact on this authentication process.

  • This feature fully supports HA deployments.