Skip Navigation
  1. BlackBerry Docs
  2. BlackBerry Web Services 12.10
  3. Blackberry Web Services Development Guide
  4. Using BlackBerry Web Services APIs
  5. Sample walkthrough: Authenticating with the BlackBerry Web Services

Sample walkthrough: Authenticating with the 
BlackBerry Web Services

The following section examines the 
AuthenticationSample.java
 application available at https://github.com/blackberry/BWS-Samples. This application demonstrates the different methods for authenticating with 
BlackBerry UEM
.
Before an application can make calls to the 
BlackBerry Web Services
, the application must initialize the BWS and BWSUtil web services and authenticate with the web services using the login information of an administrator account. When the BWS and BWSUtil web services are initialized, they accept subsequent API calls from the application.
Administrator accounts can use one of the following authentication methods:
  • Local user authentication (that is, non-directory users)
  • Microsoft Active Directory
     authentication
  • LDAP authentication
Although the sample application also includes an option for SSO authentication, this feature is not supported in 
BlackBerry UEM
 and is only included to support 
BlackBerry Enterprise Service 10
.
Administrators select the authentication method when they create new administrator accounts. Single sign-on authentication requires an administrator to complete additional configuration steps. For more information about creating an administrator account, the different authentication types, and configuring single sign-on authentication, see the BlackBerry UEM Documentation.

Define metadata

Like any 
BlackBerry Web Services
 request, you must first define the metadata that describes the application's requests. Each metadata object specifies the locale, client version, and organization ID data. The inclusion of this metadata supports forward and backward compatibility with different versions of 
BlackBerry Web Services
. To learn more about metadata values such as the 
ClientVersion
, 
Locale
, and 
OrgUid
, see the API Reference overview.
Here's an example of how to create the 
RequestMetadata
 object and declare the variables used for authentication: 
// The request Metadata information. This is the version of the WSDL used to generate the proxy,
// not the version of the server.
private final static String CLIENT_VERSION = "<Client Version>"; // e.g. CLIENT_VERSION = "12.6.0"

// The enum used to determine the current server type.
private enum ServerType { Unknown, BDS, UDS, BES12 };

// Enum used to determine the server used in this execution
private static ServerType _serverType = ServerType.Unknown;
/*
* To use a different locale, call getLocales() in the BWSUtilService web service to see which locales are
* supported.
*/
private final static String LOCALE = "en_US";
private final static String ORG_UID = "0";
private final static RequestMetadata REQUEST_METADATA = new RequestMetadata();

Get the login information

Next, the app retrieves the encoded login information and domain data (if necessary) for the administrator account that the application uses to authenticate with the 
BlackBerry Web Services
, and defines the possible log data and status messages.
public static String getEncodedUserName(String username, Authenticator authenticator,
        CredentialType credentialType, String domain) throws WebServiceException {
        
    final String METHOD_NAME = "getEncodedUserName()";
    final String BWS_API_NAME = "_bwsUtil.getEncodedUsername()";
    logMessage("Entering %s", METHOD_NAME);
    String returnValue = null;

    GetEncodedUsernameRequest request = new GetEncodedUsernameRequest();
    request.setMetadata(REQUEST_METADATA);
    request.setUsername(username);
    request.setOrgUid(REQUEST_METADATA.getOrganizationUid());
    request.setAuthenticator(authenticator);

    request.setCredentialType(credentialType);
    request.setDomain(domain);

    GetEncodedUsernameResponse response = null;
    try {
        logRequest(BWS_API_NAME);
        response = _bwsUtil.getEncodedUsername(request);
        logResponse(BWS_API_NAME, response.getReturnStatus().getCode(),response.getMetadata());
    } catch (WebServiceException e) {
        // Log and re-throw exception.
        logMessage("Exiting %s with exception \"%s\"", METHOD_NAME, e.getMessage());
        throw e;
    }

    if (response.getReturnStatus().getCode().equals("SUCCESS")) {
        returnValue = response.getEncodedUsername();
    } else {
        logMessage("Error Message: \"%s\"", response.getReturnStatus().getMessage());
    }

    if (Base64.isBase64(returnValue))
    {
        logMessage("Decoded value of encoded username \"%s\"", 
            StringUtils.newStringUtf8(Base64.decodeBase64(returnValue)));
    }
    else
    {
        logMessage("Value of encoded username \"%s\"", returnValue);
    }
    logMessage("Exiting %s", METHOD_NAME);
    return returnValue;
}

Perform an echo call

To verify that the app can call and get a response from the 
BlackBerry Web Services
, you can call 
BWS.echo()
. The following code demonstrates how to call 
echo()
 and handle the return value.
