In this section, we will go over the GroupWise preparations needed for GroupWise Mobility Service.
Creating the Trusted App
The Mobility Service acts as a GroupWise Trusted Application. This is an application that shares a “key” with the GroupWise system to bypass the need for passwords for individual users. You create the Trusted App key in ConsoleOne. You need at least GroupWise 8 SP1 HP1 snapins to perform the steps as listed here. All GroupWise 2012 snapins work for our purposes. Here are the steps:
- Open ConsoleOne and connect to your primary domain.
- Click on the GroupWise System to the left, and then choose Tools|GroupWise System Operations|Trusted Applications.
- Click Create to start a new Trusted App setup. Enter the following information:
- Name: The name of your Trusted Application. This must be unique to your system. We have named ours “Mobility”
- Description: Enter a description so that later you will know what this application is used for.
- TCP/IP Address: We have found that attempting to limit the IP address for GroupWise Mobility Service results in failure of the GroupWise Sync Agent to properly talk to the Post Office Agent. At this point we recommend that you leave this field blank.
- Requires SSL: Choose here if you wish to require SSL for the application. We recommend that you leave this unchecked for now. This gives you the ability to test and work through issues as you need to.
- Do not chose Message Retention.
- Enter a file location for the text file that will be created. This will contain a long string of characters that will be used by GroupWise Mobility Service installation. Your file location will likely be on the local server or workstation, and you will copy it to GroupWise Mobility Service server prior to installation.
- Enter the name of your Trusted App key file. This can be truly any file name you desire. Just don’t lose the file! Otherwise, you’ll have to create a new Trusted App key the next time you install GroupWise Mobility Service from scratch.
Choosing a Contact Post Office Agent
GroupWise Mobility Service relies on a “Contact” Post Office Agent to authenticate users. This can be any Post Office Agent in your system. Essentially this is what happens: When a user is added to GroupWise Mobility Service, the GroupWise Sync Agent contacts the defined Post Office Agent, and asks for the Post Office for the user in question. This is then written into the database for that user.
This Contact POA can be anywhere. It uses the same type of redirection table for SOAP as POAs use for redirecting client requests on port 1677. There is only one location for a POA in the GroupWise Sync Agent setup. While any POA can be used, it is best to choose one in “close network” proximity to GroupWise Mobility Service, and also is reliably available.
Enabling SOAP for GroupWise Mobility Service
The GroupWise Mobility Service GroupWise Sync Agent uses the Post Office Agent SOAP protocol to do its synchronization.
SSL and SOAP
You can create your own SSL certificate (a self-signed certificate) or purchase a certificate for your Post Office Agent.
An SSL certificate is issued by a “Certificate Authority”. There are many recognized SSL Certificate Authorities. Just a few names to float around are Verisign, Comodo, GoDaddy, DigiCert and Thawte (and we know there are many more, but it’s way beyond the scope of this guide to list them all). When you purchase a certificate from one of these providers, you are not only purchasing an encryption certificate, but a “trust relationship”. Most web browsers and mail clients will “trust” certificates created by these authorities as being genuine, and assuming there are no other problems (name mismatches, expiration dates, and the like), the web browser or email client will not complain, and “trust” that certificate for encryption. I’m sure most of you have encountered a “questionable” certificate in surfing the web. You are presented with a window that says the certificate might not be valid, and a request that you confirm or deny whether you wish to continue.
By virtue of having a GroupWise system (at least prior to GroupWise 2014/Windermere), you have at least ONE Certificate Authority of your own – your eDirectory certificate server. You may also have a separate CA on a Windows or Linux server, even your new Mobility server. And it’s perfectly reasonable for you to use one of these if you wish.
You can choose whether you wish to purchase a certificate based on your organization’s policies, or you can generate your own certificate. If your POA is only being used for internal communications between GroupWise components, there is really no need to purchase an SSL Certificate. You can easily just create your own self-signed certificate for your POA to use in communicating via SOAP over SSL with the Mobility Service’s GroupWise Sync Agent.
Novell’s documentation on this is fairly clear, so we will not reinvent the wheel here. You can find their steps here: http://www.novell.com/documentation/groupwise2012/gw2012_guide_admin/data/ak9e3ju.html (section 83.2 of GroupWise 2012 Administration Guide).
Just for clarity, here are the basic steps that are outlined in the Novell documentation:
- Create a Certificate Signing Request. This is really just a file that you send to the certificate authority (or then use yourself if you choose to create a self-signed certificate) in order to have your certificate generated. (See step 83.2.1 in the Novell documentation).
- If you choose to purchase a certificate, the authority must be able to provide the certificate in Base64/PEM or PFX format.
- If you choose to generate your own certificate, follow the instructions beginning with step 83.2.2.
Enabling SOAP at the POA and Verifying SSL Settings
Now we will ensure that SOAP is turned on. You may have other processes, such as GroupWise 2012 WebAccess or a BES that already use SOAP. If this is the case, then you will be good to go! We will go over these steps now.
- In ConsoleOne, change the drop-down list in the GroupWise view to show Post Office Agents.
- Edit the properties of your POA.
- Click the triangle on the GroupWise tab, and change to Agent Settings.
- Click the “Enable SOAP” box to turn on SOAP.
- The default for “Max SOAP threads” is 20. This cannot be increased. It can, however, be decreased if you wish to reduce overhead on the POA. The POA will start with four SOAP threads, and add more as needed, up to the Max stated here.
- Click on the triangle again (now where it says Agent Settings), and change to Network Address. Verify that SOAP shows port 7191 for the Internal SOAP port (or change it as necessary if you wish to use a different port). If you intend to enable SSL for this Post Office Agent, set the SSL to “required” or “enabled”.
- To enable SSL, you also have to indicate the location of the certificate file. Copy the files that were generated in the SSL Certificates Section above to a location on the server so that they are accessible by the POA.
- Click on the triangle again (now where it says Network Address), and go to SSL Settings. Enter the location for both the certificate and key which was received, and if necessary, enter the certificate password.
- Click OK to save all of your changes.
- Restart your POA.
- You can test that the POA is now listening for SOAP connections by opening a command prompt on Windows, or a terminal window on Linux and typing the following
telnet ipaddressofpoa 7191
You should see a connection like that shown below.
telnet 192.168.100.238 7191
Connected to 192.168.100.238.
Escape character is ‘^]’.
Some versions will go on to show similar info:
Date: Sat, 20 Mar 2013 16:55:54 GMT
Server: Linux GroupWise POA 8.0.2
You may also quickly receive a disconnect from the server, and that’s okay!
NOTE: If you are using Windows versions newer than Vista, the Telnet Client is not enabled by default. It’s a good utility for all administrators to have, and is available though Control Panel|Programs|Turn windows features on or off. Then on the list that appears simply check the box beside Telnet Client.
Creating an eDirectory Group or GroupWise Distribution List for Mobility Users
There are two ways to add users to GroupWise Mobility Service installation: individually adding users and adding a group of users. If you are using LDAP Provisioning, the group is an eDirectory group. If you are using GroupWise Provisioning, this is done via a GroupWise Distribution List. We recommend that you create a group or distribution list (perhaps just named “Mobility”) and assign users to that group who will need to have access to GroupWise Mobility Service. Once you have a group defined for your Mobility users, you can add and remove users from this group to easily control the access to GroupWise Mobility Service. If, however, your GroupWise userids and eDirectory userids are not the same and you use LDAP provisioning, we have found that using the eDirectory group is unreliable. See more information in the section entitled “Managing Mobility Service Users”. If you use GroupWise provisioning, make the visibility of your distribution list “invisible” if you wish to prevent it from being seen in the address book.
Understanding the Relationship between LDAP and the Mobile Server
There is one small idiosyncrasy of GroupWise Mobility Service, at least from a GroupWise perspective: While it appears that Novell assumes that all sites are using LDAP authentication for their users, and that all GroupWise users are eDirectory users (and not External Entities!), we’ve found in our travels that this is just not the case. Over half of the sites we surveyed (and a quarter of sites over 500 users) do NOT use LDAP authentication for GroupWise. Add to that the number of GroupWise External Entities that we have encountered, and some currently configured GroupWise sites will have trouble using LDAP provisioning and authentication. However, as we discussed in the prior chapter, this is no longer a requirement, and if you have no additional needs for LDAP with regards to the Mobility Service, you can use GroupWise provisioning and authenication.
Since GroupWise requires eDirectory for administration, most GroupWise sites have eDirectory as the primary LDAP server. Of course, GroupWise allows sites to use this LDAP server (i.e. eDirectory) to act as the authentication mechanism for GroupWise clients, bypassing the GroupWise password entirely. For these sites, GroupWise users created as GroupWise External Entities bypass the LDAP authentication, and are redirected to native GroupWise authentication. This allows both eDirectory users and GroupWise External Entities to coexist in a GroupWise system that relies on LDAP authentication.
If you use LDAP authentication for the Device Sync Agent, users who have separate GroupWise and eDirectory passwords will be required to enter their eDirectory password on their devices to authenticate to Mobility. If you wish to allow External Entities and Resources to use GroupWise Mobility Service, you must use GroupWise Authentication. This is okay even if you are using LDAP authentication for your GroupWise POA itself. Basically, when you turn on GroupWise authentication, the password that the POA accepts (whether the native GroupWise password or the LDAP password associated with the user) is what Mobility uses.
Converting GroupWise External Entities to eDirectory Users
As stated above, as long as you use GroupWise Authentication in the Device Sync Agent, External Entities can access their GroupWise data through GroupWise Mobility Service. If for some reason you do not wish to use GroupWise authentication, but require GroupWise External Entities have access to GroupWise Mobility Service, you will need to first convert the External Entity to an eDirectory user. Here are the steps:
- Find the GroupWise External Entity in your eDirectory tree.
- Right-click on the External Entity to be converted.
- Choose GroupWise Utilities|GW/eDirectory Association.
- Choose Convert External Entity to User.
- You may receive an IDM driver warning at this time. If you are using the IDM driver for your GroupWise system, follow the instructions given.
- You will asked to verify that you wish to convert the External Entity to an eDirectory user, choose Yes.
- Edit the properties of the new User object and assign a password for the user to use for GroupWise Mobility Service authentication.
After you have completed these steps, the GroupWise user will have access to GroupWise Mobility Service for device synchronization.
Preparing Users for GroupWise Mobility Service
Another by-product of using LDAP provisioning for GroupWise Mobility Service occurs when you have users who have an eDirectory userid that does not match the GroupWise userid. For example, my eDirectory ID is danitaz, and my GroupWise Userid is dzanre. If this is the case in your organization, you will need to write down the eDirectory and GroupWise userids for later when you are preparing GroupWise Mobility Service for use.
While we recommended the convenience of using eDirectory groups to enable Mobility users when using LDAP provisioning, there is one instance where we have found eDirectory groups to be problematic. That is when the user’s eDirectory ID does not match the GroupWise Userid. While it is perfectly acceptable for your two IDs to be different, we have found that adding such users via an eDirectory group is unreliable. In fact, in recent GroupWise Mobility Service installations (using the most recent code available), each time we have attempted this, the only way to get devices to actually synchronize was to delete the user from the eDirectory group, wait until the user clears from GroupWise Mobility Service, and then add the user in again manually, making certain to set the “Application Name” at the time of user addition (this will be discussed in more detail in the chapter on “Administering GroupWise Mobility Service”.