Custom app registration in Google Workspace / Google Cloud to avoid repeated lost credentials or reauthentication

Why use custom application registration?

By default, Mail Attachment Downloader signs in to Gmail / Google Workspace using OAuth (sometimes called modern authentication) through Gearmage's built-in Google app. Some Google Workspace organizations restrict or block third-party apps, or apply policies that revoke access to apps they don't own. This can show up as repeated sign-in prompts, lost credentials, or errors such as "Sign in with Google temporarily disabled for this app" or "This app is blocked". This matters most when the program runs unattended as a service (e.g. PRO Server).

A custom application registration lets you use your organization's own Google OAuth client instead. Because the app belongs to your Google Workspace, your administrator controls it, it can be marked Internal (no Google verification needed), and it isn't affected by changes to the built-in app.

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. For Google you need two things (there is no Tenant ID for Google):

• Client ID
• Client Secret

The user still signs in once through the browser, just like with the built-in app, but the sign-in goes through your own app. If the user's password is changed, Google revokes the existing Gmail access and the user will need to sign in again. That's Google's standard behavior for all apps.

Requirements

• A PRO edition of Mail Attachment Downloader. Custom app registrations are ignored in the Free edition.
• The account must connect over IMAP (the Gmail / Google preset, or a custom host of imap.gmail.com) with Use OAuth2 (modern auth) checked. Custom app registrations are not available for POP3.
• A Google account allowed to create projects in Google Cloud for your organization. A Google Workspace administrator is recommended, since the Admin console steps below need one.

Create a Google Cloud project

1. Go to the Google Cloud Console and sign in with an account in your Google Workspace organization.
2. In the project picker at the top, click New Project, give it a name (e.g. Mail Attachment Downloader), select your organization, and click Create. You can also reuse an existing project.
3. With the project selected, go to APIs & Services → Library, search for Gmail API, and click Enable.

Configure the OAuth consent screen

1. Go to APIs & Services → OAuth consent screen (shown as Google Auth Platform in the newer console). If prompted, click Get started.
2. Under App information / Branding, enter an app name (e.g. Mail Attachment Downloader) and a user support email.
3. Under Audience, choose Internal. This limits the app to users in your organization and avoids Google's app verification.
   • External is only needed for accounts outside your Workspace (such as personal @gmail.com addresses). An External app left in Testing status only works for listed test users, and Google expires its sign-ins after 7 days, which brings back the repeated re-authentication problem. We recommend Internal.
4. Enter a developer contact email, agree to the Google API Services policy, and click Create / Save.
5. Under Data Access (or Scopes), click Add or remove scopes and add:

   Scope	Used for
   https://mail.google.com/	Reading, moving and deleting email over IMAP
   https://www.googleapis.com/auth/userinfo.email	Confirming which account signed in
   https://www.googleapis.com/auth/gmail.send	Only if the program sends email (e.g. forwarding or notifications over SMTP)

   You can paste them under Manually add scopes. Click Update, then Save.

Create the OAuth client (Desktop app)

1. Go to APIs & Services → Credentials (or Google Auth Platform → Clients).
2. Click + Create Credentials → OAuth client ID (or + Create client).
3. For Application type, choose Desktop app. This is important: other types such as "Web application" will fail to sign in with a redirect_uri_mismatch error. No redirect URI needs to be entered.
4. Give it a name and click Create.
5. Copy the Client ID and Client secret, or click Download JSON to keep a copy.
   • Use the Client ID as the Client ID in the app.
   • Use the Client secret as the Client Secret in the app.

Google may only show the full client secret once, when the client is created. Save it somewhere safe. If you lose it, add a new secret to the client (or create a new client) and update it in the program.

Allow the app in the Google Workspace Admin console

Depending on your organization's policies, a Google Workspace administrator may need to do the following in the Google Admin console:

1. Trust the app (needed if third-party app access is restricted): go to Security → Access and data control → API controls → Manage Third-Party App Access, click Configure new app, search for your new Client ID, select it, choose the users or organizational unit, and set access to Trusted.
2. Make sure IMAP is allowed: go to Apps → Google Workspace → Gmail → End User Access and confirm POP and IMAP access is enabled for the users that will be downloading.
3. Check session length (optional): if Security → Access and data control → Google Cloud session control requires periodic re-authentication, it can also apply to trusted apps. Consider exempting trusted apps or setting "Never require reauthentication" for this program.

Enter the details and test the connection

1. In Mail Attachment Downloader, open the settings (gear icon) for the Gmail / Google Workspace account.
2. Make sure the account uses IMAP and Use OAuth2 (modern auth) is checked.
3. Click on the Custom App Registration tab and enter the Client ID and Client Secret. Both are required. If only one is entered, the built-in app is used.
4. Click Clear Cache to clear any cached credentials from the built-in app.
5. Click Test Connection. A browser window opens. Sign in with the mailbox's Google account and approve access. The consent screen should show your app's name.
6. If the connection succeeds, you have set it up correctly. Click Save.
7. If the connection fails, recheck the Client ID and Secret (watch for extra spaces), confirm the client type is Desktop app, and see the troubleshooting section below.

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 if a custom app you entered is not being used, it explains why (for example: incomplete entries, POP3, or the Free edition).

Troubleshooting

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.