# IMAP - Microsoft 365 - Setup Account

Zuar Runner uses OAuth 2.0 to gain access to the contents of your Microsoft 365 or
Outlook.com mail.  This requires the creation of an "app" in Microsoft Entra ID
(formerly known as Active Directory) that can act on your behalf.  Once the app has been
created, the credentials associated with the app are used to authenticate Zuar Runner to
Microsoft when your IMAP job(s) run.

Microsoft documentation describing how to do this can be found
[here](https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#register-your-application)
and [also here](
https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app).


.. |register| image:: assets/m365-setup-account__register.png
.. |overview| image:: assets/m365-setup-account__overview.png
.. |secret-1| image:: assets/m365-setup-account__secrets-1.png
              :alt: client secret
.. |secret-2| image:: assets/m365-setup-account__secrets-2.png
              :alt: client secret
.. |permissions-1| image:: assets/m365-setup-account__permissions-1.png
                   :alt: permissions
.. |permissions-1b| image:: assets/m365-setup-account__permissions-1b.png
                   :alt: permissions
.. |permissions-2| image:: assets/m365-setup-account__permissions-2.png
                   :alt: permissions
.. |permissions-3| image:: assets/m365-setup-account__permissions-3.png
                   :alt: permissions


.. NOTE::

   * You only need to create one "app" within Azure AD, regardless
     of the number of IMAP jobs you wish to create.
   * Once created, the "app" can be used by anyone with an email
     address in your organization.

## Prerequisites

1. An Azure account that has an active subscription.
1. The account must have an administrator, or developer role assigned
   to it.

## Register an Application in Azure AD

1. Signin to the [Azure Portal](https://portal.azure.com).
1. If you have multiple tennants, ensure that you are in the correct
   tennant.
1. Search for and select "Microsoft Entra ID".
1. Navigate: `Manage --> App registrations --> New registration`
   1. Name your applications
   1. Select the correct account type.
      |register|
   1. Click `Register`
1. The app's Overview page will be displayed.
   |overview|
1. Make a copy the `Application (client) ID` (`client_id`) and `Directory
   (tenant) ID` (`tenant_id`).  You'll use these later when creating a job
   using the wizard.

## Create Application Credentials

1. On the app's Overview page, click `Certificates & secrets`.
1. Click `+ New client secret`.
   |secret-1|
1. Make a copy of the `Secret ID` (`client_secret`) for later use.
   |secret-2|

## Grant Permissions to Application

### API Permissions

1. On the app's Overview page, click `API Permissions`.
1. Use `+ Add a permission`.
1. Under `Select an API`, click `APIs my organizaiton uses`.
1. In the search box, type "Office 365 Exchange Online".
1. From the list that is displayed, click on `Office 365 Exchange
   Online`.
1. Under `What type of permissions...`, click `Application Permissions`.
1. Under `IMAP` click `IMAP.AccessAsApp`.
   |permissions-1|
1. Click `Add permissions`.
1. Click `Grant admin consent for ...` to grant admin permissions to `IMAP.AccessAsApp`.
   |permissions-1b|

### Authentication

1. On the app's Overview page, click `Authentication`.
   1. Under `Advanced Settings`, click `Yes` for `Enable the following mobile and
      desktop flows:`
   1. Click `Save`

|permissions-2|

### Microsoft Graph Permissions

1. On the app's Overview page, click `API Permissions`.
1. Under `API permissions`, click `Microsoft Graph`.
1. Select the following permissions:
   * `email`
   * `offline_access`
   * `openid`
   * `profile`
   * `IMAP.Access.AsUser.All`
   * `User.Read`
1. Click `Update Permissions`.

### Confirm Permissions

When you are done, you should have the following permissions:
|permissions-3|

## Credentials

You have successfully configured an app within Azure that can be used
with Zuar Runner's IMAP job. 

You should have collected credentials similar to the
following (the format is unimportant):

```
client_id = 9aef02cb-6efb-485f-91b8-ea57fda29d68
client_secret = utM8Q~xHAJt4PSCZzDKlL5P~WPgSlautR-VMrdsR
tenant_id=abdfa575-4bf4-4e51-878b-14e280eab912
```

You'll need these credentials when you run the IMAP wizard
to create an IMAP job.  Instructions for doing that can 
be found [here](m365-create-job).