App registration with Azure

We recommend reading the quick start guide provided by Microsoft at https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app.

There are two ways to configure iService access with OpenID Connect in Azure (the process is a bit different for each)

1. Allowing Microsoft logins only from users in your Azure directory, or

2. Allowing any Microsoft login, including from your directory. 

This guide explains option 1 above. You will need to make the following three settings.

✓Accounts in this organization directory only

✓Redirect URI platform set to ‘Single-page Application (SPA)’

✓Redirect URl set to your tenant’s FQDN in the format of: https://<tenanturl>/app

These settings are shown in the image below.

After you create it, you’ll be presented with the following properties. You’ll need to note the Application (client) ID and Directory (tenant) ID, since you’ll need to plug these into your iService tenant settings in the OpenID page.

Use the Client ID and Tenant ID from the page shown above to complete the OpenID setup described at the top of this chapter.

Create your application

After you log into Azure, navigate to Applications and click New Application.

Enter a name that others will recognize, like iService. Set the scope of the application so it limits access to account in this organizational directory. You do not need to enter a value for the Redirect URI.

When you save your app, navigate to API Permissions.

Click Add a permission and then select Application Permissions.

Your application should only have the two permissions shown below (Mail.ReadWrite and Mail.Send).

After you add the permissions, you must Grant Admin Consent for the permissions. Click on Grant admin consent to open the dialog box and the select Yes.

After you grant admin consent, the status will turn green.

To obtain your secret key for the application, click on Certificates and Secrets and then Client Secrets. Then click on New Client Secret to create the secret.

Enter a short description for the secret and then select the expiration period. Be sure to note the date the secret expires and create a new one before the expiration date.

After you configure the secret key and set the expiration, the key will be displayed.

To get the other two values, load the Overview page.

After you create your application, you should setup the proper restrictions to limit the access of the credentials you create to only the associated mailboxes. This is a separate step from creating the application in the process described above.

The steps are roughly as shown below.

1.Create a new app registration in the Azure directory for iService to use. In the app registration settings:

oIn the app registration API permissions page, assign this app the proper permissions- I think Mail.Read and Mail.Send would be all that's needed, but this will ultimately depend on how we implement it I guess. Then grant admin consent for these permissions.

oIn the certificates and secrets page, generate the secret key for to later plug in to the iService app

2.Define a "Mail-Enabled Security Group" in the directory and add then add the mailboxes they want us to have access to, to that group. For the example below, this group is called iservice@mydomain.com

3.Create an application access control policy that restricts the app created in step 1 to only have access to the mailboxes in the mail-enabled security group created in step 2:

New-ApplicationAccessPolicy -AppId <your-app-id> -PolicyScopeGroupId iservice@mydomain.com -AccessRight RestrictAccess -Description "Restrict iService app to mailboxes in the iService security group."

4.Create the mailbox in iService tied to the Azure app created in step 1, including the app id, secret key, etc. Ideally we'll have this part abstracted out in the iService admin panel by then though so that you can just define it once there, then reference in a dropdown when creating each iService mailbox.

The Microsoft documentation for this step can be found at https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access.