Integrating Microsoft Graph and K2 Assumptions This document assumes you are familiar with Microsoft Graph OAuth OAuth configuration in K2 Swagger, REST, etc Configuring the REST Broker and custom brokers in K2 Testing Microsoft Graph Before beginning the configuration exercise you can test Microsoft Graph against your Office 365 tenant using the online Graph Explorer. https://graph.microsoft.io/en-us/graph-explorer Some key resources that will help in the configuration process include Overview of Microsoft Graph - https://graph.microsoft.io/en-us/docs Microsoft Graph permission scopes - http://graph.microsoft.io/en- us/docs/authorization/permission_scopes Microsoft Graph app authorization - http://graph.microsoft.io/en- us/docs/authorization/app_authorization Register an App In this document we are going to use the new (currently in beta) Application Registration Portal - https://apps.dev.microsoft.com/ Navigate to the Application Registration Portal and login with your tenant admin credentials. Click Add an App Give the app a name
Transcript
Integrating Microsoft Graph and K2
Assumptions This document assumes you are familiar with
Microsoft Graph
OAuth
OAuth configuration in K2
Swagger, REST, etc
Configuring the REST Broker and custom brokers in K2
Testing Microsoft Graph Before beginning the configuration exercise you can test Microsoft Graph against your Office 365 tenant using the online Graph Explorer. https://graph.microsoft.io/en-us/graph-explorer Some key resources that will help in the configuration process include
Overview of Microsoft Graph - https://graph.microsoft.io/en-us/docs
Microsoft Graph permission scopes - http://graph.microsoft.io/en-us/docs/authorization/permission_scopes
Microsoft Graph app authorization - http://graph.microsoft.io/en-us/docs/authorization/app_authorization
Register an App In this document we are going to use the new (currently in beta) Application Registration Portal - https://apps.dev.microsoft.com/ Navigate to the Application Registration Portal and login with your tenant admin credentials. Click Add an App
Take note of the Application Id – you’ll need this for the OAuth configuration on the K2 server.
Click Generate New Password
Taken note of the password and store it somewhere as you’ll need this for the OAuth configuration on the K2 server
Under Platforms click Add Platform
Select Web
Enter the K2 OAuth identity redirect URI.
In this example we will be configuring and running the example directly from a Denallix VM and therefore a local url is sufficient. At this point you can save your changes. You have successfully configured the app.
Configuring OAuth on the K2 Server Go to the K2 server You need to configure a new OAuth Resource. Go to https://k2.denallix.com/Runtime/Runtime/Form/Manage+OAuth+Resources/ or find the Manage OAuth Resources form in K2 Designer.
Under Resource Parameters double click on a parameter to edit it.
client_id: the App ID from your app e.g. a17f3d75-a261-4516-88b3-38d845247d19 [Authorization, Token, Refresh]
client_secret: the password generated when creating the app e.g. yzL5heUz0uXTBbFLeqZydk1 [Authorization, Token]
scope: this defines what permissions the app requires and as a result what functions it can perform. Refer to Microsoft Graph permission scope (http://graph.microsoft.io/en-us/docs/authorization/permission_scopes) for details. In our example we are using read only functions. e.g. Directory.Read.All Group.Read.All Files.Read Sites.Read.All [Authorization]
redirect_uri: the K2 OAuth identity uri e.g. https://k2.denallix.com/identity/token/oauth/2 or https://[yourhost]/ identity/token/oauth/2 [Authorization, Token]
The other parameters do not need configuring. Once the configuration is complete it will look something like this.
Changing scopes If you are playing with adding different capabilities to your Microsoft Graph integration you may want to add or remove permission scopes for the app. You can edit the scopes parameter for the OAuth Resource. In order for this to take effect you need to force a re-authorization. Go to the Manage OAuth Tokens form (https://k2.denallix.com/Runtime/Runtime/Form/Manage+OAuth+Tokens/) and find the line item for your user e.g. Administrator, for the Resource Type, select it and then delete it.
Configuring the Microsoft Graph K2 Swagger Example The Microsoft Graph service is an OData v4 service. K2’s OData support currently only covers OData v1-3. It is still possible to integrate with Microsoft Graph via the REST Broker or via a custom broker. Using the REST Broker for integration will require creating your own Swagger file. An simple example of a Swagger file that defines a handful of Microsoft Graph functions is available here: https://github.com/jonnoking/K2-REST-Descriptor-Files/blob/master/Swagger/Microsoft%20Graph/MicrosoftGraph-Example.json The example Microsoft Graph Swagger file is used to demonstrate what’s possible. It uses a combination of v1.0 and beta services. It is not intended to be a comprehensive definition of the service nor does it fully describe the respective objects. Ensure that you have the latest version of the REST Broker installed. You can download it from here http://help.k2.com/restbeta. Download the Swagger json file and put a copy of it in a directory on the K2 server e.g. c:\K2\Swagger\MicrosoftGraph-Example.json Avoid referring to the URL directly as this file or file location may change over time. Open SmartObject Tester. Register a new Service Instance of the REST Service Type.
Authentication Mode: OAuth
OAuth Resource: select the OAuth Resource you configured in K2 in the previous step. e.g. Denallix Tech UK Graph Explorer
Descriptor Location: Provide the path to your Swagger file e.g. c:\K2\Swagger\MicrosoftGraph-Example.json
Click OK and a browser window will launch prompting you to login to Office 365. Login with your Office 365 credentials.
Having signed in successfully you will be prompted to authorize the app you created to act on your behalf and to give it the requested permissions you defined when configuring the OAuth scopes in the previous section. If you get an error message at this point you may have misconfigured the scopes in you OAuth configuration.
Click Accept. If you OAuth configuration is correct you will be redirected to the K2 redirect uri you configured earlier (https://k2.denallix.com/identity/token/oauth/2 ) and be notified that authorization was successful.
You will be prompted with the Add Service Instance dialogue. Click Add to complete the Service Instance registration process. The newly created service instance will have a
Create the GraphUser object and run the Me method.
If you don’t already have a token or your token has expired, you may get prompted to re-authenticate with Office 365.
Example Custom Broker for Microsoft Graph If you need more flexibility than the REST Broker provides when working with Microsoft Graph, or any OAuth secured service, you can create a custom broker that takes advantage of the same OAuth settings you established in the previous section. A quick and very simple example of a custom broker that calls the “Me” service of Microsoft Graph is available here. https://github.com/jonnoking/K2Field.SmartObjects.Services.MicrosoftGraphExample Compile the project and create a new Service Type in SmartObject Tester (refer to Documentation).
Configure a new Service Instance on the new Service Type. In the Add Service Instance form select the same Service Authentication as with the REST Broker example.
In the code you’ll see that the broker tests to see if the service instance is configured for OAuth. If so it gets the OAuth token for the executing user and puts it in the Authorization header for the HTTP request.
Create an instance of the Microsoft Graph User SmartObject and execute the method.
