GroupWise and Multi-Factor Authentication (MFA)

Published 8/24/2022, Actively Updated 2/21/2023 (Work in Progress)


This document is relevant to GroupWise 18.4 and beyond and is specific to Multi-Factor Authentication. Note the following:

  • Although MFA was available in GroupWise 18.3, it was new and there were lots of problems with the MFA implementation.
  • MFA was not available in any earlier versions of GroupWise prior to 18.3.
  • If you want to use MFA, plan on installing GroupWise 18.4.2 at a minimum.
  • As with most of my technical guides, this is a work in progress, and I add/modify as I am able to.


  • Most people assume MFA is a simple implementation that controls the end-user login behavior.  But when you implement MFA in a GroupWise environment, there are many different components that are impacted that you may not realize.
  • MFA introduces complex elements to your environment that change the behavior of the Admin Console, GroupWise Agent Screens, the GroupWise Client, GroupWise Web, GroupWise Mobility, GroupWise Messenger, and possibly other 3rd party products that connect to GroupWise such as Retain Archiving.
  • You cannot just enable a checkmark to magically turn MFA on.  MFA for GroupWise requires a separate server called the NetIQ Advanced Authentication server to be installed and configured. To an experienced person, it's not a huge deal, to anyone that has never dealt with this before, it can be extremely overwhelming. The learning curve is quite severe, and documentation is lacking in many areas.
  • There are architectural and security concerns that must be addressed. While the Advanced Authentication server does have policies and configurations to secure the system, there are some limitations that could require an additional proxy server to help secure and restrict access from the outside.
  • With GroupWise, you receive entitlements for a limited license of the Advanced Authentication server.  Depending on what "Methods" you choose to use, you may be required to purchase licenses or 3rd party subscriptions. "Method" means the way you receive the code that serves as the 2nd Authentication piece.  For example, SMS Text Messages is an included method with the GroupWise limited license, but you will need to pay for a 3rd party texting service for this to function.
  • An MFA implementation is what I would consider a significant project that requires adequate planning, implementation time, and testing before rolling out to an entire user base. It could take several weeks or even months to fully implement. I say this because you need to be realistic in your expectations about a project like this.


Here's what you need to successfully implement GroupWise MFA.

  • A GroupWise 18.4.2+ system.  It doesn't matter if it's on Windows or Linux. It doesn't matter if you have a single post office or if you have 20. MFA is designed to work with any GroupWise 18.4.2 system regardless of scale.
  • LDAP Authentication must be utilized in your GroupWise environment.
  • A NetIQ Advanced Authentication Server. Installed as a virtual appliance.
  • If you're using GroupWise Mobility, you should also be running GroupWise Mobility 18.4.2
  • If you're using GroupWise Messenger, you should also be running GroupWise Messenger 18.4.2
  • If you're using GroupWise GWWEB, you should be running the latest GWWeb version (Currently 18.4.2)
  • If you're using an older version of GroupWise WebAccess, you should abandon it and switch to GWWEB.  WebAccess can be used with MFA, but it does not natively support it. It is considered an "UI-Less" endpoint and requires this to be entered for the password:  Password + & + MFACode.
  • If you're using Retain Archiving, you should be running the latest version, 4.10 (?).
  • If you are using any services that require authentication from the public internet (Such as GWWEB or the GroupWise Client), you should utilize a reverse proxy server on your network perimeter to control and restrict access to sensitive areas of the Advanced Authentication server from the public Internet. This can be done with an Ubuntu server running the NGINX proxy, or can also be done with some firewalls. This is a complex topic that is very critical to understand. More on this later.
  • Depending on how your users authenticate with the GroupWise Client, you may be required to fully roll out the GroupWise 18.4.x client to your users to be successful with MFA.  Clients older than version 18.3 are not MFA aware and generally cannot authenticate when MFA policies are enabled.

Other 3rd Party MFA Solutions and GroupWise

