OAuth2 Authentication form field – application examples

Applies to version: 2021 R1 and above; author: Łukasz Chechelski

Introduction

The OAuth2 authentication standard is becoming increasingly popular, as it enables integration between different systems. In many cases, the connection takes place in the API → Application model, which makes authentication much easier. In this case, a predefined set of data is used – Client ID, Client Secret, and our subsequent actions are authorized by the token received in return.

But what if it is crucial to determine the user's context? This need is answered by the OAuth2 Authentication form field, which allows the user to be authenticated before connecting to the API and performing operations. The scenario described herein presents this feature using communication between MS Graph and Microsoft Azure. The configuration covered includes:

• OAuth2 Authentication form field
• Authentication via OAuth2
• MS Graph queried by REST calls.

Scenario and configuration

The prepared scenario describes a method for moving an attachment from a workflow instance to a SharePoint Online library (hereinafter referred to as SHO). It is also assumed that the file is uploaded not in the context of the application, but as a user.  In this way, information about the user who added the file to the corresponding library will be visible on the SharePoint Online side.

In such a scenario, user authentication must be properly enabled in the Azure Portal administration panel. The application created there must have the appropriate set of permissions to allow the user to log in and perform the appropriate operations in SHO. It is a good practice to define the minimum set of permissions required to perform operations. User.Read level permissions allow login, while those from the Sites family allow operations within the SHO library.

Fig. 1. Preview of application permissions in Azure

In terms of determining the required level of permissions for an application, the MS Graph documentation comes in handy. It contains a meticulously dissected set of permissions required in the context of selected endpoints. A link to the full documentation is provided at the end of this article. Below is an extract for the methods used in our example.

Fig. 2. Table showing the required permissions

Attention should also be paid to the "Authentication" tab of the created application. Here the Redirect URI is specified according to the following pattern
 

https://<<BPS_PORTAL_ADDRESS>>/OAuthFlows/ReceiveTokens

Fig. 3. Sample Redirect URI

In order to properly use the received token, the token authorization option must be enabled in the same window. The "Access tokens (used for implicit flows)" option is used for this. This is where you specify whether operations are performed on a single tenant or in a multi-tenant environment.

Fig. 4. Token configuration preview

The configuration in Designer Studio should be started by preparing the authentication in the Data sources tab. For the created authentication type OAuth2 User -> API, the Microsoft identity platform (Common) template should be selected. With this feature, the system will immediately load the necessary configuration. It remains to fill in the Client ID and Client Secret of the Azure application.

Authentication takes place within scopes, in accordance with the OAuth2 standard. The list should include:

• openid
• email
• profiles

Fig. 5. Authentication configuration in Designer Studio

Based on the authentication created in this way, a REST Web Service data source should be created. In its configuration, specify OAuth2 User -> API as the authentication type, and then select the created authentication. It is important to specify the base service instance URL: "https://graph.microsoft.com".

Fig. 6. Data source configuration in Designer Studio

The next step is to configure the form field responsible for user authentication. The OAuth2 Authentication form field is used for this purpose. Such a form field must be visible in the step where the user can log in. In the advanced configuration the connection that allows authentication is specified first. Three options are available among the operation modes:

• User – the form field displays a control that allows the user to log in to the configured authentication provider and, after the user has logged in, displays the corresponding status.
• JavaScript – in JavaScript mode, the control for the form field is not displayed. Instead, all Form rules (and JavaScript) work, including the GetToke rule, which allows you to programmatically retrieve the access token issued during user authentication. In this case, the authentication may take place "in the background".
• User + JavaScript – is a combination of the above two modes, offering the possibility of using both of them at the same time.

JavaScript mode works well in cases where authentication is to be initiated by the Form rule. In this mode, it is possible to use the IS AUTHENTICATED and AUTHENTICATE functions. Both of these functions take the OAuth2 Authentication form field as a parameter.

To ensure that the user does not forget to log in, it is possible to embed the following code in the path parameters. With this procedure, the user is prompted to log in while going through the path.

Fig. 7. Example of using the IS AUTHENTICATED and AUTHENTICATE functions

Another interesting feature is the token renewal functionality, which can be activated using the field located directly below the scopes. If the user's token expires during the session, this functionality allows it to be automatically renewed. This is done transparently, without any user interaction.

Since the appropriate scopes have been provided in the authentication configuration, there is no need to duplicate the values here. The scopes field remains empty.

Fig. 8. OAuth2 Authentication form field configuration

After saving the process, a new form field will appear on the form to allow login. After selecting the Sign in button, the system will connect to Azure and display an authentication window. In it, the user should enter their Microsoft account information.

Fig. 9. The Sign in window

After correct login, the control changes the displayed information. The mechanism supports MFA authentication if the tenant's security policy requires it. The SSO mechanism is also supported – the logged-in user will not be asked to provide data again.

Fig. 10. Control confirming user login

It is possible to use the mechanism configured in this way for authentication in the Invoke REST Web service action.

Communication with SHO is carried out via MS Graph, whose principle of operation is based on this standard. In the Authentication tab, specify the connection – exactly the same as in the OAuth2 control. With this solution, there is no need to reconfigure the connection to MS Graph from scratch.

Fig. 11. Configuration of the Invoke REST Web service action

To test the solution, the attachment is moved from the workflow instance to the indicated library. The attachment moved by the action will appear as added by a specific user, not the application. Therefore, it is important that the user has the appropriate permissions on the library side as well.

Fig. 12. File in the library – note that it has been modified by the user

Summary

The OAuth2 Authentication form field extends the possibilities of integrating WEBCON BPS with various external systems. Its use is not limited only to the cooperation with the Microsoft ecosystem – it can be used wherever the OAuth2 standard is supported, e.g., Google, auth0, or Keycloak. If the key is to perform operations in the context of the logged-in user, rather than the entire application, then it is worth considering the implementation of the described mechanism.

Useful links

• Graph Explorer – a web application that allows you to test MS Graph endpoints directly from the browser,
• Microsoft Graph REST API v1.0 endpoint reference – full MS Graph documentation,
• Configuration of the OpenID Connect authentication provider in WEBCON BPS – one of the examples of using the OAuth2 standard in WEBCON BPS. The article describes the method of configuring Google as one of the available authentication mechanisms for users.