Skip Headers

Oracle® Communication and Mobility Server Administrator's Guide Release 10.1.3 Part Number E10292-02 |
Home | Contents | Index | Contact Us

Previous | Next
| View PDF

# 5 Provisioning Users and Applications

This chapter describes using the Sapphire Shell (Sash) utility. This chapter includes the following sections:

- "Overview of Sash"

- "Launching Sash"

- "Using Sash"

- "Creating a User"

- "Provisioning the XDMS Using Sash"

- "Scripting with Sash"

- "Error Logging in Sash"

## Overview of Sash

The Sapphire Shell (Sash) is a command-line utility to provision OCMS users to the TimesTen In-Memory database, the XDMS (XML Document Management Server) and the RADIUS server. You can provision users from the Sash command line prompt (`sash#`) or by using the CommandService MBean.

See "Configuring Oracle Internet Directory as the User Repository" for information on using Oracle Internet Database (OID), the LDAP data store used by Oracle WebCenter Suite, as the user provisioning repository for an OCMS deployment.

## Launching Sash

On Windows, you invoke Sash by selecting the Launch Sash option of Oracle Communications and Mobility Server (accessed through Start > All Programs). On Linux systems, the Sash launcher script (`launch_sash.sh`) is located in the same folder that contains the start and stop scripts for OCMS.

Figure 5-1 Launching Sash from the Windows Programs Menu

Description of "Figure 5-1 Launching Sash from the Windows Programs Menu"

### Launching Sash from the Command Line

You can also launch Sash using the batch or shell script files (`sash.bat` and `sash.sh`, respectively) which are located in OC4J OCMS installations at ORACLE_HOME/sdp/sash/sbin and on JBoss Application Server installations at jboss-4.0.5.GA/sdp/sash/sbin.

OCMS provides the following shortcut for launching Sash from the command line:

`launch_sash.sh` (UNIX)

`launch_sash.bat` (Windows)

This shortcut is located at ORACLE_HOME/sdp/bin on OC4J OCMS installations and at JBOSS_HOME/sdp/bin on JBoss Application Server installations.

#### Secured and Unsecured Connections to JBoss Application Server

JBoss Application Server supports both secured and unsecured installations. Unsecured installation do not require authentication credentials to connect to the JBoss MBean Server and JMX Console. In secure installations, users must provide user names and passwords to connect to the JBoss MBean Server and JMX Console. In the Sash command line, the `auth` flag denotes secured connections from Sash to JBoss and has the effect of prompting users for user names and passwords. The syntax is as follows:

    #sash--jboss auth

In unsecured JBoss deployments, the Sash command line is invoked with the `noauth` flag, meaning that users do not have to provide authentication credentials. The syntax is as follows:

    #sash--jboss noauth

The `auth` and `noauth` flags are determined by whether the JBoss instance has been configured in a secured mode. If you use the Launch Sash option of Oracle Communications and Mobility Server, then the `auth` and `noauth` flags are set appropriately for the environment based on information provided during the OCMS installation.

### Connecting Sash to an External OCMS Instance

By default, Sash connects to the local instance of OCMS. If needed, you can override this default behavior and connect Sash to external instances of OC4J or to another instance of Oracle Application Server, or JBoss Application Server.

#### Connecting to an External Instance of OC4J

Sash connects to the OCMS server through RMI. Example 5-1 illustrates how to connect Sash to a server with the host IP address 10.0.0.234.

Example 5-1 Connecting Sash to OCMS

    sash#–-host 10.0.0.234

When you connect to OC4J, Sash prompts you for a username and a password. The user name is the same as that for OC4J administrator (oc4jadmin). The password is the same as the password associated with the OC4J administrator. Once you log in, the Sash command prompt (`sash`) appears. An error message displays if the login is unsuccessful.

#### Connecting Sash to an External Oracle Application Server Instance

To connect Sash to an external instance of the Oracle Application Server, use the `--ias` option and then add `-- port` followed by the port number for OPMN (Oracle Process and Management and Notification) server. Example 5-2 illustrates how to connect to an external instance of the Oracle Application Server.

Example 5-2 Connecting to an External Instance of the Oracle Application Server

    sash#--ias --port 6003

When you connect to the server, enter the administrator user name and password.

Tip:

The OPMN request port is configured in the `opmn.xml` configuration file under ORACLE_HOME/opmn/conf/opmn.xml.

#### Connecting Sash to an External JBoss Application Server Instance

