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 Remote 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 Remote 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 Remote Console. See Using the Remote Console to Configure Trusted Hosts for instructions.
Identity assertion mode:
You can set the identity-assertion element in sip.xml to specify either P-Asserted-Identity or Identity.
Security provider:
You configure security providers by using the Remote 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.

Using the Remote Console to Configure Trusted Hosts

You can specify to bypass authentication for certain hosts by adding trusted-host definitions through the Remote Console.

To add trusted hosts:

From the Edit Tree of the Remote Console, click Custom Resources, and then sipserver, and then SIP Server, and then SIP Security.
Enter any trusted hosts.
Click Save, click the shopping cart, and then click Commit Changes.

Configuring the Proxy Registrar

In this release, the Remote Console does not support configuring Proxy Registrar domains. All support for Proxy Registrars will be removed in the next release.

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:

From the Remote Console, click Custom Resources, and then sipserver, and then SIP Server, and then Proxy.
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, click the shopping cart, and then click Commit Changes.

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
`privateIdentity`	Commands for adding and removing private communication identities used for authentication.	None	Subcommands include: `add` – Adds a new user to the system. For example: `privateIdentity add privateId=alice` `delete` – Removes a user from the system. For example: `privateIdentity delete privateId=a`lice
`publicIdentity`	Commands for adding and removing public identities associated with a private identity.	`pubid`	Subcommands include: `add` – Adds a public identity to the system which is associated with a particular user. For example: `publicIdentity add publicId=sip:alice@test.example.com privateId=alice` `delete` – Deletes a communication identity from the system. For example: `publicIdentity delete publicId=sip:alice@test.example.com privateId=alice`
`account`	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: `add` – adds a new account to the system. The syntax is as follows: `account add uid=<string> [active=<true\|false>] [locked=<true\|false>] [accountExpiresAt=<accountExpiresAt>] [tempAccount=<true\|false>] [description=<string>] [lockExpiresAt=<lockExpiresAt>] [currentFailedLogins=<integer>]` For example: `account add uid=alice active=true` `delete` – Deletes an account from the system. For example: `account delete uid=<string>` `update` – Updates an account. For example: `account update uid=<string> [active=<true\|false>] [locked=<true\|false>] [accountExpiresAt=<accountExpiresAt>] [tempAccount=<true\|false>] [description=<string>] [lockExpiresAt=<lockExpiresAt>] [currentFailedLogins=<integer>]` `info` – Retrieves information for a specific account. For example: `account info uid=<string>`
`role`	Manages role types and user roles in the system. `role` is an additional security and authorization mechanism that is defined within the `<auth-constraint>` element of sip.xml. This command authorizes a group of users access to applications. The applications in turn check for a specific role. Converged Application Server defines one role for the Proxy Registrar application, "Location Services".	None	Subcommands include `role system` and `role user`.
`role system` (subcommand of `role`)	Manages the roles types.	None	Subcommands include: `list` – Lists the roles in the system. For example: `role system list` `add` – Adds a new role to the system. For example: `role system add name=<string> [description=<string>]` `update` – Updates a role in the system. For example: `role system update name=<string> [description=<string>]` `delete` – Deletes a role from the system. For example: `role system delete name=<string> [description=<string>]`
`role user` (subcommand of `role`)	Manages the user roles	None	Subcommands include: `add` – Adds a role to a user. For example: `role user add uid=<string> name=<string>` `delete` – Deletes a role from a user. For example: `role user delete uid=<string> name=<string>` `list` – Lists roles for a user. For example: `role user list uid=<string>`
`credentials`	Command for managing credentials.	None	Subcommands include: add – Adds credentials to a user. For example: `credentials add password=<string> realm=<string> uid=<string>` `addAll` – Adds credentials for all of the configured realms in the system to a user. For example: `credentials addAll password=<string> uid=<string>` `delete` – Deletes realm credentials for a user. For example: `credentials delete realm=<string> uid=<string>` `deleteAll` – Deletes all credentials for a user. For example: `credentials deleteall uid=<string>` `update` – Updates the credentials for a user. For example: `credentials update password=<string> realm=<string> uid=<string>` `updateAll` – Updates a user's credentials for all provisioned realms in the system. For example: `credentials updateAll password=<string> uid=<string>` `list` – Lists all of the realms for which credentials exist for a given user. For example: `credentials list uid=<string>`
`identity add`	Enables you to create a basic user account.	None	None. See Creating a User with the Identity Add Command.

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:

The delete 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 configure realms 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 and account 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 publicIds 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).