Features (AddOns)

Service Up

InBox MailAccountOAuth2

Version 6.0.3

Creation date 22/08/2022

Resources

Module to enable receiving (IMAP, POP3) and sending (SMTP) emails via OAuth 2.0 authorization.

Prerequisites

Framework

The following versions of Znuny Framework are supported:

  • [6.0.x]

Modules

The following modules are required:

  • [None]

Operating System

The following operating systems are required:

  • Perl module: Data::UUID

Third Party Software

The following third party software is required:

  • [None]

Browsers

The following browsers is required:

  • [Chrome]

  • [Mozilla]

Installation

bin/otrs.Console.pl Admin::Package::Install /path/to/InBox\ MailAccountOAuth2-6.0.3.opm

Configuration

This module does not require system configuration

Use

Adding a Token

Adding a token will generates a YAML configuration in the database. This file has a specific format depending upon the provider and can be exported, modified, and imported as needed by the configuration or for migration see below. We include basic formatting templates for the email providers, Google and Microsoft (Common, Consumer, and Organization).

The configuration is all done comfortably in the web interface, and you may generate as many service tokens as needed for your accounts.

Important

The system setting HttpType must be https for production systems using external services like GMail and Office365.

You can set this using the command-line as follows:

[otrs@host ~]$ bin/otrs.Console.pl Admin::Config::Update --setting-name HttpType --value https

Alternatively, you can search for HttpType in the system configuration and set it there.

Note:

After configuration, it may be necessary to edit the endpoints manually, as the service provider can change the requirements at any time.

AddOAuth

The following fields are needed:

Name: A name for the token.

Client ID: Your client id. (The public identifier.)

Client secret: Your client secret. (The application’s own password.)

Validity: The validity of the setting.

Template: Shows the template that was used to create this OAuth2 token configuration.

Types of Notifications to be shown

Expired token: Shows a notification for admins below the top menu if the OAuth2 token has expired.

Expired refresh token: Shows a notification for admins below the top menu if the OAuth2 refresh token has expired.

Edit a Token

You can edit the token at any time.

EditOAuth

Note:

The template type is permanent once the token is saved.

Token Overview

It the token overview, it is necessary to manually request a new token upon token setup and as required by your service provider. You will receive front-end notifications as configured to inform you when the token or refresh token has expired.

Overview

Token Notifications

In the notification area, you receive notifications if a token or refresh token has expired. Clicking the notification will send you to the administration module for renewal. You may then click on refresh to get a new token.

Notification

Note:

When a refresh token expires, you must generate a new one with your service provider.

Backup and Migration

Export and import settings using the function provided in the left sidebar.

Backup

Note:

The option to overwrite settings only changes those settings of the same name.

Vendor-Specific Documentation

Important

Redirect URI: The redirect_uri for Znuny is built from the system variables in the following manner:

${HttpType}://${FQDN}/${ScriptAlias}/get-oauth2-token-by-authorization-code.pl

https://serviceup.example.com/otrs/get-oauth2-token-by-authorization-code.pl

As each setup is specific to your vendor, please read more about setting up a token at the vendor site.

Microsoft

Google

PostMaster Mail Account

In the configuration of PostMaster email accounts, the option of OAuth2 authentication is available.

When selecting this option, or the OAuth2 token configuration field, it becomes available, and must be chosen to configure the account that is being registered.

PostMaster

Templates

The configuration templates are accessible here.

In the case of Microsoft Email configuration, it may be necessary to change the template's authentication URL and token. And also the scope for token generation and automatic refresh (refresh token).

AuthorizationCode:
    Request:         
      URL: https://login.microsoftonline.com/{TenentID}/oauth2/v2.0/authorize

TokenByAuthorizationCode:
    Request:          
      Parameters:
        grant_type: authorization_code
      URL: https://login.microsoftonline.com/{TenentID}/oauth2/v2.0/token
 TokenByRefreshToken:
    Request:          
      URL: https://login.microsoftonline.com/{TenentID}/oauth2/v2.0/token

Scope: offline_access https://graph.microsoft.com/IMAP.AccessAsUser.All https://graph.microsoft.com/POP.AccessAsUser.All https://graph.microsoft.com/SMTP.Send https://graph.microsoft.com/offline_access