GroupWise only supports MFA being implemented via the NetIQ Advanced Authentication Server. It does not support 3rd party solutions such as Duo or Okta. Note the following:

  • Unsure what the right term is, but the NetIQ Advanced Authentication Server is the Master / Authoritative Source for the process used by GroupWise. Duo and Okta also want to be the Master source. What this means is that even if you tried to integrate into a 3rd party solution,  you will end up with 2 systems that want to be in full control of the process.
  • Theoretically -- Through some of the more advanced NetIQ Methods, it may be possible to spawn a task from the Advanced Auth Server to another solution, however it adds another complex layer to the mix. Unless you have a significant amount of experience working with this type of solution, you're probably better off not going this route.
  • I have worked extensively trying to get GroupWise, NetIQ Advanced Authentication Server, and Okta's MFA solution to work.  I spent weeks and weeks working with Technical resources at both Micro Focus and Okta trying to get various methods of integration configured and we were not successful. We ended up scrapping that process and using simpler native methods to get the project on track.
  • You might think "Gosh, I would think that I could just connect to a different system like DUO, it shouldn't be that hard."   It doesn't work that way. GroupWise is very tightly connected to the NetIQ server and there are currently no supported integration options for other vendors.

GroupWise Mobility & MFA

When it comes to an MFA implementation and GroupWise, it's important to understand that GroupWise Mobility + MFA is an absolute beast. This is the area where you will likely find the most frustration and problems with your user base.  Here are some bullet points of things you must consider:

  • MFA for GroupWise is currently for the most part ALL or Nothing.  You cannot require users to use an MFA code for GWWEB but not use MFA on GroupWise Mobility.  Note: There is some gray area here so for the purposes of this doc, it's all or nothing. Various scenarios may need to be tested and explored to determine if the resulting behavior is adequate for your security needs.
  • There is a single asterisk item in the GroupWise documentation that outlines the entire requirements for MFA and GroupWise Mobility. You'll never find it if you're looking for it, and when you see it you won't really understand the implications unless you're dealing with it first-hand. This is because it doesn't really highlight that it applies to Mobility, and someone with no experience with MFA would likely not make the connection. It really needs 3-4 pages of mainstream discussion but it's just not there.  This is the line I am referring to that can be found at this link.   It's in the footnotes of the table of all Methods and where/how they are supported within GroupWise:
    • * - indicates that the Auth Method needs to be appended to the LDAP password when authenticating using “&” and then the Auth Method. For example: password&authmethod.

Because of the minimal mentions of GMS in the documentation, it is easy to make assumptions about the behavior of GMS. To understand it better, we should compare how GMS works with and without MFA implemented. Refer to the table below:

GroupWise Mobility Without MFA

GroupWise Mobility WITH MFA

Server Name In the email configuration on your smartphone, you provide the server name (and port number if not 443). No Change
Login Name Login name is the same as you use to login with GroupWise client or GWWEB. No Change but does require LDAP Associated accounts (See next item)
LDAP/ Standalone On the backend of GroupWise, the username could be a standalone GroupWise user or it could be tied to an LDAP source such as eDirectory or Active Directory. GMS now uses the same authentication source that GroupWise uses, so this is determined by your specific GroupWise configuration. Requires the account be connected to an LDAP source used to Authenticate the user to GroupWise. Standalone GroupWise accounts will not work for MFA.
Password On your smartphone, you enter the same password you use to login to the GroupWise client or GWWEB On your smartphone, because there is no way to trigger an MFA dialog, you must enter the password and the MFA code into the password field as a single line of text.  You must also delimite the two with the ampersand (&).  For example:


If your password is ILoveFido and your MFA code is 515084, then you would enter this into the password field on your phone:


If your password is GroupWiseRocks and your MFA code is 081231, then you would enter this into the password field on your phone:


If you fail to enter using this format, you will have an abundance of problems with synching items on your phone.  You "might" not get an error if you do not enter the above, however your phone will likely not sync correctly.

GMS User Web Portal If you're familiar with the GMS admin page at x.x.x.x:8120 that the administrator uses, you may also know that when you login as a standard user, there are a few options available that control what folders and contacts are synced to their phones. Without MFA, you just use the standard name and password. With MFA enabled, this user portal also requires the same format as in the row above. Otherwise, you will not be able to login.
GMS Admin Portal The GMS admin portal at x.x.x.x:8120 uses either the linux root account or actual user accounts that have been defined as admins. In both cases it simply uses the password for the account to login. Root user does not require MFA.  Other defined admin users, that are actual GroupWise users, will be required to enter their credentials the same way as listed in the two previous rows using password&code. They must also be LDAP associated users in GroupWise.
Password Changes If a GroupWise password changes, the new password is entered into the smartphone and life goes on. Fact 1: LDAP is required for MFA to work.
Fact 2: Many organizations have policies that require periodic LDAP password changes.
Fact 3: LDAP Password changes and how it impacts GMS will become the bane of your existence causing lots of end user confusion and frustration. When a password changes, the new password PLUS a new MFA token must be entered into the smartphone. If users simply enter their passwords, the results could be unpredictable, but the phones will likely not sync.  The new password should be entered in the same format as when setting the password in the first place.  As before, you must use the ampersand (&) delimiter between the new password and the mfa code. For example:


