28 Jul Modern Authentication
Recently, our institution implemented Microsoft Modern Authentication to enable security controls that the university can implement to reduce the risk of compromised credentials with two-factor authentication for any service that contains sensitive, restricted data or otherwise. Modern Authentication enables Active Directory Authentication Library (ADAL) based sign-in for Exchange and client applications across different platforms. This enables sign-in features such as Multi-Factor Authentication(MFA), smart card, and certificate-based authentication. Modern authentication is an umbrella term for a combination of authentication and authorization methods between a client (for example, your laptop or your phone) and a server, as well as some security measures that rely on access policies.
This impacts Exchange and corresponding mail & calendaring software like Microsoft Outlook, Apple Mail, Apple Calendar, and lesser-used applications like BusyCal, Spark, etc. It also impacts collaboration software like Microsoft Skype for Business, Microsoft Teams, and cloud service Microsoft Office 365.
This implementation will be done in two phases. The first phase is to migrate all campus staff & faculty to modern authentication all mail client software depending on our campus Exchange infrastructure. The second phase is to require two-factor authentication (2FA) for all mail/calendaring client, and software and software depending on Exchange or Microsoft Office 365.
Modern authentication includes the following primary components:
- Authentication Methods
Multi-factor authentication (MFA); smart card authentication; client certificate-based authentication
- Authentication Methods
- Authorization Methods
Microsoft’s implementation of Open Authorization (OAuth)
- Authorization Methods
- Conditional Access Policies
Mobile Application Management (MAM) and Azure Active Directory (Azure AD) Conditional Access
Modern Authentication is the term Microsoft uses to refer to its implementation of the OAuth 2.0 authorization framework for client/server authentication. Modern Authentication leverages Active Directory Authentication Libraries (ADAL) to enable applications to support sign-in features like two-factor authentication (2FA/MFA) certificate-based Authentication. OAuth 2.0 also includes the use of access and refresh tokens to validate the authentication requests and reduce the number of times users receive a prompt to re-authenticate with primary credentials and as a consequence, perform 2FA. OAuth started around 2006, with the development of the Twitter OpenID implementation. In 2007, a Google group was created with a small group of implementers to write a proposal for an open protocol. Initially, it was developed to provide API to delegate authentication. Over the years, OAuth has evolved with its direct handling of non-website services. OAuth has built-in support for desktop applications, mobile devices, set-top boxes, and of course websites. Many of the protocols today use a shared secret hardcoded into your software to communicate, something which poses an issue when the service trying to access your private data is open source. OAuth is about giving access to your stuff without sharing your identity at all (or its secret parts).
With our migration to “modern authentication” it was difficult to find any documentation from Apple on what version initiated support in the operating system (macOS or iOS) or Apple mail & calendar, etc. information. Hopefully, Apple will improve this documentation in the future, but currently, you have to parse through developer articles and look for hints on what is or isn’t support and what version of the operating system. For example, there wasn’t anything in the macOS Deployment Guide to OAuth / Modern authentication.
However, Apple does document the availability of “OAuth” for macOS 10.14 Mojave and later in the “ExchangeWebServices” payload in Device Management documentation on the Apple Developer site.
For manually configured Exchange accounts in macOS 10.14 Mojave or later, OAuth is used automatically when it’s available during AutoDiscover.
macOS – Duo Security
Duo Security’s article called “Guide to Office 365 mail client behavior when using Basic and Modern Authentication with Duo” confirms this support.
Also, it is difficult to find official documentation on Apple mobile operating system iOS. Initially, iOS 10 we added support for OAuth 1.x. However, there was an issue with Microsoft integration that blocked any iOS 10 device from using the new AutoDiscover process which caused it to fall back to the original AutoDiscover process. Which was the only way to invoke OAuth 2.x in iOS 11.
There was no way to invoke it for MDM payloads until the OAuth keys were available which were added in the iOS 12 release. This is referenced in the “ExchangeActiveSync” payload documentation.
iOS – Duo Security
Again, Duo Security’s has an article called “Guide to Office 365 mail client behavior when using Basic and Modern Authentication with Duo” confirms this support but with iOS 11 and later NOT iOS 12 and later as assumed from Apple Developer documentation.
Microsoft KeyChain Items Removal
To work around login issues with or without Microsoft Modern Authentication with Microsoft Outlook, Skype for Business, Microsoft Teams, or other Microsoft Office 365 applications you can try resolving issues by deleting any cached passwords for your account and any tokens from the keychain.
To do this, follow these steps.
- Quit Microsoft Outlook and all other Microsoft Office applications.
Launch Keychain Access
- In the search field in Keychain Access, enter “Exchange”
- In the search results, select each item to view the Account that’s listed at the top, and then press Delete.
Repeat this step to delete all items for your Exchange account.
- In the search field, enter “adal”
- Select all items whose type is MicrosoftOffice15_2_Data:ADAL:<GUID>, and then press Delete.
- In the search field, enter “office”
- Select the items that are named Microsoft Office Identities Cache and Microsoft Office Identities Settings 2, and then press Delete.
- Quit Keychain Access
When you start Outlook, you are prompted to authenticate
Automate KeyChain Item Removal
If you believe you will need manually remove the Microsoft keychain items more that two times then it probably a good idea to automate the process.
There is a shell script that automates the process of removing of the Microsoft Office 365/2019/2016 keychain entries called “NukeOffKeychain” created by a Microsoft System Engineer, Paul Bowden.
The following options are available with the “NukeOffKeychain” shell script:
Remove Login, Cache, and ADL
Using the “–default” option will remove the login, cache, and ADAL keychain items.
# NukeOffKeychain –Default
Credential keychain entries removed Default keychain entries removed
Remove Rights Management
Using the “–IRM” option will remove the rights management keychain items.
# NukeOffKeychain --IRM Rights Management keychain entries removed
Using the “–All” option will remove all keychain items including login, cache, ADAL, rights management & HelpShift.
# NukeOffKeychain.sh --All Credential keychain entries removed Default keychain entries removed Rights Management keychain entries removed HelpShift keychain entries removed
If you use Jamf Pro to manage your Mac client systems, you can make this script available using Self Service to allow your users to run it when needed.
Jamf Pro Setup
Download the “NukeOffKeychain” script from the GitHub repository.
- Script Argument
Then add the script with parameter values “–jamf” in argument 3 and “–MAS” in argument 4.
The “–jamf” argument enables the script to ignore the first 3 arguments options available in the script which include “–Default”, “–IRM” and “–All”.
Supporting Hybrid Modern Authentication Against Onprem Mailboxes
Been working with some 3rd party developers to get their applications working with our campus hybrid modern authentication. And one developer easily got everything working following the steps outlined on this web page:
Microsoft Outlook – Address Book Lookup
Microsoft Outlook has many new features and enhancements that are related to the offline address book. By default, Outlook uses a cached mode configuration. Because the cached mode generates an offline address book, you must understand how to configure the offline address book so that it works efficiently in your Microsoft Exchange organization. Cached mode is the new default configuration for Outlook. It provides an experience that is similar to the offline configuration in earlier versions of Outlook. When you are running in cached mode, your Exchange mailbox is synchronized to a local file (a .ost file), and the offline address list from your Exchange computer is synchronized to a collection of files (.oab files) on your client computer. Outlook directly accesses the .ost file and the .oab files on your local system instead of communicating directly with your server or servers.
If you have issues after migrating from basic to modern authentication with Address Book lookup, you might try the following fix to force a download of the Offline Address Book (OAB):
Quit the Microsoft Outlook application and enter the following command:
defaults write com.microsoft.Outlook ForceOABDownload -bool TRUE
And then relaunch Microsoft Outlook, it should force the Offline Address Book (OAB) to update.
This above command will modify the property list in the current user’s folder here:
Enabling Diagnostic Logging
If none of the troubleshooting steps above help you resolve your issue with Microsoft Outlook, you can enable diagnostic logging and review the logs.
Microsoft Outlook for Mac provides the option to enable logging for the following features:
- AutoDiscover service
- Microsoft Exchange (folder and item synchronization)
- Microsoft Exchange Calendar
- LDAP transactions
Additional Logging Features
In Microsoft Outlook 2016 for Mac version 15.12.3 and later versions, the following features are also logged in addition to the ones listed above:
- Network Connections
Enable Logging (GUI)
To enable logging in Microsoft Outlook 2016 for Mac, follow the steps below:
- In Microsoft Outlook, select the Window menu, click Sync Error
- In the Sync Errors window, click the Gear icon.
- Select the “Turn on logging for troubleshooting” option, and then click the “OK” button
Enable Logging (Command Line)
You can use the command line to enable diagnostic logging, enter the following command:
defaults write com.microsoft.Outlook LogForTroubleshooting -bool TRUE
- Restart Outlook and when prompted to turn off logging click “Leave Logging On” and reproduce the issue you experience and then Quit Outlook to stop the log capture.
Disable Logging (GUI)
- Restart Microsoft Outlook and when prompted to turn off logging click “Turn Logging Off”.
- If you disable logging manually you must restart Outlook to fully disable logging, otherwise, it will continue logging in the background
Disable Logging (Command Line)
You can use the command line to disable diagnostic logging, enter the following command:
defaults write com.microsoft.Outlook LogForTroubleshooting -bool FALSE
Warning Disable Logging
It is important to turn off logging after you complete your troubleshooting. If logging is not turned off, the log file size will continue to increase taking up disk space. If you must keep logging enabled for several hours or several days in order to capture the issue, make sure that the system has sufficient free disk space.
Log File Locations
Depending on the edition and version of Microsoft Outlook for Mac the log name and location will differ.
To locate the log file, see the table below:
Log File Information
The log file contains the following information:
- Issues that occur when email messages, calendar items, notes, tasks, and meeting requests are sent or received.
- Type or severity of errors, if known.
In Microsoft Outlook 2016 for Mac version 15.12.3 and later versions, the log file opens in the Console application and you can view it while Microsoft Outlook is active.
Each entry has a name that identifies the feature that is being logged. The following table lists the label for each feature.
The log file may also contain the user’s personal information. This includes user name, sender, and receiver’s email addresses, and the contents of the user’s email messages, notes, tasks, calendar, and contacts. If you are concerned that the data file contains sensitive or confidential information, you may review the contents of the data file by using text-editing software and then remove the information from the file before you send the data file to support professionals.
Note – Authentication information is NOT included in the log files.
Disable AutoDiscovery for Microsoft Office for Mac
- Start Outlook on the affected Mac client
- Launch the Script Editor application located in “Applications > Utilities” folder
- Copy/Paste these three lines into a new Script Editor window
tell application "Microsoft Outlook" set background autodiscover of exchange account 1 to false end tell