Microsoft provides different APIs to access Exchange Online. To authenticate against these APIs, we need OAuth access token with appropriate permissions when invoking these APIs. And this type of access token is obtained from Azure AD.
A little background, in order to access Microsoft resource eg. Azure, Exchange Online, SharePoint via Microsoft APIs, the entry point via an identity (or service principal). In this case, it would be by creating an Azure AD app registration.
In Azure AD, an API is granted either with delegated permission or application permission. When using Client Credential flow in Azure AD, the access token is acquired as application identity with only the application permission (delegated permission is not used since there is no user). The scope used during access token request is with *./default scope, for example https://graph.microsoft.com/.default or https://outlook.office365.com/.default depending on which API you are using.
To configure the access restriction of the application, we will need the Exchange Online PowerShell module (ExchangeOnlineManagement). It is the Microsoft Exchange Online administrative interface to Microsoft Exchange Online. To install the PowerShell module,
Install-Module -Name ExchangeOnlineManagement -Scope CurrentUserConnect to the organization Microsoft Exchange Online, enter the credential in the interactive prompt
Connect-ExchangeOnlineDepending if your account has the appropriate role in the organization eg. global admin, exchange admin, etc. it appears to subsequently downloads dynamic module to user path like this, C:\Users\abc\AppData\Local\Temp\tmpEXO_xyzabc10.a12\ where the module seems to contain similar cmdlets like the ones in PowerShell module.
To locate the dynamic module, you can lookup some cmdlet eg.
Get-Command Get-ServicePrincipalWith all the tools and some background covered, here are the two examples of using OAuth to access Office 365 Exchange Online mailbox. One using Legacy Office 365 Exchange Online API to access and read mails of a mailbox via IMAP/POP, and another using Graph API to send mail as the user. Please be aware these are not the only ways, but simply an example. Microsoft provide several other ways to achieve to read and send mails with OAuth.
In order to access the APIs, we need a valid access token with appropriate permission (scope) from Azure AD. First we need to create a application service principal via app registration.
Login to Azure portal, go to Azure Active Directory. Select app registration and select new registration.
Since the application will be using client credential flow, the default option without any redirect URI is sufficient.
Next we will need to create a Client Secret. Select certificates & secrets on the left menu and click on Client secrets and create a new client secret. Keep the Client Secret for later use.
Next we need to grant API permission to the application. Select API Permissions on the left menu, and add a permission.
For Graph API, select Microsoft Graph, click on Application Permissions.
Search for mail, and check Mail.Send. Notice that the permission will allow the application to send mail as any user. We will restrict its access via application access policy described later.
For Office 365 Exchange Online API, select APIs my organization uses tab, search for office and select Office 365 Exchange Online. click on Application Permissions.
Search for and check IMAP.AccessAsApp (if you need to access via POP, check POP.AccessAsApp).
Grant admin consent to the permissions added.
We need to get the ApplicationID (ClientID) and ObjectID of the application service principal for later use. Go to Enterprise Applications on the left menu
Search for the application and note down the ObjectID and ApplicationID.
The app registration is now completed. If needed, you can verify if the access token could be obtained. It is important to know ahead which API you are trying to invoke so you can obtain an access token with correct audience (aud claim in the JWT). For Graph API, use https://graph.microsoft.com/.default as the scope; And for Office 365 Exchange Online API, use https://outlook.office365.com/.default as the scope. Here is an example acquiring an access token for Graph API usage.
$tenantid = 'your tenant id' $clientid = 'your app client id' $clientsecret = 'your app client secret' $token = Invoke-RestMethod -Method Post -ContentType 'application/x-www-form-urlencoded' -Uri "https://login.microsoftonline.com/$tenantid/oauth2/v2.0/token" -Body @{ client_id = $clientid client_secret = $clientsecret scope = 'https://graph.microsoft.com/.default' grant_type = 'client_credentials' } $token.access_tokenYou can copy/paste to view the decoded access token (JWT) here. See the below example of the aud claim and scope with Mail.Send role (permission) configured earlier.
Legacy Office 365 Exchange Online APIs
In the API permission, we granted IMAP.AccessAsApp or POP.AccessAsApp access to the application service principal. This allows the application to access IMAP or POP. However, the application can't access any mailbox yet. And to allow it to access specific mailbox, we first need to add the service principal in exchange online and then grant that service principal permission (delegation) to the mailbox.
Create an exchange service principal. Use the AppId and ObjectId from the Azure AD application registration.
New-ServicePrincipal -AppId c33aa7**-****-****-****-******ffca0d -ServiceId c21b49**-****-****-****-******f33f47 -Organization 'tenant id' -DisplayName mailtestTo grant permission for service principal to a mailbox (add delegation),
Add-MailboxPermission -Identity "usera@emaildomain.com" -User c21b49**-****-****-****-******f33f47 -AccessRights FullAccessTo check the existing permission (delegation) on a mailbox,
Get-MailboxPermission -Identity "usera@emaildomain.com"More information to configure for IMAP/POP can be found here.
To verify the IMAP access with the application, you can use this PowerShell script written by one of the Microsoft employee for verification.
$tenantid = 'tenant id' $clientid = 'c21b49**-****-****-****-******f33f47' $clientsecret = '***************************' $maibox = 'usera@emaildomain.com' .\Get-IMAPAccessToken.ps1 -tenantID $tenantid -clientId $cliendid -clientsecret $clientsecret -targetMailbox $mailbox
Graph API
For Graph API, understand that granting API Application Permission usually allow it access to all tenant resources. For example, Mail.Send permission allows it to send mail as any user; Mail.Read permission allows it to read mail in all mailboxes. To restrict it to specific mailbox / security group, creates an Application Access Policy.
Note, as of this writing, if there is no application access policy existed, the get application access policy cmdlet returns an error.
Get-ApplicationAccessPolicyWrite-ErrorMessage : Ex6F9304|Microsoft.Exchange.Configuration.Tasks.ManagementObjectNotFoundException|The operation couldn't be performed because object 'OU=abcefg.onmicrosoft.com,OU=Microsoft Exchange Hosted Organizations,DC=ABCDE123456,DC=PROD,DC=OUTLOOK,DC=COM\*' couldn't be found on 'AABBCC112233000.ABCDE123456.PROD.OUTLOOK.COM'. At C:\Users\abc\AppData\Local\Temp\tmpEXO_xyzabc10.a12\tmpEXO_xyzabc10.a12.psm1:1113 char:13 + Write-ErrorMessage $ErrorObject $IsFromBatchingRequest + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : NotSpecified: (:) [Get-ApplicationAccessPolicy], ManagementObjectNotFoundException + FullyQualifiedErrorId : [Server=ABCDEFGHIJ123,RequestId=abcd-efgh-3e96-e79a-123456789012,TimeStamp=Sat, 31 S ep 2022 25:02:47 GMT],Write-ErrorMessage
To add application access policy to restrict application access to certain mailbox or security group, use the AppId during the Azure AD application registration. The PolicyScopeGroupId is the mailbox or security group that can be only access by the app.
New-ApplicationAccessPolicy -AccessRight RestrictAccess -AppId c33aa7**-****-****-****-******ffca0d -PolicyScopeGroupId usera@emaildomain.com -Description "restrict mailtest access"To test the policy against the restricted account or/and other account, the AccessCheckResult returns if the effective access is denied or granted.
Test-ApplicationAccessPolicy -AppId c33aa7**-****-****-****-******ffca0d -Identity usera@emaildomain.comFrom the experience, even thought the test command responded the testing result of the policy, in practical the policy could take more than 1 hour to be effective. From personal experience, it takes about an hour.
To list all existing application access policy,
Get-ApplicationAccessPolicyPlease note that the Application Access Policy only applicable to certain Microsoft Graph application permission. As of the time of writing,
Mail.Read
Mail.ReadBasic
Mail.ReadBasic.All
Mail.ReadWrite
Mail.Send
MailboxSettings.Read
MailboxSettings.ReadWrite
Calendars.Read
Calendars.ReadWrite
Contacts.Read
Contacts.ReadWrite
Exchange Web Services permission scope: full_access_as_app.
More information can be found here.
No comments:
Post a Comment