Help ›

Authorization Code Grant custom client setup guide

This guide explains how to set up an Entra / Azure custom OAuth client configuration for use with the Authorization Code Grant flow. This is an interactive flow that prompts the user for authorization when initially linking the account. It is the default OAuth flow in most cases.

This feature requires a subscription to Auth-Email's Pro plan.

đź’ˇ   If you have already set up a custom client for the Client Credentials Grant flow you can skip to the final steps of this guide and reuse the application configuration and client ID / secret when linking with Auth-Email.

1. Create an Entra / Azure application

The first step is to create a new application registration in the Microsoft Entra admin center. This application represents your Auth-Email integration, and will be used to request OAuth tokens for accessing mailboxes.

  1. Log in to the Microsoft Entra admin center with an administrator account.
  2. In the left-hand menu, select “App registrations” and then “New registration”.
  3. Provide a name for the new application you will create (for example, Auth-Email Authorization Code Grant).
  4. For “Supported account types”, select Accounts in this organizational directory only.
  5. Choose Web in the “Redirect URI” field, and enter https://auth-email.com/authorize
  6. Click “Register” to create the application.

The following screenshot shows an example registration configuration:

Entra application configuration

2. Configure and grant permissions

After creating the application registration, you will be redirected to its overview page for further configuration. You can also return here later by selecting “App registrations” from the left-hand menu of the Entra admin center, then choosing your application from the “All applications” list.

  1. In the left-hand submenu, select “API permissions” and then “Add a permission” (located just above the table of permissions).
  2. In the popup, select the tab “APIs my organization uses”.
  3. Find and select Office 365 Exchange Online, then choose “Application permissions”.
  4. Expand the IMAP, POP, and SMTP sections, and select all of the following permissions:
    • IMAP.AccessAsApp
    • POP.AccessAsApp
    • SMTP.SendAsApp
    • đź’ˇ  If you know you will only be using specific protocols, it is fine to add just those permissions.
    • đź’ˇ  The User.Read permission is automatically added to all new applications, but it is not required for access via Auth-Email. You can leave this permission as-is, or remove it if you prefer.
  5. Click “Add permissions” at the bottom of the panel to save your changes.

The following screenshot shows the API permission configuration, granting IMAP, POP, and SMTP access:

Entra application API permissions

After adding the required permissions, you will be returned to the API permissions overview page for your newly-created application. To allow your application to use the permissions you just selected, admin consent is now needed.

  1. Click the “Grant admin consent for {your organization name}” button (located just above the table of permissions, as shown in the screenshot below).
  2. In the confirmation popup, click “Yes” to give consent for the requested API permissions.

Entra application admin consent

The final configuration step is to generate credentials for your newly-created application. Return to the Microsoft Entra admin center, and select the “App registrations” section from the left-hand menu, then choose your application from the “All applications” list.

  1. In the left-hand menu, select “Certificates & secrets”.
  2. In the “Client secrets” tab, select “New client secret”.
  3. Provide a description (for example, Auth-Email Authorization Code Grant Secret) and select an expiration period.
  4. We recommend including the expiry date in the secret description to help you track when it needs to be rotated.
  5. Click “Add” to create the client secret. The new client secret will be displayed in the list.
  6. Copy the “Value” of the client secret and save it for the next step.
    • đź’ˇ  Important: This value is needed for integrating with Auth-Email. You will not be able to retrieve it later, so make sure you copy and save it now.
  7. In the left-hand menu, select “Overview” to view the completed application’s details. Keep this page open while you move to the next step.

Now that you have created and authorized the new Entra / Azure application, you can link it with Auth-Email.

  1. Log in to your Auth-Email dashboard, then visit the Acccount settings page.
  2. In the “Custom OAuth clients” section, select “Add client”.
  3. Give the client a name (for example, {Your organization name} Authorization Code Grant), and select Microsoft as the service provider.
  4. In the “OAuth flow / grant“ dropdown box, select Authorization Code.
  5. Leave the “Permission URL“, “Token URL“, and “OAuth scope“ fields as their default value.
  6. Enter the “Application (client) ID“ from your Entra application into the “Client ID“ field.
  7. Enter the client secret value you saved earlier into the “Client secret“ field.
  8. Click “Add client” to create the custom OAuth client.

Finally: test your setup

You can now select this custom OAuth client when authorizing email accounts in Auth-Email. Instead of proceeding with the default authorization method, choose your newly-created application in the list at the bottom of the Auth-Email account authorization page. You will be prompted to authenticate, then authorize access to link and activate your account.

Once authorization is complete, your account is available to be used over IMAP, POP or SMTP using using its address and the password you just set. See the configuration step of our getting started guide for help setting up your email client if needed.