OAuth setup with Office 365
OAuth for Solar Archive with Azure/Office
Introduction
Solar Archive is an archive for Email and IM transcript messages. It supports logins for users defined locally within the archive system, as well as Active Directory (LDAP) users. With Cloud based systems, establishing connectivity to Active Directory (LDAP) is often not allowed – making support for user logins more challenging. SAML and OAuth can be used as alternative login methods that do not require LDAP connectivity or user accounts to be pre-configured into Solar Archive.
SAML (Security Assertion Markup Language) was first introduced to provide organisations with a very secure way to provide Single Sign On (SSO) to remote applications, such as Solar Archive. The customer would need to set up an Active Directory Federated Service (ADFS) – a web server service that was visible on the public side of the organisation. A third-party service (for example, a 2 factor authentication provider) would register the organisation’s ADFS service and also the remote application, like Solar Archive. Then it could coordinate Login requests between the user and the application. Although this worked, it was quite complicated to set up.
OAuth simplifies the SAML approach and no longer needs the third-party service. It can still be set up using ADFS – but is also quite easy to configure for Office 365 users. This document shows how to configure OAuth for Office 365 and Solar Archive.
User Experience
Once OAuth is configured, users will be directed to the Solar Archive Login page where one (or more) Quick Login buttons will display:
When one of these buttons is clicked, the user may be prompted to select an account, or provide 2-factor authentication (2FA) credentials:
If successful, the user will go directly to the Solar Archive search panel. At the top right, you will see the user details. Click the “settings” button to confirm that any secondary / alias email addresses have also been obtained via the OAuth system:
Now any searches will return results for any emails sent to or from any of these email addresses.
The OAuth access can also be extended, by setting some Azure App Registration API Permissions, to:
Search and List user accounts (API Permission User.Read.All). As used when selecting accounts for Mailbox Reader, Folder Replication or User Directory.
User Mailbox Access for Mailbox Reader or Folder Replication (API Permission Mail.Read or Mail.ReadWrite)
Restore to Mailbox (API Permission Mail.ReadWrite)
The following sections discuss this in more detail.
OAuth Setup – step by step
1. Login to Office 365 as an administrator
Whilst writing this document, this feature has moved to Microsoft Purview portal. Use Data lifecycle management > Exchange (legacy) > Journal rules to create and update journal rules on the Journal rules page. This page has now been retired from the Classic Exchange admin centre. More details can be found on Offical Exchange Site
You must use an account with administrative access to your orgnisation’s Office 365
subsription. Navigate the long menu to find the link to Azure Active Directory
Open the Azure Active Directory App Registrations
Any existing applications will be listed here.
There are 2 key areas –the App registrations list / Add new registration ; and Endpoints We will look at the App Registration part first.
You may already have an application that this already being used for OAuth / SSO purposes – and you could edit this for Solar Archive rather than adding a new application.
However, we will show you how to add a new registration as follows. Create an App by entering a
A Name (any name will do)
The type should be left as Web app / API
A sign-on URL – this is known as the “Reply URL”. For Solar Archive is MUST be in this format:
https://your Solar Archive host/Solar Archive/microsoftoauth.do o Please enter the correct URL hostname for connecting to your Solar Archive system o In some cases, the Solar Archive web name could be re-branded – so enter the appropriate name provided by your supplier rather than the word “Solar Archive”.
The name “microsoftoauth.do” is required.
This is all you will need to create the app entry. However, you will next need to create a “secret key”, and optionally you could add extra Reply URL entries – each one corresponding to additional web apps that you are granting SSO access to.
https://[your.cloud.site]/Solar Archivev/microsoftoauth.do https://[your.cloud.site]/Solar Archivev9/microsoftoauth.do
Please note, each application has an Application ID – this is the first piece of data that you will be needing this when configuring the Solar Archive settings.
Secret Key creation
It is critical that a remote application can acknowledge an encrypted message sent from the OAuth provider (Azure AD) by decrypting it via a secret key. Without this it will not be allowed.
Secret Keys are only displayed on-screen ONCE and once only – so you will need to record this straight away.
All you need to do is to enter a name for the key – any name will do. Then set the duration for the key…
This is the second piece of data required on the Solar Archive side.
Reply URL’s
These are the “Reply URL’s”. You may only need one URL - the one added when you created the App in Azure AD, ending in “/microsoftoath.do”. But if you needed to edit or add other web sites that you wish to respond to OAuth login requests then you can do this here.
During and after Solar Archive <> OAuth <> Azure AD completes its verification steps, you can control who/where/how the login phases will be conducted – if 2FA is to be used for certain user types or depending on their location.
After a successful login, Solar Archive will connect to the “Graph API” passing the user credentials returned from OAuth, to obtain essential details about the user. These are:
Secondary Email addresses
First name and Surname
Account Creation date
User Principal Name (UPN)
GUID
To do this, the User Account “read” permission must be granted. This is the default setting for all new apps. Consequently, this does not need to be altered for Solar Archive’s purposes.
Please note that the Graph API may be used to obtain data from Azure AD in much the same way that LDAP was used for on-premise services. The Graph API is not only used for Active Directory connections but is expanding to cover all of the core Microsoft applications – like Outlook, SharePoint, Teams (skype for business) and so on.
Solar Archive administration users the ability to select from the list of Azure user accounts for Mailbox Reader and Folder Replication purposes. To allow this feature, you must add the “Graph API > Application > User.Read.ALL” permission. Also for Mailbox Reader / Folder Replication, the Mail.ReadWrite / Mail.Send permissions are also required. This is described in full later in this document.
Endpoints
Solar Archive login (initiated via the user’s Browser) will need to know where to redirect the user to perform the OAuth sequence – and where to obtain the users account details. These are known as “endpoints” and are web service URL’s.
If you have set up an Azure AD hosted “developer application”, then these URL’s are common, fixed URLs and can be left blank on the Solar Archive side. However, for the app registration described in this document we will need to obtain 3 specific endpoints.
Endpoints are defined for your organisation’s Office 365 subscription, not per app registration. Therefore you will need to navigate back to the list of App Registrations panel – and at the top you will then see the link to Endpoints.
The final 3 entries in the Endpoints list are needed (in reverse order!) by Solar Archive, as shown here:
That is all you need from the Microsoft Office 365 / Azure AD / OAuth side. Now we can take the 5 values highlighted in these steps and register them in Solar Archive.
Solar Archive’s OAuth configuration
Log in or access Solar Archive as an Administrator. For multi-tenant (cloud) Solar Archive systems you may need to login using a Super User type account and then connect to the required company (tenant) using the full admin link. The highlighted values from the Azure side must be copy-pasted into the panel, as indicated below:
Under the Adv. Configuration menu you will see “SSO OAuth” menu entry.
Each entry added here will create an OAuth Login button on the Login page. You would not usually require more than 1 OAuth registration – but for demonstration purposes we are showing several entries. For example, you could have an entry for on-premise ADFS based OAuth login, one for a Developer App and another for standard Office 365 (as described in this document).
The “Connection Name” is displayed on the button on the Login page. The 2 connections shown above will result in these buttons showing on the login page:
Please use a name that your users may understand or is a term used in other applications!
The remaining 5 entries are obtained from the Azure AD sections shown earlier in this document.
The Provider Type should be Microsoft Office365. There is a separate document describing the setup for ADFS (on-premise based SSO). The OpenID Connect type can be used with a wide variety of other providers, like One Login and Google Workspace.
Client ID is the Azure app registration’s Application ID
The Client Secret is the key value displayed just once when you create a “key”.
The Authorization URL is the “OAuth 2 Authorization Endpoint”
Please Note: In the middle of the authorisation is the “Tenant ID” value. This can be used in other settings – e.g. for Mailbox Reader or Restore to Inbox
Access Token URL is the “OAuth 2 Token Endpoint”
User Detail URL is the “Graph API Endpoint”
Please note – for “developer app” registered apps, the 3 endpoint URL’s can be left blank as these are common to all developer apps and not specific to any organisation.
Here is a login panel with this new OAuth login button, together with 2 previous ones.
Local User Accounts for OAuth
When a user accesses Solar Archive for the first time using OAuth, it will create a Local User Account entry within Solar Archive. This account will mirror their details extracted during the OAuth login phase (as obtained from “Azure AD - Graph API”).
To review the accounts created by OAuth logins, visit the Basic Configuration > Local User Accounts.
The Office 365 accounts will show the user’s email address as their username. They will be set to “external authorization” (meaning that their password is not held in Solar Archive so must be validated with some external system).
API Permissions for Mailbox Selection lists
Since Solar Archive version 9.3.0 it is possible to use OAuth Application permissions to allow a Solar Archive Administrator to search and list Azure user accounts for Mailbox Reader and Folder Replication purposes.
Since Solar Archive version 9.3.3, it is also possible to select “Graph” instead of “EWS” for Mailbox Reader and Folder Replication – but you MUST add further Azure API Permissions to allow this to work. Please Note – with these API Permissions you will NOT need to assign a user with the “Application Impersonation” role, as you have to for EWS.
The required permissions are: User.Read.All (for account selection listing); Mail.ReadWrite and Mail.Send (for Mailbox Reader/ Folder Rep / Reply-to).
This section shows the process to add this permission.
Here is an example of this facility for Folder Replication.
Click the new “Select Users from Office 365” button and a pop-up web page lets you select the OAuth connection. Enter some search term and click “Search”.
If you get an error message, then either
The Azure AD “Application” API Permissions are not correct.
The Azure AD “Application” is using an older style with default “endpoints”.
Solar Archive config for Azure is using default “endpoints” rather than the Azure defined ones.
But if it does work, you will see that it returns not only valid mailboxes – but “external guests accounts” as well. Additional efforts beyond this document are needed to return a filtered list.
By default you get the Azure Active Directory User.Read permission – the permission to read your own details. This is added for you and is all that is needed for SSO Login Authorisation in Solar Archive.
To add this permission, use the “View API Permissions” or click the “API Permissions”. Then “Add a permission”, and select “Microsoft Graph”
This needs to be an “Application” level permission – a user is not required to login to access this service.
Then, as there are many different permissions, then it is best to search for the required one (User.Read.All plus Mail.ReadWrite and Mail.Send).
Then you can select and add this permission. However, this still requires a final “Grant Consent” this change to complete the process. Only an Administrator, or an Azure user with the Consent permission, can complete the process.
NOTE: You may be logged in as the Admin – but you still need to click the “Grant admin consent” button (when it displays).
Be sure to Grant consent using an appropriate user account.
And it will display the Permission Consent like this:
And a minute or two later the new permission should show as Granted. Once done, the new feature in Solar Archive should start to work.
Restore to Inbox using EWS with OAuth authentication
There are some features not supported by MSGraph one of which is Restore to Inbox. EWS not also supports OAUTH connections. This means that you will no longer require the setup and usage of an Impersonation User account. To use this capability, as documented by Microsoft here: Authenticate an EWS application by using OAuth | Microsoft Docs The key steps are:
1.To add this permission, use the “View API Permissions” or click the “API Permissions”. Then “Add a permission”, and select “Microsoft Graph” include the EWS Access permission.
2.Add or Alter an EWS based Solar Archive Restore & Authentication connection to use OAuth authentication.
Setup Solar Archive to Restore to Inbox over EWS with OAuth
Back in the Solar Archive admin area, locate the Basic Configuration > Restore & Authentication panel.
Here you add or modify a connection to “outlook.office365.com” for EWS protocol.
There are 3 authentication types:
User Login – the user will need to enter their Username and Password when restoring an email. However, this does not work if 2 Factor Authentication (2FA) is required.
EWS Impersonation – the Exchange Online administrator must have provided an Azure user account (not necessarily an Exchange Mailbox user account).
NOTE: You must enter the Impersonation user’s User Principal Name (UPN) as the username for the impersonation feature to work.
OAuth app – this is the option to be used here. On selecting this option it asks for an OAuth connection, and a Tenant ID – see below for how to obtain this value.
NOTE: Using OAuth permission with EWS means that you will NOT need an Impersonation User account.
If you do not know the Tenant-ID, then enter some dummy text and save the connection, then do the following:
Obtaining the “Tenant ID”
If you look back at the OAuth setup in Solar Archive, you will notice that the Authorization and Access Token URL’s have a long string within them. This text is the Tenant-ID.
Simply copy-paste this value to the Restore & Authentication connection.
Possible Issues
Reply URL issue
If the Solar Archive service that you are using with OAuth is providing a Reply URL that does not match any of the Azure App Registration’s Redirect URLs then this error will display:
Note the wording “… does not match the reply urls …”. This suggests that the URL used for accessing
Solar Archive is using a different domain (e.g. mailarchive.host.com) or web name (typically
“Solar Archive”) to any of the ones registered in the Azure AD App. Or that the Solar Archive web is not contactable using that URL on the public side.
To rectify this, look at the browsers current URL while this error is displayed. Somewhere in this URL it includes the Reply URL (as set by the Solar Archive Service that you are using OAuth with).
If you put that URL into Notepad, you will spot the Redirect URL:
https://login.microsoftonline.com/e9eb0714-blaa-blaablaa/oauth2/v2.0/authorize?client_id=fd421875-blaa-blaablaa&response_type=code&redirect_uri=https%3a%2f%2ffcs-wincryodc.fcs.Solar Archive.com%2fcryo%2fmicrosoftoauth.do&response_mode=form_post&scope=openid+ email+profile+User.Read+offline_access&sso_nonce=AwABAAAAAAACAOz_BAD0_zGskYz5qTUbJxfUqKO87jB0k2WisvHGghxYART16MRvN9as3Z-7brNJDFi43WBrOPm6&client-requestid=8cb997c0-blaa-blaa-blaa&mscrid=8cb997c0-blaa-blaa-blaa
Incorrect Entrypoints
If you have left the 3 entrypoint URL settings blank (so Solar Archive uses the common url’s instead) or that the entrypoints relating to a different organisation or were entered in the wrong place, then issues like the following will display:
Last updated
