Most of the tutorials and OutSystems Forum answers you find explain how you can access Microsoft Graph API using application credentials. There are many use-cases where you want to use the Graph with the currently logged on user credentials. I haven’t found a step-by-step tutorial, so here is one.

What is OutSystems?

OutSystems is low code application platform. A visual development environment supporting your complete application development lifecycle. Low code means that you still can use custom code whether it be JavaScript on the frontend or C# on server-side. You can read more about OutSystems on their website.

What is Microsoft Graph?

Graph is a unified REST API gateway to data of the Microsoft 365 universe, ranging from querying to configuration options of your Microsoft 365 tenant. You can read more about the Microsoft Graph API here.

Summary

We will create a new OutSystems Reactive application and configure the login flow to authenticate against your Azure Active Directory tenant. For this we are using the Microsoft Login Connector Forge component. We then use the OAuth2 access token of the logged in user to perform operations against the Microsoft Graph API To-do tasks endpoints. For this we are using another Forge component Microsoft Graph To-do Tasks.

If you have configured your OutSystems Users provider to authenticate against Azure Active Directory, you might wonder why we are using another component for authentication. The short answer is that the Users provider uses the SAML protocol which does not give you an OAuth2 access token. Only OAuth2 access tokens are supported by Microsoft Graph API.

The Microsoft Login Connector Forge component

The component is a community project by

• Vincent Koning
• Paul Davies
• Miguel Amado
• Hugo Codinha

It is an exceptional high-quality component free to use in your own environment. From own experience i know that creating and maintaining Forge projects is a huge effort and, in many cases, done in their spare time.

The Microsoft Graph API To-do Tasks Forge component

This is my OutSystems Forge contribution. You can find my OutSystems Profile here. If you want to know more about other components of me and ISD FENIQS, please visit Anvil. Anvil is our dedicated microsite for all our OutSystems components.

What you need

To follow this tutorial, you need

• An OutSystems development environment. (A personal environment is sufficient)
• Microsoft Login Connector Reactive from OutSystems Forge, along with Microsoft Login Connector Core (gets automatically installed when you install the first component)
• Microsoft Login Connector Management from OutSystems Forge.
• Microsoft Graph To-do Tasks Connector from OutSystems Forge.

Now it is a good time to install all those Forge components 🙂

What we will do

• Add application configuration in your Azure AD to let user’s login from your OutSystems application.
• Configure Microsoft Login Connector and your application login flow.
• Retrieve access token and use it to perform Microsoft Graph API To-do Tasks operations.

Step by Step

Although it is our users which authenticates against Azure Active Directory, we need to setup an application configuration in our tenant. We tell Azure AD to allow users to authenticate coming from a specific application and configure which permissions on so called resources we require. The Microsoft Graph API is one resource.

Step 1 — Register Azure Active Directory application

Go to your Azure portal at https://portal.azure.com

In the top search bar search for App Registrations and click on App registrations in the Services section.

In the App Registrations list screen click on New Registration.

• Provide a meaningful name for your application
• Select Accounts in this organizational directory only. (we only want to allow users from our own organization and not from others)
• Under Redirect URI select Web from the dropdown and enter https://<your OutSystems environment>/MicrosoftLoginConnectorReactive/CallbackPage
• Click on Register

Step 2 — Note Client Id

On your new application dashboard copy the client id and tenant id. We need that later when we configure the Microsoft Login Connector in OutSystems.

Step 3 — Generate Secret

In the left pane under Manage click on Certificates & Secrets. Check that the Client secrets tab is select and click on New client secret.

Enter a description for your secret and an expiration. The click Add.

In the following screen it is important to immediately copy the client secret (Value). The client secret is only shown once on this screen and cannot be retrieved later. We need the client secret (together with the client id earlier) for configuring the Microsoft Login Connector.

Step 4 — Configure permissions

The last step is to configure permissions. In the left pane click on API permissions. You will note that there is already one permission set User.Read of type delegated. This is the least permission needed for users to login.

There are two types of permissions.

• Delegated — your application accesses the API as the signed in user.
• Application — your application accesses the API

In this tutorial we are focussing on the Delegated type as we want to do all operations as the logged in user.

We need to assign additional permissions. As we want to access the Graph API To-do Tasks endpoint, we need to add the following permission

• Tasks.ReadWrite

This gives our application the right to Read and Write tasks of the logged in user. You can also add Tasks.ReadWrite.Shared if you want to perform operations on shared task lists and tasks.

• Click on Add a permission
• Select Microsoft Graph and Delegated permission
• From the list of permissions select Tasks > Tasks.ReadWrite
• Click on Add permissions

Step 5 — Create an OutSystems Reactive application

In Service Studio create a new Reactive Web Application. Create the default Reactive Web module and publish it. For the time being we leave it as is. We just need that Espace, so that we can configure the Microsoft Login Connector in one step.

Step 6 — Configure Microsoft Login Connector

Now we configure the Microsoft Login Connector. We use the Management console which is accessible under https://<your OutSystems environment>/MicrosoftLoginConnectorManagement

On the start screen add a new application and fill in the details. You need

• Client Id and Tenant Id from Step 2
• Client Secret from Step 3

Next click the Espaces tab and add your created Reactive Webapplication. Here in the screen the app is called GraphAPI.

Finally click the Resources tab and add the Microsoft Graph API Resource as default.

