Configuring the Proxy Registrar
This chapter describes how to configure a proxy registrar and the permissible Proxy-Require options for the Sip Server in the Oracle Communications Converged Application Server deployment.
About Proxy Registrar Configuration
The Administration Console exposes the Proxy Registrar MBean attributes that are used to set Proxy and Registrar parameters. Only those parameters and attributes that you typically need to set are exposed in the Administration Console. To modify advanced parameters and attributes, you can modify MBean attributes by using WebLogic Scripting Tool (WLST).
For information about the Proxy and Registrar MBeans, see the Converged Application Server Java API Reference.
Some Proxy Registrar configurations, such as security settings, require that you edit the sip.xml deployment descriptor. If you modify sip.xml, you must redeploy the Proxy Registrar for the changes to take effect.
Setting Authentication for the Proxy Registrar
Authentication for the Proxy and Registrar is defined in a
security-constraint
element in the sip.xml deployment
descriptor. Proxy and Registrar authentication is enabled by default. You can disable
authentication for the Proxy, Registrar, or both by removing their respective section
from the security-constraint
element:
- To disable Registrar authentication, remove the
registrar servlet
section. - To disable Proxy authentication, remove the
VoipProxy Servlet
section.
The type of authentication for SIP requests is defined in the
auth-method
subelement of the login-config
element
in sip.xml. Converged Application Server supports DIGEST, BASIC and CLIENT-CERT
authentications. DIGEST authentication is the default. For more information, see the
discussion of authentication for SIP servlets in the Converged Application Server
Security Guide.
You can also set the following authentication policy:
- Trusted hosts:
You can bypass authentication for certain hosts by adding trusted-host definitions in the
sip-security
element. See sip-security.Note:
You can also configure trusted hosts by using the Administration Console. See Using the Administration Console to Configure Trusted Hosts for instructions. - Identity assertion mode:
You can set the
identity-assertion
element in sip.xml to specify eitherP-Asserted-Identity
orIdentity
. - Security provider:
You configure security providers by using the Administration Console:
- If you set the identity assertion mode to
P-Asserted-Identity
, then configure a P-Asserted-Identity Assertion Provider. Be sure to set its Trusted Hosts parameter. - If you set the identity assertion mode to
Identity
, then configure an Identity Header Assertion Provider.
See the discussion of SIP servlet identity assertion in the Converged Application Server Security Guide.
- If you set the identity assertion mode to
Using the Administration Console to Configure Trusted Hosts
You can specify to bypass authentication for certain hosts by adding trusted-host definitions through the Administration Console.
To add trusted hosts:
-
Log in to the Administration Console.
-
If your domain is running in Production mode, click Lock & Edit.
-
In the Domain Structure panel, click SipServer. The SIP Server configuration options are displayed in the main window.
-
Click the Configuration tab and then the SIP Security tab.
-
Enter any trusted hosts and click Save.
-
If your domain is running in Production mode, click Activate Changes.
-
Stop and restart all servers in the domain. See Getting Started.
Configuring the Proxy Registrar
To configure the Proxy Registrar do the following:
Configure the Proxy
To configure the Proxy:
-
Log in to the Administration Console.
-
If your domain is running in Production mode, click Lock & Edit.
-
In the Domain Structure panel, click ProxyRegistrar. The Proxy Registrar configuration options are displayed in the main window.
-
Click the Proxy tab.
-
Configure the following Proxy parameters:
Note:
Parameters that are preceded by an exclamation mark (!) indicate that you must restart the servers for the new value to take effect. Be sure to restart all servers in the domain to ensure that the new values are propagated to all servers. Getting Started.
-
!Enable ENUM Lookup: Select this option to enable ENUM lookup. If ENUM lookup is disabled and the request URI is a Tel URL, then the request will be rejected with a 404 response.
-
!ENUM DNS Server: Specify the address of the DNS server.
-
!ENUM Zone: This is the DNS Zone used by ENUM. The default domain "e164.arpa" provides the infrastructure in the DNS for storage of E.164 numbers.
-
!ENUM SIP Service Field: Specify which service field of the DNS NAPTR record to retrieve. The default, E2U+sip, is the common value for SIP applications.
-
!ENUM Preset DNS Response: Specify a comma-separated list of predefined DNS responses. If you set this value, the Proxy does not consult the DNS server for ENUM lookup. Instead, the Proxy uses the ENUM Preset DNS Response value as the response from the DNS server.
-
Force Record Route: Select this option if you want all subsequent requests to go through the Proxy. The default is True.
-
Parallel Forking: Indicates whether a call that has more than one destination is routed to those destinations in parallel or sequentially. The default is parallel.
-
TimeOut Length: Specify the period in seconds that the Proxy waits for a final response to a request. The default is 180 seconds.
If Parallel Forking is set to sequential, the time-out period is the time the container waits for a final response from a branch before it CANCELs the branch and proxies the next destination in the target set.
If Parallel Forking is set to Parallel, the time-out period is time the container waits for final responses from the entire proxy (that is, all of the parallel branches) before it CANCELs the branches. With parallel forking, the container sends the best final response upstream.
-
!Hosted Domains: Only set this value if you set Use Domain Service to false. Specify a comma-separated list of the domain names for the domains hosted by this server. To specify any domain name, use an asterisk: *
-
!Use Domain Service: Select this option to use the Domain Service to determine which domains are hosted by the server. If set to false (not selected), then specify the domains in the Hosted Domains parameter to specify the domains.
-
Offline Code: Specify the status code that is returned when a SIP client is offline.
-
-
If needed, configure advanced parameters. You typically do not need to do this and can accept the default values.
-
At the bottom of the Proxy window, click Advanced to display the advanced parameters.
-
If needed, set the following parameters:
!Options: This specifies any option tags supported by the Proxy. When receiving a request that has a Proxy-Require header, all option tags listed in the Proxy-Require header must be specified in the Options field. If not specified, the proxy will reject the request with a 420 response. The value is a comma-separated list of options. For example, “privacy, sec-agree".
!Location Service: Specify the location service class name.
-
-
Click Save.
-
If your domain is running in Production mode, click Activate Changes.
-
If you changed the value of any parameter that requires restarting the server, stop and restart all servers in the domain. See Getting Started.
Configuring the Registrar
To configure the Registrar:
-
Log in to the Administration Console.
-
If your domain is running in Production mode, click Lock & Edit.
-
In the Domain Structure panel, click ProxyRegistrar. The Proxy Registrar configuration options are displayed in the main window.
-
Click the Registrar tab.
-
Configure the following Registrar parameters:
Note:
Parameters that are preceded by an exclamation mark (!) indicate that you must restart the servers for the new value to take effect. Be sure to restart all servers in the domain. See Getting Started.
-
Max Contacts: Specifies the maximum allowed number of Contact headers in a REGISTER request and the maximum number of contacts that will be stored as a result of multiple REGISTER requests. The default is 5.
-
Max Registration Expires: Specifies in seconds, the maximum allowed expiration time for registrations. If a request is made that exceeds this maximum, a response is sent that the time is too long. The default is 7200 seconds. Max Registration Expires must be greater than the value of Min Registration Expires.
-
Min Registration Expires: Specifies in seconds, the minimum allowed expiration time for registrations. If a request is made that is shorter than this minimum, a response is sent that the time is too brief. The default is 60 seconds. Min Registration Expires must be less than the value of Max Registration Expires.
-
Default Registration Expires: Specifies in seconds, the default expiration time for registrations. If an expiration time is not requested, the default is used. The default value is 3600 seconds. Default Registration Expires must be greater than the value of Min Registration Expires and less than the value of Max Registration Expires.
-
Max Subscription Expires: Specifies in seconds, the maximum allowed expiration time for subscriptions. If a request is made that exceeds this maximum, a response is sent that the time is too long. The default is 7200 seconds. Max Subscription Expires must be greater than the value of Min Subscription Expires.
-
Min Subscription Expires: Specifies in seconds, the minimum allowed expiration time for subscriptions. If a request is made that is shorter than this minimum, a response is sent that the time is too brief. The default is 60 seconds. Min Subscription Expires must be less than the value of Max Subscription Expires.
-
Default Subscription Expires: Specifies in seconds, the default expiration time for registrations. If an expiration time is not requested, the default is used. The default value is 3600 seconds. Default Registration Expires must be greater than the value of Min Registration Expires and less than the value of Max Registration Expires.
Note:
The Administration Console does not validate that the expiration times are logically set. For example, if you set Default Expires to 3600 seconds and set Max Expires to 2700 seconds, the Administration Console will accept the configuration, but registrations may be denied.
-
-
If needed, configure advanced parameters. You typically do not need to do this and can accept the default values.
-
At the bottom of the Registrar window, click Advanced to display the advanced parameters.
-
Set the following parameters:
Supported Methods: Specify the supported methods to insert into the Contact header of REGISTER request responses when the REGISTER request itself does not include supported methods in the Allow header or the Contact header.
The format of this value is the same as the methods parameter in the contact header.
Enable Associated ID: Indicates whether to add the P-Associated-URI header when the Registrar sends a response.
!Location Service House Keeper Period: The house keeper removes expired registrations. Specify in seconds, the period between house-keeper runs. A negative value means to run the house keeper only once, when the Proxy Registrar application is started. The default is 300 seconds.
!Location Service House Keeper Delay: Specify in seconds, the time to wait after the Proxy Registrar application is started, before the house keeper is started. A negative value turns off the house keeper. The default is 120 seconds.
!Location Service: Specify the location service class name.
-
-
Click Save.
-
If your domain is running in Production mode, click Activate Changes.
-
If you changed the value of any parameter that requires restarting the server, stop and restart all servers in the domain. See Getting Started.
Configuring the Proxy-Required Options for the Sip Server Proxy
Provide the message header field values that the application supports in incoming messages. If the message header field of an incoming message contains a value from this configured list, then the message header is passed on to the application.
To provide the message header values for the Sip Server Proxy:
-
Log in to the Administration Console.
-
If your domain is running in Production mode, click Lock & Edit.
-
In the Domain Structure panel, click Sip Server. The Sip Server configuration options are displayed in the main window.
-
Click the Proxy tab.
-
In the Proxy-Require Options field, enter a comma-separated list of permissible values for the Proxy-Require headers. For example:
proxy,timer
-
Click Save.
Provisioning Users
You can use Sash to provision users for the proxy registrar. Sash is a
command-line utility for provisioning Converged Application Server users to the
database, to the XML Document Management Server (XDMS), and to the RADIUS server. You
can provision users from the Sash command line prompt (sash#
) or by
using the CommandService MBean.
See Getting Started With Oracle Internet Directory in Administrator's Guide for Oracle Internet Directory for information on using Oracle Internet Database (OID) as the user provisioning repository for a Converged Application Server deployment.
Launching Sash
The Sash launcher script is located in the same folder that contains the start and stop scripts for Converged Application Server.
Launching Sash from the Command Line
Converged Application Server provides the following scripts for launching Sash from the command line:
launch_sash.sh
(UNIX)
launch_sash.cmd
(Windows)
These scripts are located at domain_home/bin
, where domain_home is the home directory of the domain.
Connecting Sash to an External Converged Application Server Instance
By default, Sash connects to the local instance of Converged Application Server. If needed, you can override this default behavior and connect Sash to external instances of Converged Application Server.
Connecting to an External Instance of Converged Application Server
Sash connects to the Converged Application Server server through RMI. The following example illustrates how to connect Sash to a Converged Application Server instance with the host IP address 10.1.10.23:
sash –-host 10.1.10.23
When you connect to Converged Application Server, Sash prompts you for a username and a password. The user name is the same as that for Converged Application Server administrator. The password is the same as the password associated with the Converged Application Server administrator. Once you log in, the Sash command prompt (sash
) appears. An error message displays if the login is unsuccessful.
Using Sash
There are two groups of Sash commands:
-
Commands that create, delete, and update system objects
-
Commands that query the system for information
Note:
Whenever a user adds a new application usage, the user must restart the server before the new application usage is available.
Whenever a user deletes an existing application usage, the user must restart the server for the deleted application usage to be completely unloaded (that is, a deleted application usage will remain loaded until the server is restarted, when it is unloaded and is then completely unavailable).
If a space precedes a sash command in a file, and then that file is used as input to the sash command, it does not work. Ensure that you remove any preceding spaces in sash commands in sash input files.
Viewing Available Commands
Entering help
displays a list of all available commands in
the server. The list of commands varies depending on the components deployed to the
server.
Table 2-1 Stand-alone Shell (Sash) Commands
Command | Description | Aliases | Subcommands |
---|---|---|---|
|
Commands for adding and removing private communication identities used for authentication. |
None |
Subcommands include:
|
|
Commands for adding and removing public identities associated with a private identity. |
|
Subcommands include:
|
|
Contains commands for managing user accounts. This command enables you to set the account as active, locked, or as a temporary account. |
None |
Subcommands include:
|
|
Manages role types and user
roles in the system. |
None |
Subcommands include
|
|
Manages the roles types. |
None |
Subcommands include:
|
|
Manages the user roles |
None |
Subcommands include:
|
|
Command for managing credentials. |
None |
Subcommands include:
|
|
Enables you to create a basic user account. |
None |
Viewing Subcommands
To view the subcommands for a specific command, enter help
<command>
. For example, entering help
for the
account
command (help account
) retrieves a brief overview
of the subcommands available to the account
command.
Example 2-1 Retrieving Help for a Specific Command
*** Description **** Contains commands for management of user accounts. In an account you can set if the account is active, locked or if it perhaps should be a temporarily account. Aliases: [no aliases] Syntax: account Sub-commands: # Adds a new account to the system account add uid=<string> [ active=<true|false> ] [ locked=<true|false> ] [ accountExpiresAt=<accountExpiresAt> ] [ tempAccount=<true|false> ] [ description=<string> ] [ lockExpiresAt=<lockExpiresAt> ] [ currentFailedLogins=<integer> ] # Deletes an account account delete uid=<string> # Updates an account account update uid=<string> [ active=<true|false> ] [ locked=<true|false> ] [ accountExpiresAt=<accountExpiresAt> ] [ tempAccount=<true|false> ] [ description=<string> ] [ lockExpiresAt=<lockExpiresAt> ] [ currentFailedLogins=<integer> ] # Retrieve information about a particular account account info uid=<string>
In addition to the overview of the command group, the information displayed by
entering help <command>
also includes the aliases (if any) to the
command.
Note:
Thedelete
command used
with account
, role
, role system
,
role user
, privateIdentity
,
publicIdentity
, and identity
has the following aliases:
remove
del
rm
Some commands require parameters. For example, if you enter help role
system add
, the system informs you that the add
command requires
the name of the role and an optional command for setting the description as well by
displaying:
role system add name=<string> [description=<string>]
Note:
Optional commands such as[description=<string>]
are enclosed within square brackets
[...]
.
The system alerts you if you omit a mandatory parameter or if you pass in a parameter that is not recognized.
Creating a User
This section describes the publicIdentity
and
privateIdentity
commands and how to use them in conjunction with
the add
, account
, role
, and
credentials
subcommands to provision a user account to the Oracle
database.
The Private Identity (privateIdentity
) uniquely identifies
a user within a given authentication realm. The Public Identity
(publicIdentity
) is the SIP address that users enter to register
devices. This address is the user's Address of Record (AOR) and the means through which
users call one another. A user can have only one Private Identity, but can have several
Public Identities associated with that Private Identity.
Note:
To enable authentication to third-party databases (such as RADIUS), user accounts that contain authentication data and are stored externally must match the Private Identity to ensure the proper functioning of the Proxy Registrar and other applications that require authentication.To create a user, first add the user to the system by creating a private
identity and then a public identity for the user using the
privateIdentity
and publicIdentity
commands with
the add privateId
and add publicId
subcommands,
respectively.
After you create the private and public identity for the user, create an
account for the user with the account add uid
command and optionally
set the status of the account (such as active or locked). The role
command sets the role memberships for role-based permissions. Set the level of
permissions for the users using the role
command, and then set user
credentials by defining the user's realm and password with the
credentials
command.
Creating a User from the Sash Command-Line Prompt
This section illustrates how to create a user from the Sash command prompt
(sash#
) by creating a Converged Application Server user known as
alice.
- Create a user using the
privateIdentity
command.privateIdentity add privateId=alice
- Create the public identity for alice by entering the SIP
address:
publicIdentity add publicId=sip:alice@test.example.com privateId=alice
- Add an account for alice and use one of the optional commands to set the
status of the account. To create an active account for alice, enter the
following:
account add uid=alice active=true
- Use the
role
command to add alice to the Location Service user group. Doing so grants alice permission to the Proxy Registrar's Location Service lookup.role user add uid=alice name="Location Service"
- Add user authentication credentials for
alice:
credentials add uid=alice realm=test.example.com password=<password>
The
credentials
command is not needed for applications configured to use the RADIUS Login Module to authenticate users against RADIUS servers. For more information on these login modules, see Converged Application Server Security Guide.Note:
You must also configurerealms
using the SIP Servlet Container MBean before you use Sash to add authorization credentials to a user.WARNING:
You can only create one user per Sash command. If you configure a single command that creates multiple users, only the final user will be created.
Example 2-2 Creating a User from the Sash Command-Line Prompt
sash# privateIdentity add privateId=alice
sash# publicIdentity add publicId=sip:alice@test.example.com privateId=alice
sash# account add uid=alice active=true
sash# role user add uid=alice name="Location Service"
sash# credentials add uid=alice realm=test.example.com password=<password>
Tip:
To create multiple users by creating Sash batch files, see Scripting with Sash.Creating a User with the Command Service MBean
You can execute Sash commands using the CommandService MBean's execute operation. The Command Service MBean is defined within the subscrdataservcommandsear
application.
To create a user:
-
Select the execute operation. The Operation page for the execute operation appears.
-
Enter privateIdentity add privateId=alice in the Value field.
-
Click Invoke Operation. Repeat this process for each of the user creation commands. For example, the subsequent
publicIdentity
andaccount
commands would both be followed by Invoke Operation.
Creating a User with the Identity Add Command
The identity add
command enables you to create a user with
one command string. This command, which is an alias to the
privateIdentity
, publicIdentity
,
account
, role
and credentials
commands, enables you to quickly create a basic user account that contains the minimum
information needed for users to connect to Converged Application Server through a SIP
client. For example, to create a basic account for user alice using this command,
enter the following from either the command line or through the Command Service MBean's
execute operation:
identity add privateId=alice publicId=sip:sip.alice@example.com role="Location Service" realm=example.com password=<password>
Note:
For applications configured to authenticate users against a RADIUS system (the applications with the RADIUS Login Module as the security provider), the command to create a user account is as follows:identity add privateId=alice publicId=sip:sip.alice@example.com role="Location Service"
The identity add
command only enables you to create a basic
user account. Accounts that require more complex construction, such as those that
associate multiple publicId
s with a single privateId
,
must be created using multiple Sash commands.
Deleting a User
The identity delete
command enables you to delete all of a user's roles, credentials, account information, public and private identities using a single command string. For example, to delete an account for a user alice using this command, enter the following from either the command line or through the Command Service MBean's execute
operation:
identity delete privateId=alice
Note:
The identity delete
command indicates the delete operation is successful if any of the user's data is deleted, even if certain data, such as the user account, no longer exists due to being previously deleted.
Scripting with Sash
You can construct scripts for common tasks that contain several operations. Sash can be evoked to execute a file containing a list of commands. To enable scripting, Sash provides such command-line flags as:
--exec
(short name:-e
): When this command-line flag is followed by a command enclosed within quotation marks, Sash executes the command and then exits.--file
(short name:-f
): When this command-line flag is followed by a filename, Sash reads the file and executes all commands in the file as they were entered and then exits.--nonewline
: This command-line flag facilitates parsing output by stripping returns or newlines from the messages returned from the executed commands. Although this command facilitates parsing, it makes reading messages manually more difficult.
Example 2-3 Creating Users from a Text File (OWLCS_users.txt)
identity add privateId=candace publicId=sip:candace@doc.oracle.com role=user password=1234 realm=doc.oracle.com identity add privateId=deirdre publicId=sip:deirdre@doc.oracle.com role=user password=1234 realm=doc.oracle.com identity add privateId=evelyn publicId=sip:evelyn@doc.oracle.com role=user password=1234 realm=doc.oracle.com identity add privateId=frank publicId=sip:frank@doc.oracle.com role=user password=1234 realm=doc.oracle.com
Error Logging in Sash
Sash does not log to any files (with the default configuration), it only prints messages on the console. The log level for Sash is configured in ORCL_HOME
/sash/conf/logging.properties
, where ORCL_HOME
is the home directory where you installed the WebLogic Server portion of Converged Application Server (the default ORCL_HOME
is oracle/middleware/occas
).