OAuth Setup with Solar Archive

How to setup OAuth with Solar Archive

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.

1. Login to Office 365 as an administrator

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.

2. 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 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/solararchive/microsoftoauth.do

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.

3. 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...

Secret Key Creation

4. Reply URL's

The OAuth’s security is ensured by the Azure Active Directory only responding to requests coming from Web addresses that have been registered. 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.

5. Required Permissions

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 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

6. 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.

7. Setup OAuth in Solar Archive

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.

Under the Adv. Configuration menu you will see (since Solar Archive version 9.0.7) an “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).

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.

1. 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.

2. Client ID is the Azure app registration’s Application ID

3. The Client Secret is the key value displayed just once when you create a “key”.

4. 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

5. Access Token URL is the “OAuth 2 Token Endpoint”

6. User Detail URL is the “Graph API Endpoint”

8. Finish up

Once this connection is added, it will immediately appear on the Solar Archive Login panel.

Here is a login panel with this new OAuth login button, together with 2 previous ones.