Configure BlackBerry Mobile Data System for Kerberos Authentication to a web site

Article ID: KB15642

Type: Support Content

Last Modified: 11-02-2012

 

Product(s) Affected:

  • BlackBerry Enterprise Server
CollapseEnvironment
  • BlackBerry Enterprise Server 4.1 and 5.0
  • Microsoft Internet Information Services (IIS)
CollapseOverview

To configure the BlackBerry Mobile Data System (BlackBerry MDS) for Kerberos authentication to a web site hosted on a web server requiring Kerberos Authentication to login, complete the following steps:

  1. Ensure that the Web Server supports Kerberos authentication ; (Refer to the web server's guide on configuring kerberos as the authentication mechanism)
  2. Configure the BlackBerry MDS Connection Service to support Kerberos authentication as follows:
  • Ensure the BlackBerry MDS Connection Service has the Support HTTP Authentication option set to True by completing the following steps:

   For BlackBerry Enterprise Server 4.1:
         1. In BlackBerry Manager, select <BlackBerry_Enterprise_Server_name>_MDS-CS_1.
         2. Click Edit Properties
         3. In the Properties window, click HTTP.
         4. Under Authentication set the Support HTTP Authentication to True.


  For BlackBerry Enterprise Server 5.0
         1. Open the BlackBerry Administration Service.
         2. Expand the BlackBerry Solution topology.
         3. Expand the component view.
         4. Select MDS connection service.
         5. Select the http tab.
         6. Set authentication support enabled to yes.
         7. If you change this configuration, you will need to restart the BlackBerry MDS service in the Windows Services window.

When this is set to True, the BlackBerry MDS Connection Service will prompt the BlackBerry smartphone user for credentials and pass this information to the relevant authentication service on behalf of the BlackBerry smartphone user.

When this option is set to False, the BlackBerry smartphone user will be prompted for credentials to authenticate directly with the web server's internal security database and not through an external authentication service. For instance, if the web site is configured for Basic Authentication, instead of, or as well as, Integrated Authentication.

  • Amend the MDSLogin.conf file.

The MdsLogin.conf file is the Java Authentication and Authorization Service (JAAS) pluggable authentication configuration file. A description of this file can be found in the Sun Microsystems Java Development Kit (JDK) document. Go to http://www.sun.com and search for Where to Specify Which Login Configuration File Should Be Used to learn more about the JAAS Login Configuration File.


 BlackBerry MDS Connection Service uses 3 login modules.

  • com.sun.security.auth.module.Krb5LoginModule - Sun Microsystems Kerberos 5 login module for JAAS. This module is used for Kerberos authentication.
  • net.rim.security.auth.module.ntlm.NtlmLoginModule - Research In Motion® (RIM) NTLM login module for JAAS. This module is used for NTLM authentication.
  • net.rim.security.auth.module.pwd.PwdLoginModule - RIM clear password login module for JAAS. This module is used for network authentication mechanisms using clear passwords, such as HTTP Basic authentication. 
  • The <flag> entered for each option can take one of the 4 values: optional, request, Requisite and Sufficient. For a complete explanation of the <flag> please go to http://www.sun.com and search for javax.security.auth.login class configuration.

   The LoginModule options are module specific; each module has its own set of options. For details of options in Sun Microsystems Kerberos module please go to http://www.sun.com and search for Class Krb5LoginModule.

Configure the MDSLogin.conf file to include your domain name. This will populate the domain field for the BlackBerry smartphone user when they are prompted for credentials on their BlackBerry smartphone. Complete the following steps:

  1. On the BlackBerry Enterprise Server, go to C:\Program Files\Research In Motion\BlackBerry Enterprise Server\MDS\Servers\servername\config.
  2. Open the MDSLogin.conf file in a text editor.
  3. Edit the MDS_Default section by replacing COMPANY.COM with your domain name.

    Note: If the domain name starts with a number, surround the domain name with quotes ("")
  4. If you wish to force a particular authentication type you can change the relevant optional entry to required
     
     Save and close the file.
     
    C. Configure the krb5.conf file to include details relevant to your specific Microsoft Active Directory environment as follows:
        On the BlackBerry Enterprise Server navigate to C:\Program Files\Research In Motion\BlackBerry Enterprise Server\MDS\Servers\servername\config.

 

  1. Open and edit the krb5.conf in a text editor.

    The default sections and entries contained within this file are as follows:
    [libdefaults]
    default_tkt_enctypes = des-cbc-md5 ; or des-cbc-crc
    default_tgs_enctypes = des-cbc-md5 ; or des-cbc-crc
    [realms]
    # change COMPANY.COM to your Kerberos realm
    # change KDC:88 to the hostname:port of KDC
    COMPANY.COM = {
    kdc = your_kdc.your_domain.com:88}
  2. Replace the COMPANY.COM entry under the [realms] section with your domain name. Ensure this entry is in UPPER case. 
  3. Enter the Fully Qualified Domain Name (FQDN) of the KDC within your Microsoft Active Directory environment and port number (if changed from the default of 88). Ensure host names and domain names are in lower case. 
  4. Restart the BlackBerry MDS Connection Server service in Windows Services.
CollapseAdditional Information

Kerberos is an authentication system developed at the Massachusetts Institute of Technology (MIT). Dependent on the complexity of your Microsoft Active Directory environment, further sections and entries may be required within the krb5.conf file. For full details of possible further sections and entries that each section can contain can be referenced at the MIT website at the following location:

http://web.mit.edu/kerberos/www/krb5-1.3/krb5-1.3.3/doc/krb5-admin.html#krb5.conf

In large, complex Microsoft Active Directory environments, multiple realms sections may be required for your computer to be able to communicate with the KDC for each realm. The tag must be given a value in each realm subsection in the configuration file, or there must be valid Domain Name System service (DNS SRV) records specifying the KDCs. However, the [libdefaults] section may require a default realm entry which identifies the default Kerberos realm for the BlackBerry Enterprise Server.

Also, the session key encryption types that are set as default in the krb5.conf file that is installed during the BlackBerry Enterprise Server installation, are contained under the [libdefaults] section:

[libdefaults]

default_tkt_enctypes = des-cbc-md5 ; or des-cbc-crc

default_tgs_enctypes = des-cbc-md5 ; or des-cb
c-crc

From the MIT website the definition of these encryption types are as follows:

des-cbc-md5 = DES cbc mode with RSA-MD5

des-cbc-crc = DES cbc mode with CRC-32

Please note that additional session key encryption key types may be required within the krb5.conf file if your environment supports or require additional key types. See the following website for details:

http://java.sun.com/javase/6/docs/technotes/guides/security/jgss/jgss-features.html

For instance starting from Java SE 6, Java GSS/Kerberos support the RC4-HMAC encryption type, therefore this encryption type can be added to the krb5.conf under the [libdefaults] section:

[libdefaults]

default_tkt_enctypes = des-cbc-md5 ; or des-cbc-crc; or rc4-hmac

default_tgs_enctypes = des-cbc-md5 ; or des-cbc-crc; or rc4-hmac

Note: Incorrect or invalid encryption types within the krb5.conf file can result in HTTP 500 errors when attempting to browse to websites that require Kerberos authentication.

Disclaimer

By downloading, accessing or otherwise using the Knowledge Base documents you agree:

   (a) that the terms of use for the documents found at www.blackberry.com/legal/knowledgebase apply to your use or reference to these documents; and

   (b) not to copy, distribute, disclose or reproduce, in full or in part any of the documents without the express written consent of RIM.


Visit the BlackBerry Technical Solution Center at www.blackberry.com/btsc.