It is a common practice for big players in the cloud market to allow their users to have more than one method to access their data. With Google, for example, you can have one single account and easy access to a bunch of free services like Gmail and Drive.<\/p>\n\n\n\n
Google also provides public APIs for developers to be able to access data via other applications. The whole process happens through the usual OAuth +, an application provided by the player.<\/p>\n\n\n\n
With Microsoft, there\u2019s Microsoft Graph<\/a>. It provides some REST endpoints that allow access to their services like Office 365 (which is in the cloud, unlike the older versions), Azure and Outlook.<\/p>\n\n\n\n Here\u2019s a single example for you to get a taste. A common URL endpoint to retrieve personal information about a specific account is https:\/\/graph.microsoft.com\/v1.0\/me<\/a>. Here\u2019s what you\u2019ll get if you try it out in a browser tab:<\/p>\n\n\n\n That\u2019s when OAuth takes place. The URL, in turn, follows some pattern rules that you\u2019ll see right away.<\/p>\n\n\n\n The access to each resource must follow a pattern. Here\u2019s the request construction:<\/p>\n\n\n\n First, as usual, you define the HTTP method for the operation. Note that it\u2019s not up to you to decide that; you must go to the docs and check which method is available for that operation. Plus, the endpoints follow the RESTful principles<\/a>, so make sure to refer to it for better comprehension.<\/p>\n\n\n\n Then it comes the version of the Graph API you\u2019re targeting. As per the writing of this article, the only available versions are v1.0<\/em> and beta<\/em>. As you may have noticed, for production purposes, only the v1.0<\/em> version should be used. The beta<\/em> version brings some new stuff, which might include breaking changes, so be careful when using it.<\/p>\n\n\n\n The resource<\/em> defines the entity (and its properties) you\u2019re willing to access. These resources usually come alone like in the previous example (\/me<\/em>), so they\u2019re called top-level entity resources. However, you may want additional inheriting data, like \/me\/messages<\/em>, for example. You can refer to the list of available resources here<\/a>.<\/p>\n\n\n\n Remember that each resource is secure information, so it requires permission<\/a> to be accessed. You\u2019ll see more about how to do it soon.<\/p>\n\n\n\n Finally, you have the parameters. Like the other REST API endpoints, it\u2019s necessary to provide the filters for the endpoints that demand that, like when retrieving all of your email messages filtered by the sender, for example.<\/p>\n\n\n\n Microsoft Graph API makes use of the OData<\/a> (Open Data Protocol) namespace, which defines a set of best practices for building and consuming RESTful APIs. You can read more detailed information about the whole API architecture here<\/a>.<\/p>\n\n\n\n Microsoft Graph also provides a great tool to easily explore the endpoints, and it\u2019s the Graph Explorer<\/a>. Open it, check out at the top of the screen if you\u2019re already logged in, otherwise log in to your Microsoft account. Figure 1 shows how it looks.<\/p>\n\n\n\n <\/p>\n\n\n\n Figure 1. Microsoft Graph Explorer view.<\/strong><\/p>\n\n\n\n In the top bar of this screen, you’ll see a few combo boxes and a text field to customize your search. Number 1 shows the option to select which HTTP method you want this search to be run. Number 2 states the API version (v1.0<\/em> or beta<\/em>).<\/p>\n\n\n\n Number 3 represents the full URL of the necessary resource. In this example, the \/me<\/em> was filled by the first option available at Sample queries<\/em> tab (number 6). It helps you to figure out the available options, pre-filling the required values and making the Explorer ready to run the request. The History<\/em> tab lists the searches executed until now.<\/p>\n\n\n\n Number 5 brings four other options:<\/p>\n\n\n Number 7, finally, deals with the tabs of the API responses. Here you\u2019ll have the response body preview (once it\u2019s completed) and the response headers.<\/p>\n\n\n\n The Adaptive cards<\/em> functionality is just a nice feature in which Microsoft tries to adapt the returned information into cards, like a business card.<\/p>\n\n\n\n The Code snippets<\/em> tab is very interesting. It auto-generates the code for the current request in four different languages: CSharp (Figure 2), JavaScript, Java and Objective-C:<\/p>\n\n\n\n <\/p>\n\n\n\n Figure 2. Code snippets for 4 languages.<\/strong><\/p>\n\n\n\n Besides all that, you still need to sign in to Graph Explorer with your Microsoft account to fetch its data. For this, click the Sign in to Graph Explorer<\/em> button in the left side panel. Then, you\u2019ll be redirected to the access page to permit the Graph Explorer app (Figure 3). Click the Yes<\/em> button.<\/p>\n\n\n\n <\/p>\n\n\n\n Figure 3. Giving access to the Graph Explorer app.<\/strong><\/p>\n\n\n\n Once you\u2019re logged, run the \/me<\/em> request. Listing 1 shows the response content that\u2019ll be shown in the Response preview<\/em> tab.<\/p>\n\n\n\n Listing 1. Response content for \/me<\/em> request.<\/strong><\/p>\n\n\n\n Sometimes, depending on the operation you\u2019re performing, you\u2019ll be prompted to consent to the specific permissions, in the Modify permissions<\/em> tab.<\/p>\n\n\n\n Run another sample query. Go to the Sample queries<\/em> tab and search for my mails from an address<\/em>, then click the GET option shown in Figure 4:<\/p>\n\n\n\n <\/p>\n\n\n\n Figure 4. Searching for a sample query.<\/strong><\/p>\n\n\n\n When you try to run this query, you\u2019ll get the following error message: Forbidden – 403 – 260ms. You need to consent to the permissions on the <\/em>Modify permissions<\/em><\/strong> tab.<\/em><\/p>\n\n\n\n Opening the referred tab, you\u2019ll see the Consent<\/em> buttons in the Status<\/em> column, like in Figure 5. If you\u2019re in a small screen, pay attention that the buttons are \u201chidden\u201d, so you have to scroll to see them horizontally.<\/p>\n\n\n\n <\/p>\n\n\n\n Figure 5. Consenting to the permissions.<\/strong><\/p>\n\n\n\n If the operation goes on successfully, you\u2019ll see the status changing to Consented<\/em>. Now, run the query. Don\u2019t forget to change the email parameter to one of yours at the query text field.<\/p>\n\n\n\n The result should be similar to Figure 6.<\/p>\n\n\n\n <\/p>\n\n\n\n Figure 6. Querying email messages by sender email.<\/strong><\/p>\n\n\n\n Now to move to an example that creates data in the server, using the API to send an email. For this, go again to the Sample querie<\/em>s tab and search for send an email<\/em>, then click the button. You\u2019ll notice that Graph Explorer fills in the Request body<\/em> area with a pre-generated JSON. It is pretty much what\u2019s necessary to send a basic email. Obviously, you may change its contents to your preferences. Listing 2 shows what the JSON looks.<\/p>\n\n\n\n Listing 2. JSON example to send an email.<\/strong><\/p>\n\n\n\n Before submitting the query, remember that you have to authorize Graph Explorer with the right permissions. Go to the Modify permissions<\/em> tab again and allow the required accesses.<\/p>\n\n\n\n Run it. If everything went right, you\u2019ll see the successful message with an HTTP 201 – Accepted<\/em> code. It means that the request was OK, and something was created in the server. In this case, the sent email.<\/p>\n\n\n\n Go to your email inbox and check that the email was sent (Figure 7).<\/p>\n\n\n\n <\/p>\n\n\n\n Figure 7. Email sent successfully.<\/strong><\/p>\n\n\n\n Here\u2019s another example. This time, you\u2019ll integrate a simple .NET Core application with Microsoft Graph to retrieve user\u2019s data and send an email as well.<\/p>\n\n\n\n First, create a new app by running the following command:<\/p>\n\n\n\n This command creates a Console app. Then, add the required NuGet dependencies:<\/p>\n\n\n\n To enable the use of Graph API within .NET applications, you\u2019ll need to set up an Azure AD application. For this, go to the Azure Admin Center<\/a> and log in to your Microsoft account.<\/p>\n\n\n\n In the home page, click the All resources > Manage Azure Active Directory<\/em> option and, finally, go to the App registrations<\/em> option. Click the New registration<\/em> button. In the next screen, give the app a name (simple-talk-graph-app<\/em>, for example) and fill the options like shown in Figure 8.<\/p>\n\n\n\n <\/p>\n\n\n\n Figure 8. Registering a new application.<\/strong><\/p>\n\n\n\n The next screen you will see shows the app details, including the Application id<\/em>, which is going to be used soon in the C# code. It\u2019s also necessary that this app is treated as a public client, so you need to toggle it going to the Authentication > Advanced Settings > Default client type<\/em> option. Toggle it and click Save<\/em>.<\/p>\n\n\n\n Next, you need to initialize the .NET development secret store. Since it\u2019s necessary to generate new OAuth tokens for every new request, the automatic way to do it is by Azure AD<\/a>:<\/p>\n\n\n\n After it\u2019s initialized, you can add the credentials related to the client id and the scopes (permissions):<\/p>\n\n\n\n Remember to replace the Start with the authentication process. Create a new class into the Auth<\/em> folder called DeviceCodeAuthProvider.cs<\/em>. The name already suggests that this is the flow this example uses to authenticate users. Listing 3 shows the code.<\/p>\n\n\n\n Listing 3. DeviceCodeAuthProvider code.<\/strong><\/p>\n\n\n\n The code is designed under the MSAL<\/a> patterns. It injects the scopes and credentials you\u2019ve previously set in the command line. There are two main methods: one to generate new access tokens and another one to authenticate each of the requests, feeding them with the proper bearer tokens.<\/p>\n\n\n\n Listing 4 shows the code to be placed in the GraphHelper.cs<\/em> file (please, create it under the Graph<\/em> folder).<\/p>\n\n\n\n Listing 4. GraphHelper code.<\/strong><\/p>\n\n\n\n The code of these methods was extracted from the auto-generated ones shown in the Graph Explorer before. Once you have the auth provider, you can instantiate the graph client and call the respective Graph operation.<\/p>\n\n\n\n Finally, move on to the code of Program.cs<\/em> file, which calls these methods. Listing 5 shows the content.<\/p>\n\n\n\n Listing 5. Program class code.<\/strong><\/p>\n\n\n\n First, you need to load the app settings where the credentials and scopes were placed. After extracting the app id and scopes array, you may retrieve a valid access token (which is going to be printed to make sure it works), initialize the graph helper (that will, in turn, create the graph client from the auth provider) and, finally, call the \/me<\/em> and \/sendMail<\/em> operations.<\/p>\n\n\n\n When you run the app, a new console window opens and asks you to access the https:\/\/microsoft.com\/devicelogin<\/a> URL and enter a printed code to authenticate. Copy the code, access the URL and paste it. Click Next<\/em>, then authenticate to your Microsoft account.<\/p>\n\n\n\n The final screen shows what type of information the app is trying to access and ask for your permission (Figure 9):<\/p>\n\n\n\n <\/p>\n\n\n\n Figure 9. Giving access to the Graph app.<\/strong><\/p>\n\n\n\n Click Yes<\/em> and close the window. When you get back to the console, the username is printed, and the email was sent as shown in Figure 10.<\/p>\n\n\n\n <\/p>\n\n\n\n{\n \"error\": {\n \"code\": \"InvalidAuthenticationToken\",\n \"message\": \"Access token is empty.\",\n \"innerError\": {\n \"request-id\": \"a2115c87-341f-405a-b127-d3432748d38b\",\n \"date\": \"2020-06-08T13:46:07\"\n }\n }\n}<\/pre>\n\n\n\nMicrosoft Graph API Structure<\/h2>\n\n\n\n
{HTTP method} https:\/\/graph.microsoft.com\/{version}\/{resource}?{query-parameters}<\/pre>\n\n\n\nSeeing it in Action<\/h2>\n\n\n\n
![\"\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2020\/07\/word-image-37.png\")
<\/figure>\n\n\n\n\n
![\"\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2020\/07\/word-image-38.png\")
<\/figure>\n\n\n\n![\"\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2020\/07\/word-image-39.png\")
<\/figure>\n\n\n\n{\n \"@odata.context\": \"https:\/\/graph.microsoft.com\/v1.0\/$metadata#users\/$entity\",\n \"displayName\": \"Julio Sampaio\",\n \"surname\": \"Sampaio\",\n \"givenName\": \"Julio\",\n \"id\": \"4e108eb8cbcb0495\",\n \"userPrincipalName\": \"-----@outlook.com\",\n \"businessPhones\": [],\n \"jobTitle\": null,\n \"mail\": null,\n \"mobilePhone\": null,\n \"officeLocation\": null,\n \"preferredLanguage\": null\n}<\/pre>\n\n\n\n![\"\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2020\/07\/word-image-40.png\")
<\/figure>\n\n\n\n![\"\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2020\/07\/word-image-41.png\")
<\/figure>\n\n\n\n![\"\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2020\/07\/word-image-42.png\")
<\/figure>\n\n\n\n{\n \"message\": {\n \"subject\": \"Meet for lunch?\",\n \"body\": {\n \"contentType\": \"Text\",\n \"content\": \"The new cafeteria is open.\"\n },\n \"toRecipients\": [\n {\n \"emailAddress\": {\n \"address\": \"YOUR_EMAIL@outlook.com\"\n }\n }\n ]\n }\n}<\/pre>\n\n\n\n![\"\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2020\/07\/word-image-43.png\")
<\/figure>\n\n\n\nIntegrating .NET Core with Microsoft Graph<\/h2>\n\n\n\n
dotnet new console -o simpletalk-graph-api<\/pre>\n\n\n\n
dotnet add package Microsoft.Extensions.Configuration.UserSecrets\ndotnet add package Microsoft.Identity.Client\ndotnet add package Microsoft.Graph<\/pre>\n\n\n\n
![\"\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2020\/07\/word-image-44.png\")
<\/figure>\n\n\n\ndotnet user-secrets init<\/pre>\n\n\n\n
dotnet user-secrets set appId \"3f2458ff-43d2-45f8-a0f0-b2f403461ef4\"\ndotnet user-secrets set scopes \"User.Read;Mail.Send\"<\/pre>\n\n\n\n
appId<\/code> with yours. Now, open the created project into Visual Studio and create two new folders: Auth <\/em>(to deal with the auth flow) and Graph <\/em>(to store the graph helpers).<\/p>\n\n\n\nusing Microsoft.Graph;\nusing Microsoft.Identity.Client;\nusing System;\nusing System.Net.Http;\nusing System.Net.Http.Headers;\nusing System.Threading.Tasks;\nnamespace simpletalk_graph_api.Auth\n{\n public class DeviceCodeAuthProvider : IAuthenticationProvider\n {\n private IPublicClientApplication _msalClient;\n private string[] _scopes;\n private IAccount _userAccount;\n public DeviceCodeAuthProvider(string appId, string[] scopes)\n {\n _scopes = scopes;\n _msalClient = PublicClientApplicationBuilder\n .Create(appId)\n .WithAuthority(AadAuthorityAudience.AzureAdAndPersonalMicrosoftAccount, true)\n .Build();\n }\n public async Task<string> GetAccessToken()\n {\n if (_userAccount == null)\n {\n try\n {\n var result = await _msalClient.AcquireTokenWithDeviceCode(_scopes, callback => {\n Console.WriteLine(callback.Message);\n return Task.FromResult(0);\n }).ExecuteAsync();\n _userAccount = result.Account;\n return result.AccessToken;\n }\n catch (Exception exception)\n {\n Console.WriteLine($\"Error getting access token: {exception.Message}\");\n return null;\n }\n }\n else\n {\n var result = await _msalClient\n .AcquireTokenSilent(_scopes, _userAccount)\n .ExecuteAsync();\n return result.AccessToken;\n }\n }\n public async Task AuthenticateRequestAsync(HttpRequestMessage requestMessage)\n {\n requestMessage.Headers.Authorization =\n new AuthenticationHeaderValue(\"bearer\", await GetAccessToken());\n }\n }\n}<\/pre>\n\n\n\nusing Microsoft.Graph;\nusing System;\nusing System.Collections.Generic;\nusing System.Threading.Tasks;\nnamespace simpletalk_graph_api.Graph\n{\n public class GraphHelper\n {\n private static GraphServiceClient graphClient;\n public static void Initialize(IAuthenticationProvider authProvider)\n {\n graphClient = new GraphServiceClient(authProvider);\n }\n public static async Task<User> GetMeAsync()\n {\n try\n {\n \/\/ GET \/me\n return await graphClient.Me.Request().GetAsync();\n }\n catch (ServiceException ex)\n {\n Console.WriteLine($\"Error getting signed-in user: {ex.Message}\");\n return null;\n }\n }\n public static async void SendMailAsync()\n {\n try\n {\n var message = new Message\n {\n Subject = \"Testing from .NET SDK\",\n Body = new ItemBody\n {\n ContentType = BodyType.Text,\n Content = \"The SDK is working fine!\"\n },\n ToRecipients = new List<Recipient>()\n {\n new Recipient\n {\n EmailAddress = new EmailAddress\n {\n Address = \"YOUR_EMAIL@outlook.com\"\n }\n }\n }\n };\n await graphClient.Me\n .SendMail(message, null)\n .Request()\n .PostAsync();\n }\n catch (ServiceException ex)\n {\n Console.WriteLine($\"Error getting signed-in user: {ex.Message}\");\n }\n }\n }\n}<\/pre>\n\n\n\nusing Microsoft.Extensions.Configuration;\nusing simpletalk_graph_api.Auth;\nusing simpletalk_graph_api.Graph;\nusing System;\nnamespace simpletalk_graph_api\n{\n class Program\n {\n static async System.Threading.Tasks.Task Main(string[] args)\n {\n var appConfig = LoadAppSettings();\n var appId = appConfig[\"appId\"];\n var scopesString = appConfig[\"scopes\"];\n var scopes = scopesString.Split(';');\n var authProvider = new DeviceCodeAuthProvider(appId, scopes);\n var accessToken = await authProvider.GetAccessToken();\n Console.WriteLine($\"Access token: {accessToken}\\n\");\n GraphHelper.Initialize(authProvider);\n var user = await GraphHelper.GetMeAsync();\n Console.WriteLine($\"Welcome {user.DisplayName}!\\n\");\n GraphHelper.SendMailAsync();\n Console.WriteLine(\"Email sent!\");\n }\n static IConfigurationRoot LoadAppSettings()\n {\n var appConfig = new ConfigurationBuilder()\n .AddUserSecrets<Program>()\n .Build();\n if (string.IsNullOrEmpty(appConfig[\"appId\"]) ||\n string.IsNullOrEmpty(appConfig[\"scopes\"]))\n {\n return null;\n }\n return appConfig;\n }\n }\n}<\/pre>\n\n\n\n![\"\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2020\/07\/word-image-45.png\")
<\/figure>\n\n\n\n![\"\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2020\/07\/word-image-46.png\")
<\/figure>\n\n\n\n