Authentication methods for the BlackBerry Enterprise Server User Administration Tool

Supported authentication models

In BlackBerry® Enterprise Server 5.0 and later, the models for authentication (login) and authorization (roles or permissions) for administration are different from the models that were used in previous versions.

BlackBerry Enterprise Server 5.0 and later supports the following authentication models:

  • BlackBerry Administration Service authentication (default)
  • Microsoft® Active Directory® authentication
  • single sign-on authentication for the BlackBerry Administration Service (uses Microsoft Active Directory authentication)
  • IBM® Lotus® Domino® mailbox authentication (Lotus Domino environment only)
  • Novell® GroupWise® mailbox authentication (Novell GroupWise environment only)

BlackBerry Enterprise Server 5.0 and later does not support Windows® authentication or Microsoft® SQL Server® authentication.

You must create one of the following administrators with sufficient credentials to authenticate with the BlackBerry Administration Service:
  • administrator in the BlackBerry Administration Service
  • administrator in Microsoft Active Directory
  • mailbox administrator (Lotus Domino and Novell GroupWise environments only)

Roles or permissions that are based on database user accounts are not supported in BlackBerry Enterprise Server 5.0 and later.

For more information about how to create a BlackBerry Administration Service administrator, visit www.blackberry.com/go/serverdocs to read the BlackBerry Enterprise Server Administration Guide.

Default authentication method for the BlackBerry Administration Service

If you do not specify authentication credentials when you type a command in the BlackBerry Enterprise Server User Administration Tool, the tool tries to log in to the BlackBerry Administration Service using your Windows® authentication credentials. You can also specify the -sso_auth parameter if you want the tool to log in to the BlackBerry Administration Service using your Windows authentication credentials.

Authentication credentials

In the BlackBerry® Enterprise Server User Administration Tool 5.0 and later, you can use the following parameters interchangeably:
  • "-username" or "-sqluser" (authentication user name)
  • "-password" or "-sqlpass" (authentication password)

The BlackBerry Enterprise Server User Administration Tool uses the values associated with these options for the authentication and authorization models that are supported in the BlackBerry® Enterprise Server. The tool does not support Microsoft® SQL Server® authentication or roles or permissions that are defined on the Microsoft SQL Server database engine.

If you do not specify authentication credentials when you type a command in the BlackBerry Enterprise Server User Administration Tool, the tool tries to log in to the BlackBerry Administration Service using your Windows® authentication credentials. You can also specify the -sso_auth parameter if you want the tool to log in to the BlackBerry Administration Service using your Windows authentication credentials.

Syntax for authentication credentials

In the BlackBerry® Enterprise Server User Administration Tool, the variable <credentials> represents the user name, password, and domain that you use for authentication with the BlackBerry Administration Service.

The BlackBerry Enterprise Server User Administration Tool uses the following syntax for authentication credentials.

Item

Description

-username <user name>

-sqluser <user name>

authentication user name

-password <password>

-sqlpass <password>

authentication password

-sso_auth

use instead of the user name and password parameters if you want the tool to log in to the BlackBerry Administration Service using your Windows® authentication credentials. If you do not specify authentication credentials when you type a command, by default, the tool tries to log in to the BlackBerry Administration Service using your Windows authentication credentials even if you do not specify the -sso_auth parameter.

-domain <domain>

authentication domain

-bas_auth

use BlackBerry Administration Service authentication

-mailbox_auth

use IBM® Lotus® Domino® mailbox authentication (Lotus Domino environment only)

-gw_auth

use Novell® GroupWise® mailbox authentication (Novell GroupWise environment only)

-ad_auth

use Microsoft® Active Directory® authentication

Setting authentication credentials

You can configure the BlackBerry Enterprise Server User Administration Tool to retrieve a set of stored authentication credentials from an .xml configuration file when you use specific subparameters.

Note: This method should only be used when you need to maintain backwards compatibility for existing application integrations for versions of the tool that are earlier than version 5.0.

Storing an encrypted set of authentication credentials

