Support Support HYPERPLANNING

  • How to send e-mail via the OAuth protocol?

The OAuth protocol makes it possible not to give an application a username and password that would allow it to do everything when accessing a service, but to give it just the necessary authorizations to do what it is supposed to do.
These authorizations are granted in the form of two "tokens:
  • an access token, valid for a short time, usually one hour,
  • a refresh token, valid for a much longer duration and which allows the access token to be renewed without having to constantly ask for user intervention.
To obtain the tokens, the user is invited to authenticate in a web browser separate from the application (so that the latter does not intercept the identifiers).
This authentication phase is driven entirely by the targeted service and not by the application.
This can be a multi-factor authentication, for example with a verification code sent by SMS or e-mail.
Only once the user is authenticated and has agreed to the requested authorizations are the tokens communicated to the application.

At any time, the user can directly reconnect to his/her service to consult or invalidate the authorizations already granted.
Everything is done to ensure that neither his username nor his password is compromised.

Identification of the application with the service

The services only grant authorizations to known applications. Therefore, a prior declaration is required to obtain:
  • a client ID to identify the application,
  • a client secret which must be hidden and which prevents an application from masquerading as another.


For the Microsoft SMTP server smtp.office365.com, you can use an application predefined by Index Education. You will avoid this step.
Otherwise, you have to declare the application yourself to get an client ID and a client secret. You can consult these two sections in this document below:
  • Register the application yourself with a Google service;
  • Register the application yourself with a Microsoft service.
Important parameter: Index Education applications use as the redirection URI
https://execonnect.index-education.com/callback

Identification of the service with the application

The application needs several URL called endpoints to initiate exchanges with the service. You can get these endpoints in the interface where you registered the application.

In the case of the application predefined by Index Education, these endpoints are pre-filled.

Register the application with a Google service yourself

For the service:
To begin, you must connect to https://console.cloud.google.com/home/dashboard, then click on API and services.
  1. Create a new project, give it a name (without accented character), then make sure the new project is selected. This name is not the one the user will see.
  2. Click on Library then click on Gmail API. Activate the API Gmail.
  3. At the top left, click on the parameter menu (hamburger menu) and go back to API and services.
  4. Then click on the left in OAuth consent screen and complete the information.
  5. In the second screen Scopes, click on the button ADD OR REMOVE SCOPES. Under Manually add scopes, paste https://mail.google.com/, click on ADD TO TABLE, then on UPDATE.
  6. For the question What features will you use?, choose Email client.
  7. Finish the configuration.
  8. On the left, click on Credentials, then on + CREATE CRDENTIALS, OAuth client ID.
    • Application type: Web application
    • Name: execonnect.index-education.com
    • Authorized redirects URI: https://execonnect.index-education.com/callback
  9. A pop-up window appears with the client ID and client secret: these two settings must be kept they will be entered in the application.
For the application:
In the application, now enter the following elements:
  • Client ID, Client secret: paste the previous stored values
  • Authorization Endpoint: https://accounts.google.com/o/oauth2/v2/auth?prompt=consent&access_type=offline
  • Token Endpoint: https://oauth2.googleapis.com/token
  • Requested authorizations: https://mail.google.com/

You can then obtain OAuth tokens.

Note:
  • The parameters prompt=consent&access_type=offline are needed to get an access and refresh token.
  • The authorization https://www.googleapis.com/auth/gmail.send (Sending e-mails on your behalf) is not enough to send an e-mail via an SMTP server, you need https://mail.google.com/ (full access to the mailbox). See OAuth 2.0 Mechanism

Declare the application yourself on a Microsoft service

For the service:
To begin, you must log on to https://portal.azure.com/, then click on Azure Active Directory.
  1. On the left, click on App registrations, then on top click on + New registration. Choose the type of accounts you want to support, then in the Redirect URI, choose Client public/natif (mobile & bureau) with the URI https://execonnect.index-education.com/callback.
  2. Once the application is added, click on Branding and properties, fill in the fields and click on Save.
  3. Click on Authentication, then on the very bottom Allow public client flow, tick Yes. Click on Save.
  4. On the left, click on API permissions, then on + Add a permission, Microsoft Graph, Delegated permissions. Under User, un-tick User.Read, then under SMTP, tick SMTP.Send. Then, on the very bottom, click on Add permissions.
  5. On the left, click on Overview.
  6. Copy the value in front of App ID (client), and keep it, it will be entered in the application.
  7. On top, click on Endpoints and copy the first two values, OAuth 2.0 authorization endpoint (v2) and OAuth 2.0 token endpoint (v2) they will be entered in the application.
For the application:
In the application, now enter the following elements:
  • Client ID: paste the previous stored values
  • Client secret: leave this field empty, the public applications are authorized
  • Authorization and token endpoints: paste the two other values kept previously
  • Requested authorizations: https://outlook.office.com/SMTP.Send offline_access
You can obtain the OAuth tokens.

Note:
  • The authorization https://outlook.office.com/SMTP.Send differs from the one registered in the application (SMTP.Send de Microsoft Graph), but only one token obtained with authorization  https://outlook.office.com/SMTP.Send allows you to send an e-mail via a SMPT server. See Authenticate an IMAP, POP or SMTP connection using OAuth
  • The offline_access permission is required to obtain an access and refresh token.

Using the OAuth protocol for limited input devices

There is a variant of the OAuth protocol called Device Authorization Grant that allows a limited input device (e.g., a connected TV) to request an OAuth token. If you have problems with the default OAuth flow, you can use this protocol variant which also works for desktop applications..

In the application, hold down the Ctrl and Shift keys when you click on the button to enter in the OAuth configuration window: this allows you to switch to the Device Authorization Grant flow. In this flow, the authorization endpoint is replaced by a device endpoint.

Caution, this does not work with the Google services because it cannot ask for the https://mail.google.com/ authorization. See Allowed Scopes

However, it does work with the Microsoft services.
Just be aware that the device endpoint is deduced from the authorization endpoint by changing the ending authorize with devicecode :
  • https://login.microsoftonline.com/common/oauth2/v2.0/authorize becomes 
  • https://login.microsoftonline.com/common/oauth2/v2.0/devicecode
  • https://login.microsoftonline.com/{xxx}/oauth2/v2.0/authorize becomes
  • https://login.microsoftonline.com/{xxx}/oauth2/v2.0/devicecode
Was this content useful to you?
https://docs.index-education.com/docs_en/en-hyperplanning-support-page-232-2434-how-to-send-e-mail-via-the-oauth-protocol.php

Can't find an answer to your question ?

Contact our support

INDEX ÉDUCATION | © 2024 - B