Online Meetings with Microsoft Graph API
Azure offers services which covers a diverse spectrum of requirements and operations. From virtual machines as IaaS to Outlook as SaaS, its offerings cover a wide range of services. In this article we will focus primarily on a resource known as Online Meetings which is a service under the Cloud Communications group of services and we will access this resource using Microsoft Graph API. This resource is similar to a calendar event but when created does not block the calendar of its participants, that is, it does not show up on the calendar. Joining an online meeting will use Microsoft Teams interface (web or standalone application) for the communication.
This article will not be a comprehensive discussion or tutorial for accessing online meetings resource. The Microsoft Graph API Documentation contains all the necessary information required. The primary focus of this article is to elaborate the points and information not covered by the documentation, but I discovered them through my personal experience developing a web application for accessing this resource.
Prerequisites
Before we proceed, there are a few concepts and terms that you as a reader will be required to know or at least be aware of. And since this discussion is about Azure services, a Microsoft subscription and account is required, preferably an enterprise account as this will emphasize the usefulness of the service.
Here are the steps, discussed at a high level with the details contained in the links mentioned with the article.
- Registered Application: An application registered with Azure, in this article we will specifically deal with a web application type. There are other types of applications available as well. After registration, you’ll have to create a client secret or associate a certificate with the application. With all this done, you’ll have the client ID and the client secret which will be used later on to acquire an access token.
- Permissions: The application will require permissions to be enabled to access online meetings. There are two types of permissions available: delegated permission and application permission. The difference between the two is that with delegated permission the application is permitted to access the resource on-behalf of a user while application permission accesses the resource with the identity of the application itself and not on-behalf of any other entity. Ideally with web application type, authorization code flow is the commonly used protocol for delegated access and client credentials flow is the protocol more popular with application access. There are other types of applications and other types of authentication protocols more favorable with these types. Note that these authentication methods will use the Active Directory to authenticate the credentials.
From these steps I suggest that you get yourself acquainted with Microsoft Graph API, OAuth 2.0 and REST API access for the language or framework you are working on.
To perform any read or write on a resource, you need to acquire an access token. This access token can be obtained from the endpoint: login.microsoftonline.com/{tenant}/oauth2/v2.0/token, where tenant is the tenant ID. The tenant is generally managed by an administrator and any application that is registered has to be associated with a tenant. With application permission, the token can directly be acquired using the application credentials but for delegated permission the authorization code (auth code in short) has to be acquired through user login, generally from a web browser.
Once an access token is acquired, you can use the Microsoft Graph API endpoint for online meetings: https://graph.microsoft.com/v1.0/me/onlineMeetings for delegated access or https://graph.microsoft.com/v1.0/users/{userId}/onlineMeetings for application access, where userId is the UPN (user principal name) or ID (object ID) of the user in Active Directory. To create an online meetings resource you can follow this page and to get an online meetings resource you can follow this page. In fact, pages under this section contain all the information you will require for accessing the resource.
Why this discussion then?
Now you may ask yourself, if all this information is available and provided by Microsoft in its Graph API documentation, why am I writing this article? The answer is simple, I encountered certain obstacles and lack of information even after going through the documentation which I overcame through trial and error.
One of the problem(s) you will encounter with MS Graph API is that the error messages are not very specific and hence do not point out where exactly is the problem. And there is no better way to elaborate it than to use the example provided in the create online meetings tutorial page. The sample body mentioned there does not contain all the required fields and on calling the endpoint using this body you might receive a response with an HTTP code 500 for Internal Server error and a message saying that that request body cannot be null. From this you can see that the error message is unfortunately generic and does not tell you where the problem is.
You can find an exhaustive list of properties for online meetings resource in the documentation, the required ones being meeting participants, the start and end date, the subject and allowedPresenters property. Since I discovered all this from trial and error, it may be the case that other non-read-only properties are also required, but the ones that I mentioned here are absolutely required. From the meeting participants, the organizer is required and the attendees are optional. The attendees collection and organizer are of meetingParticipantInfo type with the identity and upn properties being required. I do not know what role is assigned to a participant if the role property is avoided but I am guessing its presenter. The identity property is of the type identitySet and in this type there are three optional fields (as mentioned in the documentation) each of type identity, but there is nothing optional about it. You have to specify the id property of the user, application or device identity. Generally, the property used is user so the id can be the upn of the user. However, the id for application/device is the object id within the Azure ecosystem. The displayName is optional. So in short, if you get an error which says that the request body is null, it means that one or more fields are missing or the format is not appropriate.
Yes, if you give a format which Azure cannot parse or recognize, then its going to throw a 500 Internal Error code in the response entity with the same exceptionally helpful generic message that the request body is null. I sometimes wonder if the developers just copy pasted the same error message for all the cases. I found this out when I supplied an incorrect date format for start date. The proper date format is the one given in the sample body in the create meeting tutorial page. So watch out for those properties which can have multiple valid formats and try them all if you get an error.
One last but most important point I want to mention here, which happens to be the issue I discovered the hard way, is the UPN or User Principal Name. Lets say you are working at Contoso and all the employees have their mail IDs as <employee_name>@contoso.com and this organization uses Azure Active Directory to digitally manage its employees and other users. If you call the endpoint https://graph.microsoft.com/v1.0/me using token acquired for delegated access, you will notice that your UPN is <employee_name>@ad.contoso.com which is the case in the organization I work in. But on using this UPN in the body of the online meeting create request, an error gets thrown (obviously with some generic message which does not tell you the source of the problem). But isn’t that the UPN? so if that is not the value for the UPN then what is? Turns out that on using <employee_name>@contoso.com as the UPN works and using the other one which is specified as the UPN by calling the /me endpoint doesn’t.
Moral of the story
With all this said, the moral of the story is that you might discover a lot of things missing in the documentation, and I suppose this is not the case specifically for online meetings resource but for other services and resources as well. There are three things I suggest you keep in mind when you encounter an error message which is not descriptive of the problem:
- Keep in mind of the properties that may be missing. Ideally, use all mentioned properties just to be on the safe side.
- Make sure that you try out all possible widely used formats for fields such as dates.
- Identifiers! make sure that the UPN or other identifiers are correctly mentioned or in case if there are multiple ways of identifying an entity, I suggest you use trial and error.