Custom app registration in Microsoft 365 / Entra admin center to avoid repeated lost credentials or reauthentication

Why use custom application registration?

By default, Mail Attachment Downloader signs in to Microsoft 365 using OAuth (sometimes called modern authentication) through Gearmage's built-in app. The user signs in and grants the program delegated access to their mailbox. This can cause problems when the program runs unattended as a service (e.g. PRO Server). Your administrator controls how long delegated sign-ins stay valid and when users must sign in again, and a password reset or Conditional Access policy can revoke them. When that happens, the program loses its credentials until someone signs in again.

A custom application registration lets you register the program as your own application in the Microsoft Entra admin center. With a client secret, the program connects app-only: it uses its own credentials, not a user's sign-in, so password resets and sign-in frequency policies don't affect it. Access is controlled entirely by your administrator through the app's permissions.

When you click on Settings (gear icon) for a given account in the program, you will get the server settings popup. In that popup you should see a Custom App Registration tab with three fields:

• Tenant ID
• Client ID
• Client Secret

Which setup do I need?

What you need depends on how the account connects (the server type selected in the server settings):

Connection	Access type	Fields to enter	Permissions
Microsoft Graph (recommended)	App-only	Tenant ID, Client ID, Client Secret	Microsoft Graph → Application: Mail.ReadWrite, Mail.Send
Exchange Online (EWS)	App-only	Tenant ID, Client ID, Client Secret	Office 365 Exchange Online → Application: full_access_as_app
IMAP, work or school account	App-only	Tenant ID, Client ID, Client Secret	Office 365 Exchange Online → Application: IMAP.AccessAsApp (+ SMTP.SendAsApp), plus Exchange Online PowerShell steps
IMAP, work or school account	Delegated (the user signs in through your app)	Tenant ID, Client ID. Leave Client Secret blank	Microsoft Graph → Delegated: IMAP.AccessAsUser.All, offline_access (+ SMTP.Send)

Custom app registrations are not available for POP3, Exchange on-premises, or personal Microsoft accounts (outlook.com, hotmail.com, live.com, msn.com). Those always use the built-in app.

We recommend Microsoft Graph for new setups. Microsoft is retiring Exchange Web Services (EWS) in Exchange Online, so if an account currently uses Exchange (EWS), consider switching it to Microsoft Graph.

Requirements

• A PRO edition of Mail Attachment Downloader. Custom app registrations are ignored in the Free edition.
• Use OAuth2 (modern auth) checked in the account's server settings.
• A Microsoft Entra administrator who can register apps and grant admin consent (Application Administrator, Cloud Application Administrator, or Global Administrator). For IMAP app-only you also need an Exchange administrator.

Create a new application registration

1. Go to the Microsoft Entra admin center.
2. Go to Identity → Applications → App registrations.
3. Click + New registration. Enter a name (e.g. Mail Attachment Downloader) and choose Accounts in this organizational directory only (Single tenant).
4. Redirect URI:
   • App-only (Graph, Exchange, IMAP with a secret): not required. Leave it blank.
   • IMAP delegated (no secret): choose platform Public client/native (mobile & desktop) and enter http://localhost. After registering, go to Authentication and also check the https://login.microsoftonline.com/common/oauth2/nativeclient redirect URI.
5. Click Register.
6. On the app's Overview page:
   • Note down the Application (client) ID and use it as the Client ID in the program.
   • Note down the Directory (tenant) ID and use it as the Tenant ID in the program.

Create a new client secret (app-only access)

Skip this section if you are setting up IMAP delegated access.

1. In your app registration, go to Certificates & secrets → Client secrets → + New client secret.
2. Enter a description, choose an expiry, and click Add.
3. Copy the secret's Value (not the Secret ID) into the Client Secret field in the program. The value is only shown once. If you leave the page without copying it, create a new secret.

Client secrets expire (at most 24 months). When the secret expires the connection stops working. Set a reminder to create a new secret before the expiry date and enter it in the program.

Assign the necessary permissions

Follow the section for your connection type. In each case, open your app registration and go to API permissions → + Add a permission.

Microsoft Graph (app-only)

1. Choose Microsoft Graph → Application permissions. Pick Application, not Delegated permissions.
2. Add Mail.ReadWrite, plus Mail.Send if the program sends email (forwarding or notifications). Mail.ReadWrite includes read access, so Mail.Read is not needed.
3. Click Add permissions, then Grant admin consent for <your organization>. Application permissions don't work until an administrator consents, because no user signs in to approve them.

Exchange Online / EWS (app-only)

1. Choose APIs my organization uses, search for Office 365 Exchange Online, and select it.
2. Choose Application permissions and add full_access_as_app.
3. Click Add permissions, then Grant admin consent for <your organization>.