To connect Sash to an external instance of the JBoss Application Server, use the `--jboss` option and enter host number. For example, to connect to an application server with the host IP address of 10.0.0.234, enter the following:

    #sash--jboss -- host 10.0.0.234

When you connect to the server, enter the administrator user name and password (if prompted).

## Using Sash

There are two groups of Sash commands: commands that create, delete and update system objects and commands that query the system for information.

### Viewing Available Commands

Entering `help` displays a list of all available commands in the server (described in Table 5-1). The list of commands varies depending on the components deployed to the server.

Table 5-1 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.company.com privateId=alice` `delete` – Deletes a communication identity from the system. For example: `publicIdentity delete publicId=sip:alice@test.company.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. OCMS 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 (illustrated in Example 5-3).

Example 5-3 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. For example, the overview of the account command illustrated in Example 5-3 notes `[no aliases]` for 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 listed in Table 5-1 to provision a user account to the TimesTen In-Memory 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 AOR (Address of Record), 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.

Once 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`#, illustrated in Example 5-4) by creating an OCMS user known as alice using the commands described in Table 5-1.

1. Create a user using the `privateIdentity` command as follows:

       privateIdentity add privateId=alice

2. Create the public identity for alice by entering the SIP address:

       publicIdentity add publicId=sip:alice@test.company.com privateId=alice

3. Add an account for alice and use one of the optional commands described in Table 5-1 to set the status of the account. To create an active account for alice, enter the following:

       account add uid=alice active=true

   Note:

   OCMS Version 10.1.3.2 requires that the `uid` be in lower-case. Oracle Communicator users provisioned using OCMS Version 10.1.3.2 must also enter their account names in lower case during login. OCMS Version 10.1.3.3 supports mixed-case `uid`s. However, Oracle Communicator users can only log in by entering their user name exactly as it was provisioned. For example, if you define the `uid` as Alice, then the user must login as Alice. If you upgrade to 10.1.3.3 from 10.1.3.2, users provisioned in 10.1.3.2 must continue to log in using lower case.

4. 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"

5. Add user authentication credentials for alice:

       credentials add uid=alice realm=test.company.com password=welcome1

   `realm` and `password` are only needed to store authentication information in the TimesTen In-Memory database (accessed through the OCMS LoginModule). The `credentials` command is not needed for applications configured to use the RADIUS Login Module to authenticate users against RADIUS servers. Fore more information on these login modules, see Chapter 6, "OCMS Security".

   Note:

   You must also configure `realms` using the SIP Servlet Container MBean before you use Sash to add authorization credentials to a user. For more information, see "Configuring the SIP Servlet Container MBeans".

Example 5-4 Creating a User from the Sash Command-Line Prompt

    sash# privateIdentity add privateId=alice
    sash# publicIdentity add publicId=sip:alice@test.company.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.company.com password=welcome1

Tip:

You can create multiple users by creating Sash batch files. For more information, 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 Subscriber Data Services application. For information on accessing application-defined MBeans, see "Accessing the MBeans for a Selected SIP Application".

To create a user:

1. Select the execute operation. The Operation page for the execute operation appears.

2. Enter privateIdentity add privateId=alice in the Value field (Figure 5-2).

3. 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.

Figure 5-2 Creating a User with the Command Service MBean

Description of "Figure 5-2 Creating a User with the Command Service MBean"

See "CommandService" for more information on executing Sash commands through Application Server Control.

### 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 OCMS 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@company.com role="Location Service" realm=company.com password=welcome1

Note:

The `realm` and `password` attributes are only needed for applications configured to authenticate users against the TimesTen In-Memory database through the OCMS Login Module. 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@company.com role="Location Service"

See Chapter 6, "OCMS Security" for more information on the login modules.

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 as illustrated in Example 5-4.

#### Deleting a User Account with the identity delete Command

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 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

## Provisioning the XDMS Using Sash

The commands for provisioning the XDMS are included in the `xcap` group. Each of these commands is preceded by `xcap`. The XDMS commands within the `xcap` group that support user provisioning are included in the `user` and `applicationUsage` subgroups. You can provision XDMS from the Sash prompt or by using the CommandService MBean that is provided with the Presence application.

### Provisioning XDMS User Accounts Using the CommandService MBean

You can provision XDMS using the execute command provided by the CommandService MBean that is registered to the Presence application (Figure 5-3). Use the CommandService MBean's execute operation as described in "Creating a User with the Command Service MBean" to provision accounts to the XDMS. For more information on the MBean itself, see "Command Service (XDMS Provisioning)".

Figure 5-3 Using the CommandService MBean for XCAP Account Management

Description of "Figure 5-3 Using the CommandService MBean for XCAP Account Management"

### Provisioning XDMS User Accounts from the Sash Prompt

To use the XDMS commands to provision users and application usages from the Sash prompt, you must first connect to an XDMS-consuming application such as Presence by entering `sash -a <application name>` from the command prompt (Figure 5-4).

Note:

You connect to the XDMS-consuming application through a command prompt, such as the Windows command shell (`Cmd.exe`). You cannot connect to these applications directly from the Sash prompt.

For example, to connect to the Presence application:

1. From the command prompt, navigate to the `\sbin` directory that contains the Sash executable. This file is located at Oracle_HOME\sdp\sash\sbin.

2. Enter the name of the Presence application using `sash -a presenceapplication`. For example, enter the following:

       c:\product\10.1.3.2\ocms\sdp\sash\sbin>sash -a presenceapplication

3. When prompted, login to Sash using your OC4J administrator name and password.

4. From the Sash command prompt, enter an XDMS command, such as `xcap user list`.

Figure 5-4 Connecting to the Presence Application

Description of "Figure 5-4 Connecting to the Presence Application"

### Using xcap Commands

This section describes how to manage user accounts and application usages using the `xcap` group of commands.

#### Provisioning XDMS User Accounts

The `add`, `delete` and `list` commands enable you to manage user accounts on the XDMS.

#### Adding XDMS Users

The `xcap user add` command adds an XDMS user with the given user name and application usage. For example, to add a user from the Sash prompt, enter:

    sash# xcap user add userName=<string> applicationUsage=<string>

Caution:

Do not use the `add` command if the XDMS is configured to automatically create users.

#### Removing an XDMS User

The `xcap user delete` command removes an XDMS user with the given user name from the application usage. For example, to delete a user from the Sash prompt, enter:

    sash# xcap user delete userName=<string> [ appusages=<string> ]

The application usage parameter (`appusages`) is optional. If no application usage is specified, then the user is removed from all application usages. When the server is configured to automatically create a user, the `delete` command removes all existing documents.

#### Searching for Application Usage for an XDMS User

The `xcap user appusages` command returns all the application usages applicable to a given user. To review the application usages assigned to a user, enter the following from the Sash prompt:

    sash# xcap user appusages userName=<string>

#### Listing XDMS Users

The `xcap user list` command returns all of the XDMS users in the system, or optionally returns the XDMS users for a given application usage.

    sash# xcap user list [ all=<true|false> ] [ appusage=<string> ]

If the optional `all` parameter is not set, then the resulting display is limited to a maximum of 100 users.

#### Provisioning Application Usage

The commands for provisioning of XDMS application usage are in the `appusage` group (`xcap appusage`).

#### Listing All Application Usages

The `xcap appusage list` command returns all the application usages on the server. For example, enter the following from the Sash prompt:

    sash# xcap appusage list

## 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.

  Example 5-5 illustrates a text file called ocsm_users.txt, which contains a group of users defined with the `identity add` command. You can provision these users by entering `-f ocms_users.txt` from the Sash prompt:

  Example 5-5 Creating Users from a Text File (ocms_users.txt)

      identity add publicId=sip:alice@doc.oracle.com privateId=alice role=user password=1234 realm=doc.oracle.com
      identity add publicId=sip:bob@doc.oracle.com privateId=bob role=user password=1234 realm=doc.oracle.com
      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
      identity add privateId=gretchen publicId=sip:gretchen@doc.oracle.com role=user password=1234 realm=doc.oracle.com
      identity add privateId=hans publicId=sip:hans@doc.oracle.com role=user password=1234 realm=doc.oracle.com
      identity add privateId=imogen publicId=sip:imogen@doc.oracle.com role=user password=1234 realm=doc.oracle.com
      identity add privateId=jack publicId=sip:jack@doc.oracle.com role=user password=1234 realm=doc.oracle.com

- `-- 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.

## Error Logging in Sash

If a command encounters an error while executing, the error message is written to the ERROR log level, while success messages are written to the INFO log level.

By default, Sash uses two log4j appenders: one that listens on INFO log level, and one that listens on the ERROR (or greater) log level. The latter is configured to output the log level before any message. For example, you can locate an error message by searching the message for the `[ERROR]` string. The first appender is directed to `stdout` and the second is directed to `stderr` in the default configuration. The Sash logging output can be configured in the `log4j.xml` file located at ORACLE_HOME/sdp/sash/conf directory. For more information on log4j, see Chapter 10, "Configuring the Logging System".