Shared Email and Access Groups Customers: MS Graph API Setup Process

Configuring Microsoft's Graph API for multiple addresses

Grant Approval to Prokeep

After providing Prokeep Support with a list of email addresses that you intend to enable with Prokeep shared email, as well as the corresponding Prokeep groups, this process will begin with you receiving an email from Prokeep requesting your Azure Tenant ID. The Tenant ID can be found in your Tenant Properties service in Azure.

After this, Prokeep Support will configure these channels, and you will receive another email  requesting access to your MS Graph API.

Click Grant Administrator Consent and log into your Microsoft Account. You will then see this screen requesting that you grant Prokeep permission to utilize your emails. Once you have reviewed the permissions you will be granting us, click Accept.

Restrict Approval to Specific Email Addresses

Set up Powershell and Log into Exchange

General Disclaimer

By default, application consent is granted tenant wide, so any email address on your account could be configured to work with Prokeep. This will not result in all emails immediately flowing into Prokeep inboxes, but does mean that any email address on your account could be configured to work with Prokeep.

 

 If you would like to restrict access to only allow specific emails to be configured with Prokeep, please follow the remainder of the steps outlined below.

 

These steps were built via Microsoft's documentation for limiting application mailbox access here.

 

Many of the following steps must be done in PowerShell as an Administrator. Please Install Microsoft Powershell if you have not already done so.

Ensure the module ExchangeOnlineManagement is installed

This step may be skipped if the module is already installed.

 

(All Users)

 

(Current User)

Note: You may be prompted to allow NuGet, and allow module installation from PSGallery if this has not already been done on your system.

 

The image above depicts Installing ExchangeOnlineManagement in PowerShell. For further details, see Microsoft's documentation on the PowerShell module here.

Ensure Scripts can be ran in your environment

Check the output of the command:

 

On Windows Clients this policy must be one of the following:

[Unrestricted | RemoteSigned | AllSigned | Bypass]

 

On Windows Servers this policy must be one of the following:

[Unrestricted | RemoteSigned | AllSigned | Bypass | Default | Undefined]

 

If your environment/policy combination is not on this list, the module ExchangeOnlineManagement will not be able to run and you will need to use the command Set-ExecutionPolicy or speak with an Administrator about elevating your permissions to do so.

 

For further details, see Microsoft's Execution Policy documentation here

 

Load ExchangeOnlineManagement and Connect

Load the module in your session

Connect and authenticate to exchange online given your username, formatted as an email addres, ex: username@xyz.com.

Upon executing that command a web browser window will be opened where you will be prompted to log in and provide multi factor authentication information to access your Microsoft account. 

Upon successful login, you should see this screen

For more complex authentication setups you may need to see the below Microsoft documentation for specific details here.

Implement Access Restrictions

Having logged in and configured our Exchange settings, we will now implement access controls so that Prokeep can only access approved mailboxes.

Create a new Application Access Policy

Permissions

Prior to performing the following steps, ensure that you have been assigned an admin role in your organization, and that you specifically have the "Organization Configuration" role assigned. This role is granted to any Exchange Administrator or Global Administrator user. If your Microsoft Account lacks this permission and you attempt to execute the following Powershell commands, you will see this error:

 

If you lack the correct permissions, please contact your Exchange Administrator, who can grant you these permissions via admin.microsoft.com > Users > Active Users.

 

Once you have ensured you have the correct permissions or have handed off these steps to someone who does, proceed with the following.

Adding Shared Mailboxes

A shared mailbox cannot be directly added via the above method as they are not security principals. An error message will specify this when attempting to add the application access policy.

 

To solve this, a mail enabled security group will need to be used or created, and the shared mailbox will need to be added to the security group. The application access policy may then be granted to that security group. Steps to create a security group are covered in the following section.

Adding Security Groups

A security group can be added to allow for multiple allowances via a single application access policy. This is the only method to add shared email inboxes, and is a more efficient method for adding individual inboxes.

 

See Microsoft's documentation for limiting application access here

 

Create a Security Group

See Microsoft's documentation for managing mail enabled security groups here

 

As an admin user, go to your Exchange Admin Center. Under Recipients, click Groups then Add a group.

 

Then choose Group Type > Mail Enabled Security

Then provide a name and description for this security group.

 

Then assign group owners. Use your own judgment here but typically provide the names of two IT admin users at your business.

 

Then add members to this security group. These are the email addresses you intend to approve for usage in Prokeep. These addresses can be distribution lists, shared emails, or individual emails.

 

Finally, create an email address name for the group. This is the name you will use when executing PowerShell commands to approve access to this group. 

From this screen you may also decide whether or not to allow outside emails to come into this group, and whether or not you wish for new group additions to require approval. For this example I have chosen to allow outside emails and not require approval. Follow your organization’s preferred security protocols if they differ from those depicted in this example.

 

Following this, review your settings to ensure you have configured this group correctly and then click Create Group.

 

Approve Security Group for Prokeep Usage

Once the security group has been created, add the group using the same Powershell command as above, but stating the security group name in place of the email address.

Upon successfully executing the above, you should see the following:

Verifying Policy Approval

Caching Delays Following Policy Changes

Note that changes to application access policies can take some time to take effect (in particular, changes to access or newly created ones, after the first has already been made). As such, after adding a new security group or adding a new mailbox to an existing security group, please allow up to 24 hours for Microsoft to make these changes. During this waiting period, Prokeep inboxes will not yet be configurable. 

Testing your Application Access Policies

After creating an access policy we can test the validity of our policies by executing the following in Powershell:

Verifying that access to a mailbox has been granted

Execute the following, providing the name of the inbox that you wish to verify has been added. 

If successful, you will see an output similar to the following. If “AccessCheckResult” states “Granted” then this inbox has successfully been granted access.

Verifying that access to other mailboxes has been restricted

Execute the following, providing the name of the inbox that you wish to verify has been added. 

You will see an output similar to the following. If “AccessCheckResult” states “Denied” then this inbox has not been granted access.

Disconnect

Once you have submitted to grant access to all the specific users and security groups you need you should disconnect from your session.

 

Disconnect the session from exchange online

 

All done - Prokeep will now only be able to access the mailboxes given by the Application Access Policies created.

 

Removing Access Policies

In the case of incorrect access policies being created, or if you decide you no longer want Prokeep to have access to a given email address, you will need to follow these steps to remove an access policy.

Listing and Removing Application Access Policies

In the case of incorrect access policies being created, you may need to remove an access policy.

Execute the following to receive a list of the current access policies:

This will return a list of all access policies created. Each will have an Identity consisting of a very long identifier that will need to be referenced if attempting to remove a policy.

To remove an unwanted policy, find the Identity for the policy from that list  and run the following:

This command will delete the application access policy. Note the quotation marks - they are necessary for running the operation. Such changes may take some time to take effect, but can be re-tested using the instructions seen above here regarding testing application access. Note that if all access policies for the Prokeep Graph API Application are removed without also removing the consent granted to the application, the application will have access to mailboxes again.