Oracle® Communications Converged Application Server Administration Guide Release 5.0 Part Number E17647-03 |
|
|
View PDF |
This chapter describes how to use the Sapphire Shell (Sash) utility to create database users for Oracle Communications Converged Application Server. This chapter includes the following sections:
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 Oracle Fusion Middleware 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.
The Sash launcher script is located in the same folder that contains the start and stop scripts for Converged Application Server.
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.
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.
Sash connects to the Converged Application Server server through RMI. Example 4-1 illustrates how to connect Sash to a server with the host IP address 10.0.0.234.
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.
There are two groups of Sash commands: commands that create, delete and update system objects and 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.
Entering help
displays a list of all available commands in the server (described in Table 4-1). The list of commands varies depending on the components deployed to the server.
Table 4-1 Shapphire 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:
|
credentials |
Command for managing credentials. |
None |
Subcommands include:
|
|
Enables you to create a basic user account. |
None |
None. See "Creating a User with the Identity Add Command" for more information. |
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 4-2).
Example 4-2 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 4-2 notes [no aliases]
for 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.
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 4-1 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.
This section illustrates how to create a user from the Sash command prompt (sash
#, illustrated in Example 4-3, "Creating a User from the Sash Command-Line Prompt") by creating an Converged Application Server user known as alice using the commands described in Table 4-1.
Create a user using the privateIdentity
command as follows:
privateIdentity add privateId=alice
Create the public identity for alice by entering the SIP address:
publicIdentity add publicId=sip:alice@test.company.com privateId=alice
Add an account for alice and use one of the optional commands described in Table 4-1 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.company.com password=welcome1
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 Oracle Communications Converged Application Server Security Configuration Guide.
Note:
You must also configurerealms
using the SIP Servlet Container MBean before you use Sash to add authorization credentials to a user.Example 4-3 shows the Sash commands for creating a user.
Example 4-3 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".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.
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@company.com role="Location Service" realm=company.com password=welcome1
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@company.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 as illustrated in Example 4-3, "Creating a User from the Sash Command-Line Prompt".
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:
Theidentity 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.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 4-4 illustrates a text file named ocsm_users.txt, which contains a group of users defined with the identity add
command. You can provision these users by entering -f OWLCS_users.txt
from the Sash prompt:
Example 4-4 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
-- 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.
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_5_0
).