Recently I have been working on projects where I have been asked to automate actions within Office365. An example of this is to create a new user.
The Microsoft Graphi API was released in 2015 and supports consumption from any automation or orchestration product that allows for integration utilising the REST framework
Thankfully, Microsoft have the great Microsoft.Graph API that helps with this. Did you know that the Graph API has been around since 2015?
The Graphi API is REST based and uses OAuth for authentication which makes it easily consumable from just about anything. In this post and the ones following I will be demonstrating how to automate some Office365 functionality using VMware vRO. You will find that the concepts and approach that I have taken can be adopted across other platforms such as Microsoft Orchestrator (Scorch) with little amendments. Before we get to the fun bits we need to jump through a couple of hoops to make all this work though.
Prerequisites
Application Registration
The first thing we need to do is register an entry for our application, although in our case the application is any and all workflows that we will development. There is a guide that you can follow here that outlines the steps that you need to take. Something that really caught me out with this. When asked to provide an entry for the redirect URL, do not use ‘localhost.’ You need to provide a real URL that will resolve from the vRO server. For instance, I used https://automationpro.co.uk. It is irrelevant for our workflows and will not be used, however, if you use a non-resolveable url, you will not be able to grant admin access later on and that will stop your workflows from running. For simplicity, I have registered my application and followed get access on behalf of a user for my calls to the API. You will need to setup a new user in Office365. For the sake of this blog, my user is called svc_postman.
Reader Activity1. Register a new application in Azure Active DirectoryNote: Ensure you generate and record an Application Secret
Permissions
Depending on what types of requests you want to make with the Graph API you may have to alter away from the default permissions that you set during the Application Registration step. You can revisit and amend permissions at any time. For the sake of learning and developing I would suggest enabling all permissions. Then when you have developed your workflows, pull the permissions back and only leave the explicit ones you require enabled.
Reader Activity 1. Review default application permissions from within the application registration portalNote: You can update and review the permissions at any time
Microsoft.Graph API Explorer
Microsofts Graph API Explorer allows you to try common API requests in a sandbox environment
I would highly recommend having a play with the Graph Explorer that Microsoft provide. I wish all vendors would provide something like these for their APIs! You will be able to test out some of the API calls and
look through the responses. You can do this in the provided sandbox environment or login using an account you have with Office365 and try some calls out for real. When you first visit the page you may thing there aren’t many samples to view. In the left pane, click the ‘show more samples’ link. You will be able to select different API areas to focus on. Samples for each selected section will appear under the ‘Getting Started’ samples section.
Reader Activity 1. Use the Graph Explorer to explore the Graph API2. Explore the provided samples on the API explorerNote: Do not underestimate the usefulness of the Explorer. It should be your first port of call when working with the API
Microsoft.Graph API
It may be boring but I would recommend browsing through the API reference guide. I would recommend having a look through the common use cases section to start becoming familiar with the concepts of the API. If you are familiar and used to working with REST based APIs then you may want to skip this activity.
Reader Activity 1. Review the API Reference Guide online2. Review the common use cases and section on obtaining tokensNote: The more familiar you become with the reference guide the easier you will find adopting and using the Graph API
Preparing VMware vRO
Configuration Elements
To make life easier I stored the required information for authentication in a configuration element in vRO. This way I can always amend the details in one location, without having to go through multiple workflows making changes. If you want to follow along then configure the configuration elements as shown in the screenshot below. As you can see there are 5 values that you will need to enter.
Use configuration elements to ease maintainability of common attributes across multiple workflows
TenantId
The Tenant ID is unique to your Office365 prescence.
Reader Activity – Obtain Tenant ID
1. Log in to Microsoft Azure using an account that has administrator permissions.
2. Click Azure Active Directory in the portal.
3. Under the Manage section, click on Properties to view the tenant ID (the tenant ID is shown as the Directory ID).
ClientId
The Client ID is unique to your registered application.
Reader Activity – Obtain Client ID
1. Log in to Microsoft Azure using an account that has administrator permissions.
2. Click Azure Active Directory in the portal.
3. Under the Manage section, click on App Registrations.
4. Ensure All Apps is selected in the second of the two dropdowns in the right hand pane.
5. Click the entry for your application registration. The Client Id is shown under the Application ID entry.
ClientSecret
The Client Secret is unique to your registered application. It is a password of sorts, used with the ClientId when contacting the service.
Reader Activity – Obtain ClientSecret
1. This is the Application Secret that you recorded when you registered the application in Azure Active Directory.
Username
The Username is the name of an Office365 user to use when making calls to the Graph API.
Reader Activity – Obtain Username
1. This is the name of the Office 365 account you used during application registration.
Password
The Client Secret is unique to your registered application. It is a password of sorts, used with the ClientId when contacting the service.
Reader Activity – Obtain ClientSecret
1. The password for the specified username.
Next Steps
We have now successfully configured our pre-requisites, learnt about the Graph API by using the Graph Explorer and reviewing the API Reference materials. In Part Two, I will run through how to create some actions to obtain our configuration item data as well as authenticating to the Microsoft Graph API and obtaining an access token.
