George Wirtjes
Senior Consultant – Sage 100
SWK Technologies, Inc.
NOTE: The information below might not be entirely up to date. For the updated instruction of how to configure Sage 100 Authentication for Microsoft 365 via OAuth, check out this video:
This blog describes how to configure OAuth for user authentication with Microsoft 365 and Office 365 accounts, as well as adding the required information to your Sage 100 SMTP settings.
NOTE: Effective October 1, 2022, Microsoft is making changes to Microsoft Exchange that will impact your ability to email in-product if you are on Sage 100 2020 or older. Microsoft will be deprecating TLS 1.1, which is used in older versions as part of the Paperless Office email function. Microsoft 365 will also require OAuth for authentication.
If you are using Sage 100 2021.4 or higher, a supported OAuth configuration is available but will need to be configured. If you are not using Sage 100 2021.4 or newer, please reach out to your SWK CAM or contact us at info@swktech.com.
For more detailed information please see this Microsoft documentation
Sage 100 OAuth Configuration Steps
- Log in to Microsoft / Office 365 as an administrator
NOTE: You must use an account with administrative access to your organization’s M365 subscription
- 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 important areas – the App Registrations list and Endpoints.
NOTE: 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:
- https://archive.clouduss.com/uss/microsoftoauth.do
- Name: “Sage 100+Version of Sage” Sage100_2022
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
- https://yourdomain/microsoftoauth.do
- 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.
Secret Keys are only displayed on-screen ONCE and once only – so you must securely make a note of the secret key straight away.
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 URLs 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 three specific endpoints.
Endpoints are defined for your organization’s Microsoft 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 three 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 APIs 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 read.all permission.
- 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 Microsoft 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 Office 365. There is a separate document describing the setup for ADFS (on-premise based SSO).
- 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”
- Access Token URL is the “OAUTH 2 TOKEN ENDPOINT”
- 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 organization
- 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 Microsoft 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).
Troubleshooting OAuth
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., mail.swktech.com) or web name 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.
Incorrect Endpoints
If you have left the three endpoint settings blank or that the endpoints relate to a different organization or were entered in the wrong place, then you may see errors like the following:
Login to Sage 100 2019 or greater.
Go to Library Master – Company Maintenance:
Select the appropriate Company Code.
Select tab 5. EMAIL
Select OAuth
Begin to enter the information you saved from the OAuth Settings on Microsoft 365 admin.
Ensure that the Client ID, Client Secret, Auth End Point, Token End Point and Scope are all filled out. If you are using a redirection URL. You can add that as well.
Check the check box for 128-bit encryption.
Finally, click the test button and test an email.
NOTE: Sage 100 has a known issue. If you make changes to the above screen you will need to save those changes by clicking “Accept” prior to testing. If you make a change and do not hit Accept, you may still be testing using the old stored settings not the ones you just updated.
Speak to the Sage 100 Experts for More Tips & Tricks
This is one of many tips and tricks SWK Technologies can provide to Sage ERP users. SWK is a top Sage Partner with intimate knowledge of Sage 100 and Sage 100cloud, and we leverage this experience to make sure you capture the best possible value from your software investment.
Contact SWK today to answer all of your questions on how to best use your Sage 100 or Sage 100cloud ERP.
Learn More About Sage 100, Microsoft 365 & OAuth