Step 7 — Add required dependencies

Open your created Reactive Web module in Service Studio. We first need some dependencies before we can start to modify the default login flow.

Add dependencies

• GetOAuth2AuthenticationUrl from MicrosoftLoginConnectorReactive module
• GetOAuth2LogoutUrl from MicrosoftLoginConnectorReactive module

• GetUserToken from MicrosoftLoginConnectorCore module
• GetUserInfoByUserId from MicrosoftLoginConnectorCore module
• OAuthProvider static entity from MicrosoftLoginConnectorCore module

Step 8 — Modify login flow

We start by modifying the general OnException Handler in the Common UI flow.

Here we exchange the default server action User_GetUnifiedLoginUrl with GetOAuth2AuthenticationUrl from MicrosoftLoginConnectorReactive module.

Configure the server action with

• Set EspaceName to GetEntryEspaceName()
• Set OAuthProviderId to Entities.OAuthProvider.AzureAd

Leave the rest blank and correct the following if and redirect actions. Your flow should look now like this

Next, we modify the DoLogout server action (in folder Authentication). Exchange the default server action User_GetUnifiedLogoutUrl with GetOAuth2LogoutUrl from MicrosoftLoginConnectorReactive module and correct the following if and redirect statements.

Step 9 — Create a screen and test login

Create your first screen (eg. Start) as default screen. Publish your application and test if you can login with your Azure AD credentials. You should use a new InPrivate browser session as OutSystems has a cookie first authentication approach. If you are already authenticated in your OutSystems environment, you first have to logoff.

Step 10 — Create Token retrieval server action

Whenever we access Microsoft Graph API, we need the access token for the current user. Luckily the Microsoft Login Connector provides a straightforward way to retrieve the access token.

To get the access token we first need the Azure E-Mail address for the current user. This one is used to retrieve the access token.

These are the steps

• Lookup the used Azure E-Mail address for the current user
• Use that E-Mail address to get the cached access token
• Raise an exception if the current user does not have a cached access token.

Later we handle the exception and redirect the user to the login page.

You might wonder how it can be that a user has access but does not have a cached access token. If someone logs into an Outsystems application which has the default username and password login flow, the user is already authenticated thus will not be redirected to the Azure AD login page. That is the above-mentioned cookie first authentication mechanism.

Create a new server action and call it GetOAuthToken with no input parameters and single output parameter Token of type text.

• Add the GetUserInfoByUserId server action from the MicrosoftLoginConnectorCore module. For the UserId parameter use GetUserId().

• Add an If statement with condition GetUserInfoByUserId.UserDoesNotHaveToken

• On the true branch of the if statement add a Raise Exception with a new User Exception. Name that exception TokenException. As message you can use something like “The user does not have an access token”

• On the false branch add the server action GetUserToken from MicrosoftLoginConnectorCore module. Configure as follows

• Assign the token result from GetUserToken to the output parameter.

Your flow should look like this now

Step 11 — Handle the TokenException

If a user does not have an access token, we need to redirect the user to the login url to perform the login. In many cases that will be seamless as the user will — most likely — automatically log in. After successful login, the token is cached, and we can use it.

• In your MainFlow UI Flow add a new On Exception Action (you can also modify the general OnException in Common UI flow).
• Configure the Exception Handler to handle the TokenException.

• Add GetOAuth2AuthenticationUrl client action from MicrosoftLoginConnectorReactive module and configure it

• Exchange the default End with a RedirectToUrl destination set to the output Url of the GetOAuth2AuthenticationUrl action.

If this leads to a 404 on the Callback page please refer to the offical documentation of the MicrosoftLoginConnectorReactive component. It shows you the steps to take using FactoryConfiguration. Unfortunately this does not work in Personal Environments.

Step 12 — Your first Microsoft Graph API operation

With all these steps done — thank for joining me so far — it is finally time to perform our first Graph API operation. On our created Start screen, we will retrieve available task lists for the current user.

• In your application add a new dependency to the Graph_TodoTasks_IS module. Select at least the Graph_TaskListList operation or everything if want to extend your application further. (From Microsoft Graph To-do Tasks Forge component)

• Add a new Data action to your Start screen (GetTaskLists)
• Set the output parameter (e.g. List) to a List of TaskList_Result
• Add the GetOAuthToken server action to the flow
• Add Graph_TaskListList from Graph_TodoTasks_IS module to the flow and configure it

• Add an if statement with the following condition

• Raise a new exception GraphException on the true branch
• Assign the result of the Graph_TaskListList action to the output parameter of your data action.

Your flow should look like this now

• Drag-and-Drop the List output parameter of your data action to the main content area of the screen to scaffold a table.

Thats it. You can try it and see if you get a result from your query. Use the Microsoft To-do app and create additional lists.

Explore the other actions from the Microsoft Graph To-do Tasks Forge component and create task lists and tasks directly from your OutSystems application with delegated user permissions.

If you had difficulties in getting up and running, please use the OutSystems Forum to get help. Suggestions on how to improve this article are very welcome. Send me a message via my OutSystems Profile or respond directly here on medium.

About the Author:

Reference:

Weber, S. (2022). Getting started with OutSystems and Microsoft Graph — Delegated Permissions. Available at; https://stefan-weber.medium.com/getting-started-with-outsystems-and-microsoft-graph-123006356d41 [Accessed: 29th July 202].