Enterprise Application Setup Guide

This guide walks you through registering an Enterprise Application in your Azure Tenant so that FreeITSM can securely connect to your Exchange Online mailbox for email ticketing.

This guide assumes you have already completed the Azure Tenant Setup and Exchange Mailbox Setup guides, or that your organisation already has an Azure Tenant with Exchange Online.

---

Step 1: Register a New Application

1. Sign in to the Azure portal at portal.azure.com
2. In the search bar at the top, search for "App registrations" and select it
3. Click "New registration"
4. Enter a name for the application – something descriptive like "FreeITSM"
5. Under Supported account types, select "Accounts in this organizational directory only" (single tenant)
6. Under Redirect URI, select "Web" from the dropdown, and enter your FreeITSM OAuth callback URL, e.g.:
   https://your.itsm.com/oauth_callback.php
7. Click "Register"

Once registered, you will be taken to the application's overview page. Take note of the following values – you will need them later:

• Application (client) ID – this is your Enterprise App ID
• Directory (tenant) ID – this is your Tenant ID

---

Step 2: Create a Client Secret

A client secret is like a password that FreeITSM uses to authenticate with Azure on behalf of your application.

1. From your application's overview page, click "Certificates & secrets" in the left-hand menu
2. Under the Client secrets tab, click "New client secret"
3. Enter a description (e.g. "FreeITSM Secret")
4. Choose an expiry period – 24 months is a sensible default, but be aware you will need to generate a new secret before it expires
5. Click "Add"
6. Copy the secret value immediately – it will only be shown once. If you lose it, you will need to create a new one.

---

Step 3: Configure API Permissions

Your application needs permission to read and send email on behalf of the mailbox.

1. From your application's page, click "API permissions" in the left-hand menu
2. Click "Add a permission"
3. Select "Microsoft Graph"
4. Choose "Delegated permissions"
5. Search for and add the following permissions:
   • Mail.Read
   • Mail.Send
   • offline_access
6. Click "Add permissions"
7. Finally, click "Grant admin consent for [your organisation]" and confirm when prompted

---

Step 4: Configure the Mailbox in FreeITSM

Now that your Azure application is set up, you need to connect it to FreeITSM.

1. Log in to your FreeITSM instance as an administrator
2. Navigate to Admin Settings → Mailbox Settings
3. Enter the following values from your Azure application:
   • Tenant ID – the Directory (tenant) ID from Step 1
   • Application ID – the Application (client) ID from Step 1
   • Client Secret – the secret value you copied in Step 2
   • OAuth Redirect URI – e.g. https://your.itsm.com/oauth_callback.php
4. Save the settings
5. Click the Authenticate button – this will redirect you to Microsoft to sign in and authorise the connection
6. Sign in with the account that owns the Exchange mailbox and grant the requested permissions

---

Ready to Go?

Use the checklist below to confirm everything is in place:

• Registered an application in Azure – with a descriptive name and the correct Redirect URI
• Noted your Tenant ID and Application ID – from the application overview page
• Created a client secret – and copied the value securely
• Configured API permissions – Mail.Read, Mail.Send, and offline_access with admin consent granted
• Entered the details in FreeITSM – Tenant ID, Application ID, Client Secret, and OAuth Redirect URI
• Redirect URIs match – the URI in Azure and in FreeITSM are identical
• Successfully authenticated – FreeITSM is connected to your Exchange mailbox

← Back to Getting Started