In this guide we'll walk through a generic app authorization as a Global Administrator and give background on how Enterprise Apps work with Azure AD, including common misconceptions for security. Once that's done, we'll get a service account authorized and connected to Robin successfully, while explaining the process in more technical depth than our traditional guide.
If you’re grappling with “How do we allow people to sign into Robin with Office 365 without allowing everyone to authenticate with any app on the internet?”, this explainer is for you.
Service Principal and Application Objects
When you authorize the Robin app for the first time, it registers a new Service Principal object in your Azure directory. This is your “install” of the Robin application, which you can manage directly. Robin maintains the Application object itself, which allows us to develop and maintain the application for all of our customers in one place.
You can think of the Service Principal like installing a version of software, and the Application as the latest version available. If the Application changes (e.g. Adds/Removes a permission for features) you can choose to reauthorize the latest version to update the service principal as needed. This is an exceedingly rare event, and not necessary for running Robin.
A diagram of this workflow from Microsoft:
Adding new applications in Office 365
Microsoft outlines this requirement for Global Administrators and applications within Azure AD.
Only global administrators can:
- Add apps from the Azure AD app gallery (pre-integrated 3rd Party Apps)
- Publish an app using the Azure AD Application Proxy
When you first try to sign into Robin’s application, you’ll need to be a Global administrator unless your tenant allows all users to register new applications (we don't recommend this).
During sign up/in users are asked to give permission to the app to access their profile and other permissions. The first person to give consent causes a service principal representing the app to be added to the directory.
Once you’ve added the application to your directory, the Global Administrator role is no longer necessary to manage the settings.
Enabling “Users may give applications permission to access their data” will allow regular users assigned to the app to sign into existing service principals. It does not grant users the right to create new service principals (i.e. other applications you haven’t approved). Adding new applications is managed by the “Users may add integrated applications” option instead, which can remain disabled.
Put another way, the first option does not give your users freedom to authorize any application they choose (only pre-approved ones) — the second option does.
This guide assumes you want to authorize Robin's Enterprise app in Office 365 as a Global Adminstrator that will not also act as the service account. This process will allow users to" Sign in with Office 365" without any ongoing connection to a Global Administrator.
- From Robin’s web dashboard, go to Manage > Integrations > Office 365. Select Connect and Service Account as a method. On the pop up window, sign in as a Global Administrator to add Robin as a service principal in your Office 365 tenant. This will allow you to manage user and group assignments directly inside Azure’s admin portal. Refer to the background in the previous section for more on why the Global Administrator is required for this step.
- Remove the account from Robin, since we only needed it to approve the application initially. This will invalidate the tokens generated for your Global Administrator account, but leave the Service Principal within Azure AD. At this point, Robin has no access to your tenant but you can now apply the correct settings within Azure.
- Optional: In Office 365’s Azure Admin Portal under “Enterprise Apps”, find Robin and enabled “Require user assignment” to require explicit assignment before logging into Robin.
- Enable “Users may give applications permission to access their data” in Office 365, which allows users w/ required permission to log into their assigned O365 apps. As mentioned above, this setting only applies to applications the global administrator has explicitly authorized already. It does not grant users the ability to create new applications you haven't already approved.
- Assign the service account to the Enterprise App now listed in the Azure Directory within Office 365. Optional: Assign a group policy instead.
- In Robin’s web dashboard, connect the actual service account via Settings > Integrations using the service account method. Accept the authorization prompt when it appears.
- Make sure service account has impersonation access within Office 365 for the calendars you would like it to manage, then connect the room calendars.
- Calendars are now connected and you’re ready to go. Any employees you assign to Robin in Office 365 will also be able to log in, and those you haven’t explicitly assign will be rejected by Microsoft when attempting to authenticate.
- Who has permission to add applications to my Azure AD instance? Global Admins + App Registration (Microsoft)
- Manage your Azure Enterprise Apps (Azure Portal)