Let’s Get Technical: iOS 11’s OAuth 2.0 for Office 365
Ivanti
*This post originally appeared on the MobileIron blog prior to the acquisition in December 2020, when MobileIron became part of Ivanti.
Background
In a recent post, we went through an overview of how to secure iOS 11’s new OAuth 2.0 email feature available and how an enterprise can mitigate against the risk of non-compliant devices accessing Office 365. For those that wish to have more of an overview, you can find it here. In this post, we are going to dive deep into how authenticating to email via OAuth 2.0 works, what happens behind the scenes, and possible steps an enterprise can take to mitigate against the risk of unmanaged email accounts in the wild. If technical details on this feature aren’t of interest to you, skip to here to view the available options to restrict this iOS 11 feature.
Changes from iOS 10.3 Beta to iOS 11
For those that tested the iOS 10.3 beta builds, the user-agent has changed from iOS 10.3 beta to the newly released iOS 11 update. In the days before iOS 10.3 was set to be released, many found the response was blocked. In iOS 11, the user-agent is now allowed in the public release. In this section, we’ll be looking into the differences between the iOS 10.3 beta and the public release of iOS 11.
iOS 11
During the initial autodiscover step, the iOS email client is making a call to Office 365 with a user-agent of Apple-iPhone9C1/1501.530400009. We can simulate the same call that an iOS device first makes when initiating autodiscover using CURL on our PC.
Request
cURL -lv "https://outlook.office365.com/autodiscover/autodiscover.json/v1.0/[EMAIL Address]?Protocol=ActiveSync" -A "Apple-iPhone9C1/1501.530400009"
Response
With the new user-agent being used, the iOS mail app receives the following response from Office 365.
{
"Protocol":"ActiveSync",
"Url":"https://outlook.office365.com/Microsoft-Server-ActiveSync"
}
iOS 10.3 Beta
During the initial autodiscover step, the ios email client is making a call to Office 365 with a user-agent of Apple-iPhone9C1/1401.530400009.
Request
cURL -lv "https://outlook.office365.com/autodiscover/autodiscover.json/v1.0/[EMAIL Address]?Protocol=ActiveSync" -A "Apple-iPhone9C1/1401.530400009"
Response
{
"ErrorCode": "NotSupportedClient",
"ErrorMessage": "The given ActiveSync client is not supported"
}
OAuth 2.0 Email Creation: End-User
As noted in the previous post, the OAuth 2.0 email creation is a user-driven feature in iOS 11 and currently Apple has not provided MDM controls to deploy this new authentication flow to managed email accounts. The embedded video below demonstrates the end-user experience when adding an Exchange Online account.
To reiterate what the video shows:
- The user selects the iOS mail app
- Next, the user selects the Exchange option
- The user then inputs their email address and description
Now let’s take a look at what happens next?
Initiating iOS 11’s OAuth 2.0 Email Creation
After the user selects next, they are presented with a one-time pop-up. As seen in the figure, the user is asked to “Sign in to your ‘[Domain]’ Exchange account using Microsoft?” and is presented with two choices, “Configure Manually” and “Sign In”.
“Configure Manually” follows the traditional active profile account creation path.
“Sign In” follows the autodiscover path by making an autodiscover request to outlook.office365.com.
Let’s look behind the scenes at autodiscover. When the user selects “Sign in”, the iOS device first makes a mysterious call to https://newaccountredirectdomain.apple.com. At the time of writing, it’s unclear what this call does.
Autodiscover
Autodiscover reaches out to outlook.office365.com with the user’s email address. The request uses the example URL shown here:
Example Request
|
https://outlook.office365.com/autodiscover/autodiscover.json?Email=<email address>&Protocol=ActiveSync |
As the example shows, Autodiscover uses the HTTPS protocol. We can simulate this call with CURL:
Command
|
curl -lv "https://outlook.office365.com/autodiscover/autodiscover.json?Email=<[email protected]>&Protocol=ActiveSync" |
Response
The response to the initial autodiscover call depends on where the mailbox resides. We tested the following scenarios:
- Office 365 mailbox (Cloud only)
- Office 365 Hybrid deployment with on-premises mailbox
- On-Premises Exchange Only
Office 365 Mailbox (Cloud only) Response:
If the email address embedded in the initial autodiscover call is found in Office 365, outlook.office365.com responds thusly:
Protocol:"ActiveSync"
Url:"https://outlook.office365.com/Microsoft-Server-ActiveSync" When the mailbox is found to be in Office 365, the end-user will start the new authentication process.
Office 365 Hybrid Deployment: On-Premises mailbox
In many enterprises, Office 365 is deployed in a hybrid configuration where migrations from on-premises Exchange to Office 365 mailboxes are staged over time. The autodiscover responses vary based on how autodiscover has been configured for the domain. Many enterprises point autodiscover.domain.com to their externally facing, on-premises Client Access Services(CAS). Others make other choices. For more information on the DNS records that Office 365 requires, Microsoft provides an excellent reference page found here. More in-depth information on the autodiscover lookup process can be found in a TechNet article here.
On-Premises Exchange Only
Remember that no matter the exchange deployment architecture, when the user selects “Sign In” to configure their Exchange account, Office 365 autodiscover always makes a call to outlook.office365.com for mailbox discovery. When the mailbox is not found in an Office 365 cloud-based mailbox, the response from Office 365 redirects to the appropriate autodiscover URL for the domain, as shown in the example:
Response
Initial call to Outlook.office365.com
GET /autodiscover/autodiscover.json?Email=<Email Address>&Protocol=ActiveSync HTTP/1.1
Host: outlook.office365.com
Redirect to the enterprise’s autodiscover location
HTTP/1.1 302 Found
Location: https://<Autodiscover name>/autodiscover/autodiscover.json?Email=<Email Address>&Protocol=ActiveSync&RedirectCount=1
Authentication
After the exchange host is acquired through autodiscover and found to be an Office 365 mailbox, the end-user is redirected to their Identity Provider(IdP). An authenticated call is made to https://<exchange host>/Microsoft-Server-ActiveSync with an empty authorization header. An empty authorization header means that the email account has not been authorized to access email and must go through the authentication process. We can simulate this call from the device to Office 365 through cURL.
|
cURL -lv "https://outlook.office365.com/Microsoft-Server-ActiveSync" -H "Authorization: Bearer" |
Response
In the HTTP 401 Unauthorized response, the authorization endpoint(authorization_uri) responds to the client to start the authentication process. The Azure endpoint or Uniform Resource Identifier(URI) points to the following:
https://login.windows.net/common/oauth2/authorize
Header Referer
When the user is redirected from the Azure endpoint, the HTTP referer provides information to their IdP to start authentication and where the request originated. In the example below, our Office 365 tenant was federated with SAML 2.0. We are still investigating what can be found when the IdP is federated to Office 365 with WS-Federation:
Breaking the Referer Down
Authorization URI: https://login.microsoftonline.com/common/oauth2/authorize
ClientID(Unique Identifier of app in Azure): f8d98a96-0999-43f5-8af3-69971c7bb423
Redirect URI: com.apple.Preferences://oauth-redirect
Permissions Scope: EAS.AccessAsUser.All
UI Locale: iOS Device’s language
Login_hint: Email Address
Resource: https://outlook.office365.com
IdP Redirect
After the authentication request originates in Office 365, the service sends a response to the email client to authenticate with their Identity Provider(IdP). The iOS mail client leverages the Safari view controller(SFVC) to redirect to the Identity Provider and complete the authentication process.
Authorization
Once the end-user provides their credentials and authenticates to their IdP, they will be presented with an OAuth 2.0 authorization approval screen.
OAuth 2.0 in Azure
This blog post does not go into how OAuth 2.0 is implemented in Azure, but if you’re interested in digging a bit deeper, you can find the following Azure documentation here. There is also an OAuth sandbox environment here that allows a safe playground for learning more.
iOS Accounts
After a successful authentication with their Identity Provider(IdP), the end-user is presented with an OAuth approval grant. The application, called “iOS Accounts” needs the following permissions in order to proceed:
- Access your mailboxes
- Sign you in and read your profile
*Note* This OAuth 2.0 authorization grant is only shown the first time an end-user attempts access to their Office 365 email account. An Administrator can also automatically accept permissions on behalf of their enterprise users.
iOS Accounts Behind the Scenes: End-user
iOS Accounts is an application created by Apple and registered in Azure. When the end-user accepts the application, they will find the iOS Accounts application in their Office 365 Portal.
To test the iOS Accounts authorization grant again for an end-user, select Revoke on the screen above. By revoking the application, the end-user will need to accept the iOS Accounts application the next time they add their Office 365 email account.
iOS Accounts Behind the Scenes: Administrator
When an end-user accepts iOS 11’s OAuth 2.0 email authorization grant, the iOS Accounts application also gets created behind the scenes in the company’s Azure tenant. However, an end-user must go through this account creation step before the application is available in their Azure tenant. At the time of this posting, iOS Accounts is NOT available to add in the public Azure Application Gallery for an administrator to configure. We found that the only way to have this application added to a company’s tenant is to manually go through the iOS 11 OAuth 2.0 account creation.
When the first time an end-user successfully grants the iOS Accounts permission, the application will be added to the Application catalog in Azure.
The Application ID, also known as a clientID, is a globally unique application created by Apple in Azure. This ID(f8d98a96-0999-43f5-8af3-69971c7bb423), will be the same across every Azure tenant.
OAuth Token
Azure uses a standards based JWT token. We decoded a real OAuth token issued for my account below. We found token validity is the difference between the value of iat and exp. In our case, the token was valid for an hour and 5 minutes.
{
"typ": "JWT",
"alg": "RS256",
"x5t": "9FXDpbfMFT2SvQuXh846YTwEIBw",
"kid": "9FXDpbfMFT2SvQuXh846YTwEIBw"
}
{
"aud": "https://outlook.office365.com",
"iss": "https://sts.windows.net/8392379d-8a98-4cb4-8cfe-5e7fa92e4e60/",
"iat": 1499289288,
"nbf": 1499289288,
"exp": 1499293188,
"acr": "1",
"aio": "ASQA2/8DAAAALGFisFdBqP3W1Nq+pKd1U5SmkCcn7nlGYonYDHfqXl8=",
"amr": [
"pwd"
],
"appid": "f8d98a96-0999-43f5-8af3-69971c7bb423",
"appidacr": "0",
"enfpolids": [],
"family_name": "[Last Name]",
"given_name": "[First Name]",
"ipaddr": "[External IP]",
"name": "[Full Name]",
"oid": "f752c51d-7811-4453-8cf5-9637033cbd87",
"onprem_sid": "S-1-5-21-725690979-2191617849-2898786972-5273",
"platf": "2",
"puid": "1003BFFD8D2D2594",
"scp": "full_access_as_user",
"sub": "DL1ipWqUqwJycUehF6T1fKv0UMahVqXM5KkUwFWw41w",
"tid": "8392379d-8a98-4cb4-8cfe-5e7fa92e4e60",
"unique_name": "[Typically Email and/or UPN]",
"upn": "[UPN]",
"ver": "1.0"
}
Ensuring Trusted Access to Compliant Devices
Now that we went through how the new iOS Account app works behind the scenes, the highest priority for Office 365 enterprise customers is to prevent unauthorized access. Our previous post identified the current limitations, but for those unacquainted, the email account creation is only available for user-driven and unmanaged account access. As a result, our current recommendation is to block this capability to ensure that only registered and compliant devices can access Office 365 email. In this section, we’ll walk through the available options to block this feature from allowing unmanaged email account creation for Office 365.
Leveraging MobileIron Access to block Untrusted Devices and Apps
Security needs to move with the speed of mobile. MobileIron Access provides powerful conditional access capabilities along with the customizable remediation page that mitigates the risk of non-compliant devices accessing Office 365. We recommend customers look into using the conditional access rules to allow only managed email accounts provisioned by MobileIron to access their Exchange Online accounts. Using the configurable remediation page, administrators can direct users to register their devices with MobileIron so they that can enjoy seamless authentication to Office 365, including Exchange Online and so that the enterprise’s assets can be properly secured.
To accomplish this technically, MobileIron Access has pre-configured rules that can be applied to only trusted devices and applications that are deployed as managed applications by their EMM administrator. This allows only for registered and compliant applications to pass through for authentication to their Identity provider(IdP) and/or provide seamless sign-on. When an unregistered device gets redirected to Access for checking compliance, its configurable compliance page will ask users to register their device and/or use only approved applications. To support this rule in Access:
- Apply the Trusted App and Device as the first priority. This rule is enabled by default.
- Add the Untrusted Apps rules iPhone and iPad. These rules will block authentication requests originating from non-compliant applications and devices on the iOS platform.
Alternatively, for enterprises that have federated Access to Office 365 with SAML 2.0, a predefined rule in Access called iOS Native Email OAuth, explicitly blocks any OAuth 2.0 requests for iOS native email. Today, the iOS Native Email OAuth predefined rule is currently not available for those enterprises that have configured Access with WS-Federation.
Disable iOS Accounts App in Azure
The iOS Accounts app created as part of the workflow above can also be disabled in the Azure App Catalog. For those enterprises that have not deployed MobileIron Access, the email client will be allowed to authenticate to their Identity Provider(IdP), but the authorization grant will generate an error. Disabling iOS Accounts is not as elegant as MobileIron Access’ remediation page that asks the user to enroll their device. Disabling the application will block the application from being used in the tenant. At this time, we have not been able to successfully configure Azure Conditional Access to get more granular with the controls.
To accomplish this:
- Login to the Azure Portal (https://portal.azure.com) with administrator credentials.
- Select Azure Active Directory icon from the left navigation window.
- Select Enterprise Applications
- Select All applications
- Select iOS Accounts. *Note that this will only be available once an end-user goes through the above account creation flow on iOS 11. It is NOT publicly available to add in the Azure App Catalog.
- In the iOS Accounts application, select Properties.
- In the Properties tab, change Enabled for Users to sign-in from YES to NO.
- Select Save. For more information on disabling user sign-in, please find the Microsoft Azure AD page here.
Alternatively, administrators can set policy on if end-users are allowed to register applications to their company’s Azure tenant. By default, end-users are allowed to register apps in Azure Tenants. In the Azure Portal, administrators can set the tenant-wide user settings to prevent end users from registering applications such as iOS Accounts in Azure. For more information, you can find the Microsoft docs located here.
For enterprises that are also leveraging MobileIron Access, disabling iOS Accounts in their Azure tenant is complementary.
Limit autodiscover authentication to Trusted IPs
For those that can’t get enough of claims adventures with their Identity Provider(IdP), we found that certain claim types can be used to restrict access to trusted devices. In the past, the X-MS-Client-Application claim type could be used to restrict to Microsoft.Exchange.Activesync. On iOS 10.3 and earlier, many of our customers have implemented a similar AD FS rule to the one below that restricts Activesync to only Standalone Sentries.
|
exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy"]) |
With the emergence of iOS 11 and its OAuth 2.0 email capability, we found that the above rule no longer blocks Activesync traffic because the application claim type is only relevant for clients that originate through an active profile. In order to restrict this new feature, we needed to restrict autodiscover to only trusted IP addresses. Limiting autodiscover has the potential to affect every enterprise devices accessing email; not just devices authenticating through activesync. We strongly recommend to leverage the other options above before attempting to restrict autodiscover through claims. Since autodiscover is widely used for every email client, an enterprise must take into account every IP address(es) that will attempt to access email with Office 365. For many enterprises, they must take into account their corporate network, legacy devices and VPN solutions that are not managed by MobileIron, and Standalone Sentries for MobileIron registered devices authenticating with ActiveSync. If the above warning doesn’t dissuade you from trying, below is a sample rule that was tested successfully.
Restrict autodiscover to only allow traffic sent through MobileIron Standalone Sentry
|
exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy"]) |
Final Thoughts
In this post, we analyzed the new iOS 11 OAuth 2.0 email flow for Office 365 which included the creation of the iOS Accounts app in Azure. As enterprises adopt iOS 11 and Office 365, administrators need to ensure email is accessed by compliant devices. Our recommended approach can be defined in two steps. The first step is to leverage MobileIron Access with a configurable compliance page to enable end-users to easily get their devices compliant. The second is for an Azure tenant administrator to disable the iOS Accounts app in Azure. This ensures that end-users have a managed and seamless Office 365 experience on iOS native email while mitigating against non-compliant email accounts. While the options above were tested against this iOS 11 feature, this is not an exhaustive list and there may be other options that can be considered. For all of our great customers and partners, I look forward to hearing about your own testing experiences on our community here.
