OAuth Providers for Mailboxes

Out-of-the-box, OroImapBundle provides two OAuth-based Email origin types: Gmail and Microsoft 365.


Google Gmail implementation provides OAuth authentication/authorization via a custom Google application.

  • Integration configuration is available via System Configuration > Integrations > Google Settings.
  • Mandatory fields are Client ID and Client Secret. They are located in the Google application management panel.
  • Option OAuth 2.0 for Gmail emails sync must be enabled. If the provided credentials are invalid, the integration will not be enabled.

Microsoft 365

Microsoft 365 implementation provides OAuth authentication/authorization via a custom Microsoft Azure application.

  • Integration configuration is available via System Configuration > Integrations > Microsoft Settings
  • Mandatory fields are Client ID, Client Secret, Tenant. They are located in the MS Azure application management panel.
  • Select Enable Emails Sync in Microsoft 365 Integrations.

Custom Provider Implementation

  1. Implement a new OAuth provider class that inherits from Oro\Bundle\ImapBundle\Provider\OAuthProviderInterface.

  2. Implement a new OAuth manager class that inherits from Oro\Bundle\ImapBundle\Manager\OAuthManagerInterface.

  3. Tag the manager implementation with tag oro_imap.oauth_manager (the service will be automatically picked up and, if the provider is enabled, an additional account type will be available for User Configuration > General Setup > Email Configuration > Email Synchronization Settings > Account Type).

  4. Implement a form type with default Email Origin values for a certain provider (see Oro\Bundle\ImapBundle\Form\Type\AbstractOAuthAwareConfigurationType and existing inheriting types).

  5. Register a route for Oro\Bundle\ImapBundle\Controller\CheckConnectionController for a new OAuth vendor.

  6. Implement a custom controller for handling access token (see Oro\Bundle\ImapBundle\Controller\AbstractAccessTokenController and inheriting controllers) and register a route for it.

  7. Register custom form block widgets definitions:

    • Resources/config/oro/twig.yml - add this file to register the global set of definitions of form fields.
        - '@ExampleVendorImap/Form/fields.html.twig'
    • Create a fields definitions file with the custom definition of the previously defined form field.
    {# '@ExampleVendorImap/Form/fields.html.twig' #}
    {% block example_imap_configuration_type_widget %}
        {% set data = form.parent.parent.vars.value %}
        {% set options = form.vars.options|default({})|merge({
            {# component options #}
        }) %}
        <div class="example-imap-gmail-container"
             data-page-component-options="{{ options|json_encode }}"
            <div {{ block('widget_container_attributes') }}>
                {# Custom form layout #}
                {{- form_rest(form) -}}
    {% endblock %}
  8. Implement JavaScript components:

    • Create a popup for OAuth initialization (extend /Resources/public/js/app/components/imap-component.js).
    • Create a view managed by the component (extend /Resources/public/js/app/views/imap-view.js).
    • Depending on OAuth implementation from your provider, claim token data via a previously defined controller.

    By default, the component/view handles the population of proper DOM elements with the provided token data.