MFA Methods, their Licensing Nuances, and Practical Use for GroupWise.

In the MFA world, the "Method" refers to how the 2nd authentication step is delivered. It could be a text message on someone's phone, a code from an authenticator app, or more.  The NetIQ Advanced Authentication server gives you about 25 different methods to choose from. Finding one that works for you would seem simple, but it's not. There are many considerations.

As a matter of terminology, OTP = One Time Password. When used, OTP means you receive a password from the method of choosing that has to be entered as part of the MFA authentication process.

Licensing MFA Methods

Since the NetIQ Advanced Authentication Server is a separate product, it also has it's own licensing outside of GroupWise. There are two ways to license it for use with GroupWise:

  1. License the full Advanced Authentication Server system and all methods. This requires an additional purchase. My understanding is that you license all or nothing, you don't license on an individual method basis. Note that there is a short trial period where all methods are available. This allows you to do some testing to determine if specific methods work better for you than others. If I recall, the trial license only allows up to 10 users to be managed.
  2. GroupWise AA Limited Use License. This limited license is included with your GroupWise entitlements, as long as you are current on your GroupWise 18 Maintenance. The Limited Use License provides full use of the following six (6) methods for GroupWise:
    1. Email OTP
    2. Emergency Password
    3. LDAP Password
    4. OATH OTP
    5. Password
    6. SMS OTP

Nuances with the GroupWise Limited Use License

While it would appear that having 6 methods available to you should be more than adequate, what you will soon realize is just how worthless most of these methods are to a GroupWise implementation. Let me explain each one below:


Discussion and Thoughts

Email OTP There is a certain amount of irony with this method since the end goal is to access your email. But if you must receive an email with the OTP just to be able to access your email, you create a catch-22 situation. The way to deal with this could be to use a different email address (Such as gmail) to receive the code. This is viable and it does work, and you would need to determine if this is feasible for your organization.

Real World Experience:  Customers I have implemented MFA for regard this method as grossly impractical. They do not want to force their user base to utilize a completely second email system just to support their GroupWise environment.

Side Note: This method won't work with GroupWise Mobility Service or any other UI-Less Endpoint because GMS cannot trigger the event that causes the email to be sent.

Emergency Password Overview and Usage: The emergency password is for special occasions only. It's not for standard everyday use. The password will likely expire and must be reset whenever you need to use it.

Per the documentation: The Emergency Password method facilitates the use of a temporary password for users if they lose a smartcard or forget their smartphone. Only a helpdesk administrator can enroll the Emergency Password method for users.

Real World Experience: In my opinion, this option is terrible. Yes it can work in a pinch. No it's not easy or friendly or easy to manage. It puts extra strain on your IT Helpdesk or administrative staff. Users are not able to enroll or set their own emergency password, someone with "Help Desk" level permissions on your Advanced Auth server has to do it.  And because of how the password generally expires, you will likely have to get your help desk involved EVERY TIME this function needs to be used.

Side Note: This method is one of the few options you have for the required authentication using GroupWise Mobility Service when the MFA security option is set to "Required". Generally speaking, when an LDAP password changes (See my note above about how LDAP enabled accounts are required for MFA to work properly), it is required that you enter the new password, the ampersand sign, and the new MFA token all as a single string into your Smartphone password field in order to continue to sync your phone.  If this is the method you use, which again, is one of the only methods that will work, you must plan for the extra administrative overhead that will be inevitable.

LDAP Password The LDAP Password method is not a supported option for GroupWise and MFA. Why it is included in the GroupWise Limited license is a bit of a mystery, unless there is some architectural requirement for the backend connection to be made to LDAP for user management.
OATH OTP Overview and Usage: The OATH OTP method allows you to use Google Authenticator (Or other standard authenticators) to generate a time-based OTP (TOTP). Essentially, you have an authenticator app on your phone, and that app is registered with the Advanced Authentication Server. The code changes roughly every 30 seconds and can be used as the MFA token for your GroupWise implementation.

