Configuring authentication with O365 via OAuth
This document describes how to configure OAuth for user authentication with Office 365 accounts.
- Log in to Office 365 as an administrator
- Navigate the long menu to find the link to Azure Active Directory
- Open the Azure Active Directory App Registrations section. Any existing applications will be listed here. There are 2 important areas – the App Registrations list and Endpoints.
You may already have an application that is already being used for OAuth / SSO purposes – and you could edit this for rather than adding a new application. However, this article will provide instructions for creating a new registration.
- Click New registration and enter in the following details:
- A Name (any name will do)
- The type should be set to Web app / API
- A sign-on URL – this is known as the “Reply URL”. For the Email Archive system this MUST be in the following format:
- Name: "Censornet Archiving"
Save and add the new App Registration. Make a note of the Application (client) ID as it will be required later.
- Optionally, after adding the App Registration you can configure Reply URL entries – each one corresponding to additional web apps that you are granting SSO access to
- Next you must create the Secret Keys.
It is critical that a remote application can acknowledge an encrypted message sent from the OAuth provider (Azure AD). It will do this by decrypting the message using a secret key. If this fails, the message will be rejected.
Enter a Name for the key and select a Duration of your choice.
- Next, you must configure Endpoints
The Email Archive system login (initiated via the user’s web 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 URLs.
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 Email Arche side. However, for the app registration described in this article, 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 3 entries in the Endpoints list are needed by the Email Archive system, as identified here:
- You should have now collected the 5 pieces of information highlighted in the screenshots above. These are required to configure the Email Archive system later in this article.
- Next, the Permissions must be set for the newly created App Registration.
- Within the newly created app, click the API Permissions tab
- Click on Add a permission - this will show a large panel with multiple API’s for which permissions can be granted.
- Select the Microsoft Graph API block, and then you will be offered two types of permissions – Delegated (which correspond with an individual user’s permission after an OAuth login for that user), or Application (which is a general permission for applications connecting using this Client ID). Select Application Permissions.
- From the list of permissions, either scroll down or type into the search box the term
User. Select the
- Click the Add Permissions button at the bottom of the panel.
- After this you will be returned to the main panel where you will see that a final “Grant” action is still needed:
If your Azure account has the correct permissions, you will need to click the “Grant admin consent for…” button showing at the bottom of this panel.
If your Azure account does not have sufficient permissions, you will not be able to grant admin consent – and an error will show like this:
Once successful, you will now see that the permission is now granted for the new App:
You can now continue to configure the Email Archive using all of the collected information.
- Log in to the Email Archive system as an Administrator (if this role has not been enabled for your environment, please contact your service provider for assistance).
- Under the Adv. Configuration menu, look for the SSO OAuth menu option.
Each entry added here will create an OAuth Login button on the Login page. You would not usually require more than one OAuth registration – but you can configure several entries if required. 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. It is recommended that the Connection Name is changed to something that your users will understand and be familiar with, e.g.
- To create the OAuth entry click Create New Connection (you will need the 5 pieces of information from earlier in this article to continue). Enter the 5 pieces of information into the form, as shown below:
The Provider Type should be Microsoft Office365. There is a separate document describing the setup for ADFS (on-premise based SSO). Other types may be added in later Censornet Archiving releases.
1. Client ID is the Azure app registration’s Application ID
2. The Client Secret is the key value displayed just once when you create a “key”.
3. The Authorization URL is the “OAUTH 2 AUTHORIZATION ENDPOINT”
4. Access Token URL is the “OAUTH 2 TOKEN ENDPOINT”
5. User Detail URL is the “MICROSOFT AZURE AD 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
- Configuration is now complete
Local User Accounts for OAuth
When a user accesses the Email Archive for the first time using OAuth, it will create a Local User Account entry within the Email Archive system. This account will mirror their details extracted during the OAuth login phase (as obtained from “Azure AD - Graph API”). This is true even if LDAP connectivity is available. I.e. Any LDAP connectivity established between a customer and the Email Archive system is not referenced during OAuth login.
To review the accounts created by OAuth logins, visit the Basic Configuration > Local User Accounts section. 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 the Email Archive so must be validated with some external system).
Here is an example of an account created via an OAuth login. Note the secondary addresses and display name are all obtained from the login process (via Graph API).
Reply URL issue
If the Reply URL is incorrect or is not reachable by the OAuth provider (Azure) – suggesting that the Email Archive URL is not visible on the Public Web site – then this error will be shown:
Note the wording “… does not match the reply URLs …”. This suggests that the URL used for accessing the Email Archive is using a different domain (e.g. mailarchive.host.com) or web name (typically “Censornet Archiving”) to any of the ones registered in the Azure AD App. Check this carefully and if you are still having problems please contact your service provider.
If you have left the 3 endpoint settings blank (so that the "Censornet Archiving" app uses the common URLs instead) or that the endpoints relate to a different organisation or were entered in the wrong place, then you may see errors like the following: