Code sample: Authentication and initializing the web services

Visit https://github.com/blackberry/BWS-Samples to copy the full code sample to your development tool. This topic highlights and explains key sections of the code that are used to authenticate the application with the BlackBerry Administration Service and initialize the BWS and BWSUtil web services. This topic refers to lines 1 to 265 and the main method of the code sample.

Before you run the code sample, verify that you have completed the configuration tasks described earlier in this guide. Also, verify that your project includes the System.Web.Services reference.

Define metadata

The following code defines the metadata that describes the application's requests to the BlackBerry Web Services. This includes the client version of the BlackBerry Web Services, locale information, the computer that hosts the BlackBerry Administration Service, and the login information for the administrator account that the application uses. You must specify the host name, user name, and password values in the main method (the last section of the code sample). The variables are defined as global variables.

The code also defines a RequestMetadata object to use for initialization. This object is defined as a global variable.

// The request Metadata information.
// This is the version of the WSDL used to generate the proxy, not the version of the server.
private const string ClientVersion = "<client_version>";

/*
* To use a different locale, call getLocales() in the BWSUtilService web service
* to see which locales are supported.
*/
private const string Locale = "en_US";
private const string OrgUid = "0";
private static readonly RequestMetadata Metadata = new RequestMetadata();

// Authentication type name.
private const string AuthenticatorName = "BlackBerry Administration Service";

// Hostname to use when connecting to web service.
private static string BWSHostName = null; // e.g. BWSHostName = "server01.yourcompany.net".
private static string Username = null; // e.g. Username = "admin".
private static string Password = null; // e.g. Password = "password".

From the main method:

// Hostname to use when connecting to web service.
BWSHostName = "<BWSHostName>"; // e.g. BWSHostName = "server01.yourcompany.net".
Username = "<username>"; // e.g. Username = "admin".
Password = "<password>"; // e.g. Password = "password".

Assign values to the Metadata global object

The following code assigns the values of the metadata global variables to the Metadata global object.

Metadata.clientVersion = ClientVersion;
Metadata.locale = Locale;
Metadata.organizationUid = OrgUid;

Initialize and set the URL properties of the web services

The following code initializes and sets the values for the URL properties of the web services so that the application can connect to the BlackBerry Web Services.

logMessage("Initializing BWS web service stub");
bwsService = new BWSService();
logMessage("BWS web service stub initialized");
logMessage("Initializing BWSUtil web service stub");
bwsUtilService = new BWSUtilService();
logMessage("BWSUtil web service stub initialized");
// These are the URLs that point to the web services used for all calls.
bwsService.Url = "https://" + BWSHostName + "/enterprise/admin/ws";
bwsUtilService.Url = "https://" + BWSHostName + "/enterprise/admin/util/ws";

Configure timeout properties

The following code configures a 60 second connection timeout for the BlackBerry Web Services.

// Set the connection timeout to 60 seconds.
bwsService.Timeout = 60000;
bwsUtilService.Timeout = 60000;

Define the authenticator object

The following code defines the Authenticator object that the application requires for the overall authentication and initialization process. In the two sections following this code, the application uses the authenticator object to collect the login information and the encoded user name that the application uses to authenticate with the BlackBerry Web Services.

Authenticator authenticator = GetAuthenticator(AuthenticatorName);
if (authenticator != null)
{
	string encodedUsername = GetEncodedUserName(Username, authenticator);
	if (!string.IsNullOrEmpty(encodedUsername))
	{
		/*
		* Set the HTTP basic authentication on the BWS service.
		* BWSUtilService is a utility web service that does not require
		* authentication.
		*/
		bwsService.Credentials = new NetworkCredential(encodedUsername, Password);

		/*
		* Send an HTTP Authorization header with requests after authentication
		* has taken place.
		*/
		bwsService.PreAuthenticate = true;
		returnValue = true;
	}
	else
	{
		logMessage("'encodedUsername' is null or empty");
	}
}
else
{
	logMessage("'authenticator' is null");
}

Authenticate with the BlackBerry Web Services

The following code retrieves the encoded login information for the BlackBerry Administration Service administrator account that the application uses, and authenticates the application with the BlackBerry Web Services.

public static string GetEncodedUserName(string username, Authenticator authenticator)
{
	const string methodName = "GetEncodedUserName()";
	const string bwsApiName = "bwsUtilService.getEncodedUsername()";
	logMessage("Entering {0}", methodName);
	string returnValue = null;

	GetEncodedUsernameRequest request = new GetEncodedUsernameRequest();
	request.metadata = Metadata;
	request.username = username;
	request.orgUid = Metadata.organizationUid;
	request.authenticator = authenticator;

	CredentialType credentialType = new CredentialType();
	credentialType.PASSWORD = true;
	credentialType.value = "PASSWORD";
	request.credentialType = credentialType;

	GetEncodedUsernameResponse response = null;

	try
	{
		logRequest(bwsApiName);
		response = bwsUtilService.getEncodedUsername(request);
		logResponse(bwsApiName, response.returnStatus.code, response.metadata);
	}
	catch (WebException e)
	{
		// Log and re-throw exception.
		logMessage("Exiting {0} with exception \"{1}\"", methodName, e.Message);
		throw e;
	}

	if (response.returnStatus.code.Equals("SUCCESS"))
	{
		returnValue = response.encodedUsername;
	}
	else
	{
		logMessage("Error Message: \"{0}\"", response.returnStatus.message);
	}

	logMessage("Exiting {0} with value \"{1}\"", methodName, returnValue == null ? "null" :
		returnValue);
	return returnValue;
}

After the authentication and initialization process completes, the BlackBerry Web Services are ready to accept API calls from the application.



Was this information helpful? Send us your comments.