IMAP (app-only, with a client secret)

1. Choose APIs my organization uses, search for Office 365 Exchange Online, and select it.
2. Choose Application permissions and add IMAP.AccessAsApp, plus SMTP.SendAsApp if the program sends email.
3. Click Add permissions, then Grant admin consent for <your organization>.
4. Register the app in Exchange Online and give it access to the mailbox. Go to Identity → Applications → Enterprise applications, open your app, and note its Application ID and Object ID. Use this Object ID, not the one on the App registration page. Then, in Exchange Online PowerShell:

   Connect-ExchangeOnline
   New-ServicePrincipal -AppId <Application ID> -ObjectId <Enterprise app Object ID>
   Add-MailboxPermission -Identity "user@yourdomain.com" -User <Enterprise app Object ID> -AccessRights FullAccess

   Repeat Add-MailboxPermission for each mailbox the program downloads from. The app can only access mailboxes you give it permission to.
5. Make sure IMAP is enabled for the mailbox (Microsoft 365 admin center → Users → the user → Mail → Manage email apps → IMAP). If sending, also enable Authenticated SMTP.

IMAP (delegated, no client secret)

1. Choose Microsoft Graph → Delegated permissions.
2. Add IMAP.AccessAsUser.All and offline_access, plus SMTP.Send if the program sends email.
3. Click Add permissions. Clicking Grant admin consent is optional, but it saves users from a consent prompt and is required if your organization doesn't let users consent to apps.
4. Make sure IMAP (and Authenticated SMTP, if sending) is enabled for the mailbox as described above.

With delegated access, the user still signs in, and sign-in frequency policies and password resets still apply. The difference is that the sign-in goes through your organization's own app, which your administrator controls. For fully unattended operation, use app-only access.

Restrict the app to specific mailboxes (optional)

By default, Graph and EWS application permissions give access to every mailbox in your organization. To limit the app to specific mailboxes, use Role Based Access Control (RBAC) for Applications in Exchange Online (recommended). The older Application Access Policies (New-ApplicationAccessPolicy) are now legacy. IMAP app-only access is already limited to the mailboxes you granted with Add-MailboxPermission.

Enter the details and test the connection

1. In Mail Attachment Downloader, open the settings (gear icon) for the account.
2. Make sure Use OAuth2 (modern auth) is checked and the right server type is selected (Microsoft Graph, Exchange, or IMAP).
3. Click on the Custom App Registration tab and enter the Tenant ID, Client ID and (for app-only) Client Secret. For IMAP delegated, leave the Client Secret blank.
4. Click Clear Cache to clear any cached credentials.
5. Click Test Connection. For app-only access there is no sign-in window. For IMAP delegated, a browser window opens: sign in with the mailbox's account.
6. If the connection succeeds, you have set it up correctly. Click Save.
7. If the connection fails, recheck all the entries, make sure admin consent was granted, and see the troubleshooting section below. Permission changes can take up to an hour to take effect in Exchange Online.

To confirm which app the account is using, click Connection Diagnostics in the server settings popup. It shows whether the custom or built-in app registration is in use and whether it's app-only or delegated. If a custom app you entered is not being used, it explains why (for example: missing client ID or tenant ID, POP3, a personal Microsoft account, the Free edition, or a client secret set in the program's .config file, which takes precedence).

Troubleshooting

Error or symptom	What to do
AADSTS7000215: Invalid client secret	You probably copied the Secret ID instead of the Value. Create a new secret and copy its Value.
AADSTS7000222: client secret keys are expired	Create a new client secret and enter it in the program.
AADSTS700016: application not found in the directory	The Client ID or Tenant ID is wrong, or they belong to different tenants. Re-copy both from the app's Overview page.
AADSTS50194: application is not configured as multi-tenant	Enter the Tenant ID in the program.
AADSTS65001 / AADSTS90094: consent required	Click Grant admin consent on the app's API permissions page.
AADSTS50011 / AADSTS500113: redirect URI mismatch (IMAP delegated)	Add the Public client/native (mobile & desktop) redirect URIs listed above under Authentication.
Graph ErrorAccessDenied / 403	Check that Application permissions (not Delegated) were added and consented, and that any RBAC or access policy includes this mailbox.
IMAP AUTHENTICATE failed with app-only	Check that New-ServicePrincipal used the Enterprise application Object ID, that Add-MailboxPermission was run for this mailbox, and that IMAP is enabled for it. Allow up to an hour for changes to apply.
Custom App Registration tab is disabled	The account uses POP3, Exchange on-premises, a personal Microsoft account, or OAuth2 is unchecked.

If this continues to fail, try temporarily disabling any antivirus or firewall to rule out connection issues, then send us the details from Connection Diagnostics.