====== Setting Up OAuth Client Authentication via Microsoft 365 with eBiss ======

===== Part 1: Setup in the Azure Portal =====

==== 1.1 Create App Registration ====

In the Azure Portal, navigate to **Entra ID** and select **Manage → App Registrations → New Registration**.

Configure the following settings:

  * Enter a unique name for the application.
  * Select the supported account types (default: //Accounts in this organizational directory only, Single Tenant//)
  * Click **Register**.

==== 1.2 Note Down Client ID and Tenant ID ====

After registration, two important IDs are displayed that will be needed for all subsequent steps:

^ Name ^ Description ^
| **Client ID** | Also called "Application ID". Unique identifier for this app registration. |
| **Tenant ID** | Also called "Directory ID". Identifies the Azure AD tenant (the organization). |

<WRAP important>
⚠ Note down both IDs now – they will be required later in the PowerShell commands.
</WRAP>

==== 1.3 Create Client Secret ====

<WRAP info>
**Note:** Certificate credentials are currently not supported. A Client Secret must be used.
</WRAP>

Navigate to **Certificates & Secrets → Client Credentials → New Client Secret**.

  * Choose a description and an expiry duration.
  * Click **Add**.

<WRAP important>
⚠ The Client Secret is only shown once! Copy and store it securely immediately after creation.
</WRAP>

==== 1.4 Note Down the Enterprise Object ID ====

In Entra ID, navigate to **Enterprise Applications**. Find and open the newly created app registration in the list.

^ Name ^ Description ^
| **Object ID** | The ID of the enterprise application object – different from the Client ID of the app registration. |

==== 1.5 Add API Permissions ====

Navigate back to the app registration under **API Permissions → Add a Permission**.

  * Select the **"APIs my organization uses"** tab.
  * Search for "SMTP" and add the **SMTP.SendAsApp** permission.
  * Search for "POP" and add the **POP.AccessAsApp** permission.

<WRAP important>
⚠ These permissions require admin consent. Ask an Azure administrator to approve the permissions ("Grant admin consent").
</WRAP>

===== Part 2: Configuration via PowerShell =====

The following steps must be executed by an **Exchange Administrator** in PowerShell.

==== 2.1 Load and Connect Exchange Online Module ====

<code powershell>
Import-Module ExchangeOnlineManagement

Connect-ExchangeOnline -Organization <Tenant ID>
</code>

^ Cmdlet ^ Description ^
| ''Import-Module'' | Loads the Exchange Online PowerShell module, which provides the specific cmdlets for Exchange management. |
| ''Connect-ExchangeOnline'' | Establishes an authenticated connection to Exchange Online. The ''-Organization'' parameter specifies the Tenant ID to address the correct tenant. |

==== 2.2 Register Service Principal ====

<code powershell>
New-ServicePrincipal -AppId <Client ID> -ObjectId <Object ID> -DisplayName <DisplayName>
</code>

^ Cmdlet ^ Description ^
| ''New-ServicePrincipal'' | Registers the Azure AD app registration as a Service Principal in Exchange Online. Only then does Exchange recognize the app as an authorized actor. AppId = Client ID, ObjectId = Enterprise Object ID, DisplayName is freely selectable (from step 1.4). |

==== 2.3 Enable SMTP Authentication ====

Choose one of the two options:

=== Option A: For a single mailbox only ===

<code powershell>
Set-CASMailbox -Identity <user@domain.com> -SmtpClientAuthenticationDisabled $false
</code>

^ Cmdlet ^ Description ^
| ''Set-CASMailbox'' | Configures the Client Access Services (CAS) for a single mailbox. With ''-SmtpClientAuthenticationDisabled $false'', SMTP Auth is enabled specifically for this mailbox, even if it is disabled organization-wide. |

=== Option B: Organization-wide ===

<code powershell>
Set-TransportConfig -SmtpClientAuthenticationDisabled $false
</code>

^ Cmdlet ^ Description ^
| ''Set-TransportConfig'' | Changes the global transport configuration for the entire organization. Enables SMTP client authentication for all mailboxes. Only recommended if all mailboxes require SMTP Auth. |

==== 2.4 Grant Mailbox Permissions ====

<code powershell>
Add-MailboxPermission -Identity <user@domain.com> -User "<DisplayName>" -AccessRights FullAccess
</code>

^ Cmdlet ^ Description ^
| ''Add-MailboxPermission'' | Grants the Service Principal (referenced by the DisplayName from step 2.2) full access (FullAccess) to the specified mailbox. Required so the app can read and manage emails (e.g. via POP). |

<code powershell>
Add-RecipientPermission <user@domain.com> -Trustee "<DisplayName>" -AccessRights SendAs
</code>

^ Cmdlet ^ Description ^
| ''Add-RecipientPermission'' | Allows the Service Principal to send emails on behalf of the specified mailbox ("Send As"). The Trustee is the DisplayName of the Service Principal from step 2.2. |

===== Part 3: Configuration in eBiss3 =====

The communication channels are configured in eBiss3 under **Communication Channels**. The following settings apply to both channels unless stated otherwise.

==== 3.1 SMTP Send (Outgoing Emails) ====

^ Parameter ^ Value ^
| **Host** | ''smtp.office365.com'' |
| **Port** | ''587'' |
| **SSL Behavior** | Explicit (STARTTLS – connection starts unencrypted, then upgraded to TLS) |
| **Authentication** | OAuth 2.0 |
| **Username** | Full email address of the sender (e.g. ''sender@domain.com'') |
| **Client ID** | Client ID from step 1.2 |
| **Client Secret** | Client Secret from step 1.3 |
| **Server URL** | ''<nowiki>https://login.microsoftonline.com/<Tenant-ID>/oauth2/v2.0/token</nowiki>'' |
| **Auth URL / Scope** | ''<nowiki>https://outlook.office365.com/.default</nowiki>'' |

==== 3.2 POP3 Receive (Incoming Emails) ====

The configuration largely mirrors the SMTP Send channel. The following parameters differ:

^ Parameter ^ SMTP Send ^ POP3 Receive ^
| **Host** | ''smtp.office365.com'' | ''outlook.office365.com'' |
| **Port** | ''587'' | ''995'' |
| **SSL Behavior** | Explicit | Implicit (direct TLS connection without prior plaintext handshake) |

All other parameters (Authentication, Username, Client ID, Client Secret, Server URL, Auth URL) remain identical to SMTP Send.

----

Once all three parts are complete, the OAuth 2.0 connection between eBiss3 and Microsoft 365 is fully configured.