public static boolean echo() throws WebServiceException {
    final String METHOD_NAME = "echo()";
    final String BWS_API_NAME = "_bws.echo()";
    logMessage("Entering %s", METHOD_NAME);

    boolean returnValue = true;

    EchoRequest request = new EchoRequest();
    EchoResponse response = null;

    request.setMetadata(REQUEST_METADATA);
    request.setText("Hello World!");

    try {
        logRequest(BWS_API_NAME);
        response = _bws.echo(request);
        logResponse(BWS_API_NAME, response.getReturnStatus().getCode(),
        response.getMetadata());
    } catch (WebServiceException e) {
        if (e.getCause() instanceof HTTPException) {
            HTTPException httpException = (HTTPException) e.getCause();
            // Handle authentication failure.
            if (httpException != null && httpException.getResponseCode()
                == HttpURLConnection.HTTP_UNAUTHORIZED) {
                returnValue = false;
                logMessage("Failed to authenticate with the BWS
                web service");
                logMessage("Exiting %s with value \"%s\"", METHOD_NAME,
                returnValue);
                return returnValue;
            }
        }

        // Log and re-throw exception.
        logMessage("Exiting %s with exception \"%s\"", METHOD_NAME,
        e.getMessage());
        throw e;
    }

    logMessage("Exiting %s with value \"%s\"", METHOD_NAME, returnValue);
    return returnValue;
}

Provide the server name and port number

To authenticate with 
BlackBerry Web Services
 you must first specify the FQDN of the computer that hosts the 
BlackBerry UEM
 along with the port number.
public static void main(String[] args) throws IOException {
    // Return codes
    final int SUCCESS = 0;
    final int FAILURE = 1;

    int returnCode = SUCCESS;

    // Hostname to use when connecting to web service. Must contain the fully
    // qualified domain name.
    String bwsHostname = "<bwsHostName>"; // e.g. bwsHostname = "server01.example.net".
        
// Port to use when connecting to web service. The same port is used to access the
// management console prior to BES12. Default ports: BES10 BDS=38443, BES10 UDS=18082, BES12=18084
String bwsPort = "<bwsPort>"; // e.g. bwsPort = "18084".
Next, you can select the authentication method that you want to use. In this example, local user authentication is always called, in addition to the directory method that you select below. To select a method, set the option to 
true
 and the other options to 
false
. For example, for LDAP sign-on authentication, set use 
useLDAP = true
 and 
useAD = false
.
// Select which authentication methods you would like to test by setting the variables to true
boolean useAD = false; // Active Directory
boolean useLDAP = true; // LDAP
The following sections describe each of the different authentication methods described above. You can configure the section that corresponds to your selected authentication method with your own credentials.

Local user authentication

The following code defines the login information for local users (otherwise known as non-directory users). Specify the 
<username>
 and 
<password>
 values for the administrator account.
// The BlackBerry Administration Service Credentials to use
String username = "<username>"; // e.g. username = "admin".
String password = "<password>"; // e.g. password = "password".
String authenticatorName = "BlackBerry Administration Service";
String domain = null; // not needed

Microsoft Active Directory
 authentication

The following code defines the login information for 
Microsoft Active Directory
 authentication. Specify the 
<username>
, 
<password>
, and 
<domain>
 values.
// The Active Directory Credentials to use
String username = "<username>"; // e.g. username = "admin".
String password = "<password>"; // e.g. password = "password".
String authenticatorName = "Active Directory";
// Only BDS requires domain for authentication
String activeDirectoryDomain = null;
if(_serverType == ServerType.BDS){
activeDirectoryDomain = "<domain>"; // e.g. activeDirectoryDomain = "example.net"

LDAP authentication

The following code defines the login information for LDAP authentication. Specify the 
<username>
 and 
<password>
 values.
// The LDAP Credentials to use
String username = "<username>"; // e.g. username = "admin".
String password = "<password>"; // e.g. password = "password".
String authenticatorName = "LDAP";
String domain = null; // not needed

Authenticate with the 
BlackBerry Web Services

The following code tests whether the application can authenticate with the 
BlackBerry Web Services
 using the login information that you specified.
private static boolean demonstrateBwsSetupAndAuthenticatedCall(String bwsHostname, String bwsPort,
        String username, String password, String domain, String authenticatorName,
        CredentialType credentialType) throws WebServiceException {
    boolean returnCode = false;
    logMessage("Initializing web services...");
    if (setup(bwsHostname, bwsPort, username, password, authenticatorName, credentialType, domain)) {
            
        /*
        * It is anticipated that the first time through this method, _serverType will be unknown. So getSystemInfo()
        * will populate this value, which will be used in the subsequent demonstrate calls if required.
        */
        if(_serverType == ServerType.Unknown){
            getSystemInfo();
        }
            
        /*
        * Demonstrate authenticated call to _bws.echo() API.
        */
        logMessage("Attempting authenticated BWS call to echo()...");
        if (echo()) {
            logMessage("Authenticated call succeeded!");
            returnCode = true;
        } else {
            logMessage("Authenticated call failed!");
        }
    } else {
        logMessage("Error: setup() failed");
    }
    return returnCode;
}

Assign values to the Metadata global object

The following code assigns the metadata values to the Metadata object.
private static boolean setup(String hostname, String bwsPort, String username, String password,
        String authenticatorName, CredentialType credentialType, String domain) {
    final String METHOD_NAME = "setup()";
    logMessage("Entering %s", METHOD_NAME);
    boolean returnValue = false;
    REQUEST_METADATA.setClientVersion(CLIENT_VERSION);
    REQUEST_METADATA.setLocale(LOCALE);
    REQUEST_METADATA.setOrganizationUid(ORG_UID);

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
.
URL bwsServiceUrl = null;
URL bwsUtilServiceUrl = null;

try {
    // These are the URLs that point to the web services used for all calls.
    // e.g. with no port:
    // https://server01.example.net/enterprise/admin/ws
    // e.g. with port:
    // https://server01.example.net:18084/enterprise/admin/ws
    String port = "";

    if (bwsPort != null) {
        port = ":" + bwsPort;
    }

    bwsServiceUrl = new URL("https://" + hostname + port + "/enterprise/admin/ws");
    bwsUtilServiceUrl = new URL("https://" + hostname + port + "/enterprise/admin/util/ws");

} catch (MalformedURLException e) {
    logMessage("Cannot initialize web service URLs");
    logMessage("Exiting %s with value \"%s\"", METHOD_NAME, returnValue);
    return returnValue;
}

// Initialize the BWS web service stubs that will be used for all calls.
logMessage("Initializing BWS web service stub");
QName serviceBWS = new QName("http://ws.rim.com/enterprise/admin", "BWSService");
QName portBWS = new QName("http://ws.rim.com/enterprise/admin", "BWS");
_bwsService = new BWSService(null, serviceBWS);
_bwsService.addPort(portBWS, "http://schemas.xmlsoap.org/soap/", bwsServiceUrl.toString());
_bws = _bwsService.getPort(portBWS, BWS.class);
logMessage("BWS web service stub initialized");

logMessage("Initializing BWSUtil web service stub");
QName serviceUtil = new QName("http://ws.rim.com/enterprise/admin", "BWSUtilService");
QName portUtil = new QName("http://ws.rim.com/enterprise/admin", "BWSUtil");
_bwsUtilService = new BWSUtilService(null, serviceUtil);
_bwsUtilService.addPort(portUtil, "http://schemas.xmlsoap.org/soap/", bwsUtilServiceUrl.toString());
_bwsUtil = _bwsUtilService.getPort(portUtil, BWSUtil.class);
logMessage("BWSUtil web service stub initialized");

// Set the connection timeout to 60 seconds.
HTTPClientPolicy httpClientPolicy = new HTTPClientPolicy();
httpClientPolicy.setConnectionTimeout(60000);

httpClientPolicy.setAllowChunking(false);
httpClientPolicy.setReceiveTimeout(60000);

Client client = ClientProxy.getClient(_bws);
HTTPConduit http = (HTTPConduit) client.getConduit();
http.setClient(httpClientPolicy);

client = ClientProxy.getClient(_bwsUtil);
http = (HTTPConduit) client.getConduit();
http.setClient(httpClientPolicy);

Define the authenticator object

The following code defines the Authenticator object that the application requires for the overall authentication and initialization process.
Authenticator authenticator = getAuthenticator(authenticatorName);
if (authenticator != null) {
    String encodedUsername = getEncodedUserName(username, authenticator, credentialType, domain);
    if (encodedUsername != null && !encodedUsername.isEmpty()) {
        /*
        * Set the HTTP basic authentication on the BWS service. BWSUtilService is a utility web service that
        * does not require authentication.
        */
        BindingProvider bp = (BindingProvider) _bws;
        bp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, encodedUsername);
        bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, password);

        returnValue = true;
    } else {
        logMessage("\"encodedUsername\" is null or empty");
    }
} else {
    logMessage("\"authenticator\" is null");
}

logMessage("Exiting %s with value \"%s\"", METHOD_NAME, returnValue);
return returnValue;