The BlackBerry® Enterprise Server User Administration Tool uses the -set_client_auth <credentials> -set_p <password> command to store authentication credentials in an .xml configuration file. You can then use the -p subparameter in the tool to extract the credentials from the .xml configuration file and insert the credentials into the command line options. The configuration file is located at <drive>:\Documents and Settings\<user_name>\Local Settings\Application Data\Research_in_Motion_Ltd\BESUserAdminClient.exe_Url_<serial_number>\<version>\user.config. The -set_client_auth command must be set for each administrator account that you want to use stored credentials.

Example

BESUserAdminClient -set_client_auth "-username jpalmer -password password1 -ad_auth -domain test.rim.net" -set_p password

Extracting credentials that are stored in the configuration file

The BlackBerry® Enterprise Server User Administration Tool uses the -p <password> command to extract and decrypt credentials that are stored in the configuration file and then insert the credentials into the command line options.

Example

BESUserAdminClient -p password1 -status

This runs the following command:

BESUserAdminClient -username jpalmer -password password1 -ad_auth -domain test.rim.net -status

String value requirements

To specify -set_client_auth values that contain characters in double quotation marks, you must surround the entire string with double quotation marks. You must use a set of quotation marks to escape every embedded set of characters that are in double quotation marks.

Example: Using double quotation marks to specify a work location nickname for a user

If you have two users with the same name, Julie Palmer, one of whom works in Waterloo and the other in New York, you can specify the work location for the user as a nickname.

BESUserAdminClient -username \"Julie \"\"Waterloo\"\" Palmer\" -password password -status

You store this option and value in the configuration file using the following command:

BESUserAdminClient -set_p password1 -set_client_auth "-username ""Julie \"\"Waterloo\"\" Palmer"" -password password"

Use cases

In all the following examples, you log on to the computer that hosts the BlackBerry® Enterprise Server User Administration Tool using the following credentials:
  • User name: NTLMU1
  • Password: NTLMP1

BlackBerry Enterprise Server User Administration Tool version 4.1.x

BlackBerry Enterprise Server User Administration Tool version 5.0 and later

Run the following command: BESUserAdminClient -p password1 -sqluser SQLU1 -sqlpass SQLP1...

Initial configuration (perform once):
  1. Create a BlackBerry Administration Service administrator with the following credentials:
    • User name: SQLU1
    • Password: SQLP1
  2. Save the BlackBerry Administration Service administrator credentials in the configuration file using the following command: BESUserAdminClient -set_client_auth "-bas_auth" -set_p password1

Then run the following command: BESUserAdminClient -p password1 -sqluser SQLU1 -sqlpass SQLP1....

Example: Running a command using Windows authentication

BlackBerry Enterprise Server User Administration Tool version 4.1.x

BlackBerry Enterprise Server User Administration Tool version 5.0 and later

Run the following command: BESUserAdminClient -p password1...

Initial configuration (perform once):
  1. Create a BlackBerry Administration Service administrator with the following credentials:
    • User name: BASU1
    • Password: BASP1
  2. Save the BlackBerry Administration Service administrator credentials in the configuration file using the following command: BESUserAdminClient -set_client_auth "-username BASU1 -password BASP1 -bas_auth" -set_p password1

Then run the following command: BESUserAdminClient -p password1

Example: Changing the authentication credentials in the configuration file to a Microsoft Active Directory user

BlackBerry Enterprise Server User Administration Tool version 4.1.x

BlackBerry Enterprise Server User Administration Tool version 5.0 and later

Not applicable

Run the following command:

BESUserAdminClient -set_client_auth "-username ADU1 -password ADP1 -ad_auth -domain D1" -set_p password1

Example: Changing the client password

BlackBerry Enterprise Server User Administration Tool version 4.1.x

BlackBerry Enterprise Server User Administration Tool version 5.0 and later

  1. Remove the existing BlackBerry Enterprise Server User Administration Tool service.
  2. Re-install the service using the new client password.

Run the following command:

BESUserAdminClient -set_client_auth "-username ADU1 -password ADP1 -ad_auth -domain D1" -set_p password2

Example: Overriding the requirement to use authentication credentials in the configuration file

BlackBerry Enterprise Server User Administration Tool version 4.1.x

BlackBerry Enterprise Server User Administration Tool version 5.0 and later

Not applicable

Run the following command:

BESUserAdminClient -username username1 -password password1..

Was this information helpful? Send us your comments.