Real World Experience: From a practical standpoint, this is the only method that can be used across the board for all endpoints. It's simple to use and relatively painless. The downside is that I have seen some organizations hesitant to force their users to download an app on their personal smartphones to be used for business purposes. User training is also a potential issue, however more and more services *everywhere* are requiring MFA and many of them also use Authenticator Apps to supply the MFA code.

Side Note: While it has its own set of challenges, this is what I have found to be the best Method for use with GroupWise Mobility Service and other UI-Less End Points.  The biggest challenge I run into with this is that when you are on your phone trying to update your password+&+MFACode, you have to switch back and forth between the email app and the Authenticator app, and you have to do it in a way that allows you to get the entire thing entered before the 30 seconds expires.  This can be extremely frustrating to many users and cause a great amount of stress on both the end user and the help desk staff.

Verdict: This is my recommended method for most use cases. It is the only Limited License Method that can be practical for use with all GroupWise endpoints.

Password Overview and Usage: This method essentially allows the users to set a 2nd password that can then be used as the MFA token. However, there is some implied risk by using this method. If that 2nd password were to get compromised along with their LDAP password, the entire purpose of MFA is defeated.

From the Docs: "NOTE: Do not use the Password method in chains that contain only one factor. You must always combine the Password method with other factors."  With GroupWise Mobility it would be impossible to meet this requirement.

From the GroupWise Team: I was told that this method would be viable to get around the challenges of MFA + GroupWise Mobility. This is because the user would just have to enter their password + & + the 2nd password they set. So it would not be difficult for them to remember or manage. When discussing the above statement from the docs, they suggested that if you use the Password Method, only use it in the UI-Less configuration chains. This will allow you to utilize it for GroupWise Mobility but would not allow it to be used with things like GWWEB or the GroupWise Client. In theory this would be a nice balance between security and practicality.

Real World Experience: While this method allows the user to manage the passcode, and it does not expire, there will be some user pushback and extra overhead implementing and managing this on an ongoing basis. Also it is important to consider the security implications should that password get compromised since it does not change unless the user actually changes it (which won't ever happen).

SMS OTP Overview:  Users receive a Text Message on their phones with the MFA code. The users must be enrolled and have their phone number saved in the system for it to work. This is a relatively simple and easy to implement Method and works pretty well. Of the 6 licensed methods with the GroupWise limited licenses, it's one of 2 that are actually viable for most day-to-day usage (Except GMS, see below).

From the Documentation: In the SMS OTP authentication method, a one time password (OTP) is sent with the SMS text to the user’s phone. The user receives the OTP and enters it on the device where the authentication is happening. The OTP must be used within a specific time frame.

Considerations: There are several things to understand about the SMS TXT Method:

  1. The enrollment process requires a valid phone number that must be confirmed when the user is enrolling. By default, this is not automatic out of the gate, but I have been successful at configurations that automate this by pulling the info from LDAP, if it exists.
  2. You must subscribe to a separate 3rd party SMS Texting service for this method to work. It will not work without a service. By default, Twilio and Messagebird are officially supported vendors, and other vendors can be used with some configuration. I have used Clicksend and it works well. You pay a small fee for every text message sent.
  3. Depending on the SMS Texting vendor, it can require a bit of testing to get the formatting right. The parameters that the Advanced Authentication Server uses has to be mapped to the vendors own syntax and that can sometimes be problematic.
  4. If the SMS Texting vendor is down, it will cause interruptions to your authentication process. You have no control over the stability of their systems and this can be frustrating at times.

Real World Experience:  This method works relatively well. It's simple to figure out, and most people understand it. Many people already get SMS Text codes for other websites and applications they use.  I have seen some organizations hesitate to use this method because pushback from users and them not wanting to have "any" work related items on their personal phones. Or the users do not want to provide their personal phone numbers to *any* system regardless of the purpose or reasoning behind it.

Side Note: This will not work with GroupWise Mobility since GMS does not have the ability to trigger the SMS Text OTP.

Security Note: Especially with this method, it is critical to secure the enrollment page and prevent access to it from the outside. The reason is that if someone's LDAP password were compromised, in theory someone could login and enroll to the SMS TXT method using a rogue telephone number, essentially hijacking the users account and have access to MFA codes as well. Another recommendation would be to have the phone numbers populated in LDAP so they can be automatically published (and not changed) in the Advanced Authentication server. This would also prevent rogue numbers from being used.