---

Table of Contents

Introduction

---

This page provides an in-deep descriptions on how our Confluence app connects to Office 365 / Exchange. Before we start going into details about the current architecture, just a few words on the "why".

You usually have two options when it comes to displaying calendar data from Exchange:

• Synchronize data to a second data store (e.g. via ExchangeService.SyncFolderItems) and display the data from the secondary store (e.g. like Outlook cached mode)
• Request the necessary information on-demand from Exchange / Office 365

Each solution has up- and downsides (out-of-sync issue, performance considerations, ...), but we decided to go the second route with our calendar. This has some technical implications, the most important one being able to retrieve event data from Exchange in the browser. In an ideal world, we would just connect to Office 365 or Exchange directly from the browser, so there would be no need for any middleman. Unfortunately, there are a lot restrictions in the browser today, namely CORS and the Same-Origin-Policy, which prevent us from using a direct connection - at least to Exchange Web Services (EWS). 

Note: For Office 365 we try to retrieve as much data as possible through Microsoft Graph. There are a few limitations though, which prevent us from removing the connection to Exchange completely (for now).

The app works with all kinds of technologies, and every combination works a bit different. In the following matrix you can see the possible connection modes:

App Components

---

In this section, we give a brief overview of the app packaging. This is all basic Atlassian development, so if you are looking for in-depth information on this topic, please check the Atlassian Developer docs.

Server & Data Center

The server version of Outlook Calendars for Confluence consists of two parts:

• Front-end Javascript code, running in the browser
• Back-end Java code, running on the Confluence Server

The communication between the two components is done via HTTP(S). The backend code currently takes care of the following task:

• Storing settings and encrypted user credentials (NTLM or OAuth tokens, depending on the target Exchange)
• Storing app wide settings 
• Proxying requests to Exchange (when configured as "Confluence Proxy", details see below)
• Integrating with certain Confluence extension points (Macro, Space Settings)

The code is packaged as a .jar-file and can be downloaded from the Atlassian Marketplace. 

Cloud

The cloud version of Outlook Calendars for Confluence consists of two parts as well:

• Front-end Javascript code, running in the browser
• Manifest file, describing all extension points, web-hooks and permissions

The only major difference is, that since Confluence Cloud does not support executing Java code, all server side logic will be handled on our servers (e.g. storing settings & proxying EWS requests).

Proxy Types

---

As referenced in the above table, there are basically three types of proxies that we support. In this case, proxy is not referring to a generic proxy, but a piece of software, that enables CORS and translates a restful HTTP call with JSON body to an EWS request, based on XML. 

To give you an idea which option achieves which results, please take a look at the following table:

Confluence Proxy

This proxy is only supported on Confluence Server or Data Center and is built into the app itself. It is based on the ews-java-api library by Microsoft. This is the most secure option to use, since no outside system will ever get in contact with sensitive data. This is also the default setting for Exchange OnPremise servers. Please note that this setting will put additional load on your Confluence server.

Web Proxy

This proxy is supported in every scenario. It's simply a small nodeJS-based ExpressJS server, which will basically do the same thing as the Java based Confluence proxy. The difference is, that this proxy is hosted on AWS. The source code is open source and can be found in here. This is the default for most combinations, because it offers better scaling and less configuration than the Confluence Proxy. In case you need to white-list the proxy in your firewall, the URL is: https://ews.yasoon.com/*

Custom Proxy

The custom proxy can be used, if you decide to host our web proxy in your premises. It will work exactly the same, with the added benefit of a more private hosting. Configuration and initial setup is more complicated, though it can also be switched to at any time in the future.

External Systems & URLs

---

Short overview of external services involved in running the app. Everything will always be accessed via TLS (unencrypted access is not supported).

Server & Data Center

In case of the Confluence Server app, in the default configuration, no external systems are involved. Depending on the configuration of the EWS proxy, one external connection might be established:

Cloud

In the case of the Confluence Cloud app, there are a few systems that need to be involved to provide the full functionality. 

Data Storage

---

Server & Data Center

The Confluence Server app does not store any data outside of Confluence itself.

Cloud 

The Confluence Cloud app stores settings on our server. 

Detailed Architecture

---

In this chapter we will describe the detailed architecture of the data that flows between browser, app & Exchange / Microsoft Graph. As there are a lot of configuration possibilities, please make sure to check that you are referencing the correct one.

Our general premise is to make everything as private & secure as possible - when the technology allows it. We'll go into details where there are currently trade-offs.

Confluence Server & Confluence Data Center

This chapter will describe the 4 options that are possible with Confluence Server:

• Office 365 (Exchange Online) via Confluence Proxy
• Office 365 (Exchange Online) via Web Proxy (or custom proxy)
• Exchange On-Premise (2010+) via Confluence Proxy
• Exchange On-Premise (2010+) via Web Proxy (or custom proxy)

Office 365 (Exchange Online) via Confluence Proxy

This option is the most secure you can configure. No external connections of any kind are established, nor is any data stored on any external system. Authentication is based on the OAuth 2.0 implicit flow provided by AzureAD. The implementation is based on the official Active Directory Authentication Library (ADAL) for JavaScript. Once the access token has been acquired from AzureAD, it's securely stored in the user profile in Confluence. The OAuth 2 access token is subsequently used to connect to the Microsoft Graph directly from the client browser. Additional information, which cannot be loaded via Microsoft Graph, is loaded via EWS, proxied by Confluence. For this, a differently scoped OAuth access token is used. 

With Office 365 (Exchange Online) via Web Proxy (or custom proxy)

This option can be used if you don't want to manage the additional load on the Confluence system, that stems from proxying EWS requests to Exchange. In this case, we'll take care of managing the connection to Exchange, and the browser will directly connect to our web proxy. This has some security implications, though we don't store any data on our proxy, and you'll be able to audit the proxy code, since it's open source. If you choose to host the web proxy yourself, the Web Proxy in the diagram below will just move from "Public Internet" to "Intranet". To keep it concise, this diagram has been omitted.

---

Exchange On-Premise (2010+) via Confluence Proxy

In case you are using a self-hosted Exchange Server, the whole picture get's a bit more simple. There is no Graph API we can access, so all data is fetched directly from Exchange Web Services. Same as before, no external connections of any kind are established, nor is any data stored on any external system. Authentication is currently based on NTLM credentials, though we are looking into possibilities to use Kerberos. The user credentials are securely stored in the user profile in Confluence. All information is proxies through Confluence, so the credentials are not accessible from outside.

Exchange On-Premise (2010+) via Custom Proxy

This option can be used if you don't want to manage the additional load on the Confluence system, that stems from proxying EWS requests to Exchange. Instead, you use our dedicated proxy software, which is highly specialized for the task. This offers high security, since no credentials are transferred outside your intranet. For Confluence systems with high load we recommend this solution.

Exchange On-Premise (2010+) via Web Proxy

When using Exchange on-premise and Confluence Server, this is definitely the least recommended configuration. In this configuration, all requests to EWS will be proxied through our server. While this is acceptable when using revocable OAuth AzureAD tokens, this really should be considered last resort when working with NTLM credentials. Nevertheless, if this your only option, we still try to make this as secure as possible by only sending pre-hashed NTLM credentials to our proxy, so we don't get in touch with the plain-text user password.