Howto16r1:Configure OAuth2 E-Mail
|
FIXME: This product is in the beta phase and is not yet finished |
The innovaphone PBX and apps can be configured to send E-Mails for various subjects and purposes. Major E-Mail providers intent to discontinue the username/password authentication schemes in favour of OAuth2. PBX and Apps version 16r1 does support OAuth2 authentication for SMTP. Here is a step by step guide how to set up OAuth2 support in Microsoft 365 through the Azure Portal and how to set it up on a Google Gmail account in the Google Cloud Console.
General Information
Most of the large email providers offer the possibility to define an app that is allowed to gain access of a certain scope like SMTP.
It assigns a Client ID / Client Secret.
Authorization for sending from the mail account needs to be given one time either:
- By providing resource owner username/password. Sending this to the token endpoint results in an access token and long term refresh token.
- By interactive authorization via a popup dialogue that is loaded from the authorization endpoint. After the credentials are verified, the dialogue redirects to the redirect URI with an authorization code that is traded to an access token and refresh token.
The access token is sent for authentication in SMTP. It needs regular refresh, which will be done automatically.
Modes
- Exchange: Microsoft, with interactive authorization
- Microsoft 365: Microsoft, without interactive authorization (Resource owner and password has to be filled)
- Gmail: Google, with interactive authorization
- Google Service Account: Google, without interactive authorization (Client e-mail, Private Key ID and Private Key of the service account must be provided)
- Client secret post: Generic configuration where all parameters of the client secret post OAuth2 flow can be set.
- Private key jwt: Generic configuration where all parameters of the private key jwt OAuth2 flow can be set.
Example Redirect URIs
- PBX: https://example-pbx.domain.com/OAUTH2-CLIENT/auth.htm
- Reporting: https://example-ap.domain.com/domain.com/reporting/auth.htm
- Fax: https://example-ap.domain.com/domain.com/fax/auth.htm
- Users: https://example-ap.domain.com/domain.com/usersapp/auth.htm
- Connect: https://example-ap.domain.com/domain.com/messages/auth.htm
- AP Manager: https://example-ap.domain.com/manager/auth.htm
Microsoft 365
Azure Portal
Log in to Microsoft Azure Portal (https://portal.azure.com) and go to Microsoft Entra ID.
Add a new app registration to create client credentials.
Register the application and maybe already fill in the redirect URI for Web based application type to path OAUTH2-CLIENT/auth.htm at the PBX.
App registration is complete. Client ID and tenant needs to be configured at the PBX and every app that will be sending e-mails.
Create a client secret. Note that expiry is limited to no longer than 2 years. The client secret must be renewed before expiry and the new secret configured and interactive authorisation carried out again to ensure continuous operation.
Copy the client secret. It also needs to be configured at the PBX and every app that will be sending e-mails.
Add permissions located in APIs my organization uses.
More precisely located in Office 365 Exchange Online.
And there in the application permissions.
Namely SMTP Mail.Send.
Grant admin permission for Mail.Send.
API permissions are now granted.
Tell all redirect URIs that the PBX and the apps will be using during interactive authorization.
Allow public client flows of OAuth2. Resource Owner Password Credentials Flow has the advantage that it doesn't need interactive authorization.
Microsoft 365 admin center
Log in to the Microsoft 365 admin center (https://admin.cloud.microsoft).
Make sure that Microsoft 365 licenses are assigned to your user.
Set your user active.
Locate the Mail tab of your user.
Allow authenticated SMTP.
Exchange admin center
Login to the Exchange admin center (https://admin.exchange.microsoft.com).
Remove deactivation of the SMTP AUTH protocol.
PBX Example configuration
With this Microsoft setup the OAuth2 configuration for the resource owner password credentials flow can be filled in as follows.
For interactive authorization this is the OAuth2 configuration. Authorize e-mail access one time and send a test mail to verify everything went well.
Gmail
Preparations
Login to the Google Cloud Console (https://console.cloud.google.com), select a project, New project.
Create the project.
Client credentials will be created in this project.
From the library specify the APIs needed to access.
These are in the Gmail API.
Choose the Gmail API and enable it.
Credentials need to be created.
Invoke the help me choose wizard.
User data access is needed.
Configure the consent screen of the interactive authorization.
Specify the permissions that need to be authorized by the user.
Its mail.google.com in general.
And its to send email on the users behalf.
These are the scopes needed.
Ask client credentials for Web type application.
Tell all redirect URIs that the PBX and the apps will be using during interactive authorization.
Download the credentials. This json file contains all information for OAuth2 configuration.
Customize the OAuth consent screen
Start the customization wizard.
Choose which users may authorize.
Google workspace users may choose internal audience. Users not in Google workspace proceed with external.
Add a test user.
PBX Example configuration
The OAuth2 parameters can be filled in with the information from the json file downloaded above. Authorize e-mail access one time and send a test mail to verify everything went well.
Generic
For other e-mail providers the client secret post OAuth2 flow may be configured in a generic way. Details need to be supplied by the e-mail provider.
For the Microsoft 365 setup above it would be as follows with Token endpoint https://login.microsoftonline.com/af326a34-169c-469e-946b-1ef57925306b/oauth2/v2.0/token Authorization URL https://login.microsoftonline.com/af326a34-169c-469e-946b-1ef57925306b/oauth2/v2.0/authorize?scope=https://outlook.office.com/SMTP.Send offline_access The configuration appends &response_type=code&prompt=consent&login_hint=...&redirect_uri=...&client_id=... automatically.
For the Gmail example above the generic confguration would be like this with Token endpoint https://oauth2.googleapis.com/token Authorization URL https://accounts.google.com/o/oauth2/auth?access_type=offline&scope=https://mail.google.com/ The configuration appends &response_type=code&prompt=consent&login_hint=...&redirect_uri=...&client_id=... automatically.
The private key jwt OAuth2 flow can be configured generically as well.
Related Articles
- Reference16r1:PBX/Config/Authentication
- Reference16r1:Apps/PbxManager/Email
- Reference16r1:Concept App Connect#E-Mail configuration
- Reference16r1:Concept App Service Fax#Mail Configuration (SMTP_Server)
- Reference16r1:Concept App Service Reports#Configuration
- Reference16r1:Concept App Service Users#Users Admin App (innovaphone-usersadmin)
- Reference16r1:Concept App Platform#SMTP