OAuth Setup for Microsoft Services

NoteThis feature is not available in versions of Gemini prior to 7.1.0

Configuring OAuth is a two-step process. First you configure Microsoft Services to know about Gemini. Then you configure Gemini to use these services.

Microsoft 365 Configuration

Create an application in Azure

Navigate to the Azure Portal and login (at the time of writing, this was Portal.Azure dotcom).

On the menu of services, select Azure Active Directory.

Select Azure App Registrations

If this is the first time you are setting this up, add a new application registration.

Give your application a name e.g. Gemini Email Connector. Choose the access level (defaults will suffice for 99% of users). Do not specify a Redirect URI.

Click Register

Configure your application

On registering your application there are 2 values that are applied to it that are essential.

  • The Application(Client) ID
  • The Tenant(Directory) ID

Note these, you will use them to configure Gemini later.

Select authentication from the menu

Add a platform and select Web application from the list of choices.

Enter the Redirect URI. This will be in the format https://yourServer.com/Admin/OAuthCallback, where yourServer.com is the url of your Gemini instance.

NoteYour Gemini site must be hosted on an SSL connection (https) as http redirects are not permitted.

Click Configure

Select Certificates & secrets

Create a new client secret

NoteIf you wish to use a certificate instead, please refer to the Microsoft documentation on the subject.

Enter a secret that will be encoded when you click "Add"

NoteWe recommend you set your secret expiry to the longest available period, so Gemini does not suddenly stop working with email.

NoteCopy the encoded secret immediately! It cannot be seen again anywhere in the portal.

Gemini Mailbox Configuration

To use OAuth with Gemini mailboxes, you can choose to configure the connection as Exchange(EWS) or IMAP

IMAP Configuration

Specify OAuth2 as the Authentication Mode

When you do this you will be prompted for an OAuth Provider. Select Microsoft.

You must use SSL and we recommend you leave the SSL protocol as Auto so Gemini can select the most modern.

Exchange(EWS) Configuration

Selecting Exchange will require you to select the Exchange version. Select Office365_OAuth.

The Exchange Web Server URL will be defaulted for you. The domain is likely to remain empty for O365 and OAuth

Generic OAuth Configuration

4 new fields have been added to Gemini's Mailbox/SMTP configuration

  • Tenant ID - the Tenant ID from your Azure application
  • Client ID - the Client ID from your Azure application
  • Client Secret - the Client Secret from your Azure application
  • Scopes - A field that will auto-populate for you

Save your configuration when you have provided the mandatory details. You will be redirected and required to authenticate with your OAuth provider

Note You must authenticate the MAILBOX email account e.g. support@company.com, not your own account or an admin account.

Confirm the access permissions and you'll be returned to Gemini, where you should see a success message

Gemini SMTP Configuration

OAuth configuration is the same for both the generic system mailbox in System Email Options, and the SMTP mailbox(es) for Breeze Ticketing

Navigate to Ticketing...SMTP Servers and edit or add a new SMTP connection

Provide a name for your SMTP Server. For Microsoft OAuth, the server and port should be as shown above.

Select OAuth2 from the Authentication Modes drop down. You will see the form present new fields.

The scopes will be automatically populated, but complete the rest of the fields as per the Azure AD Application details created earlier.

Save the configuration. On Ticketing SMTP servers you should get a simple success message. On System Email Options, you will get a verbose trail of Gemini testing the SMTP connection.

Related