Microsoft 365 Scope

UiPath.MicrosoftOffice365.Activities.Office365ApplicationScope

Description

Uses the Microsoft identity platform to establish an authenticated connection between UiPath and your Microsoft 365 application. This authenticated connection enables a Robot to call the Microsoft Graph API to read and write resources on your behalf.

Important: Starting with version 2.5.0-preview, you can use the newer Microsoft 365 activities inside the Scope activity. To learn how to use the Integration Service activities with Microsoft 365 Application Scope, see How to use Microsoft 365 activities without Integration Service connections.

Project compatibility

Windows - Legacy | Windows

Overview

To establish your authenticated connection, you first register your Microsoft 365 application in your Azure Active Directory (using your personal, work, and/or school Microsoft 365 account). When registering your application, you assign the Microsoft Graph API permissions that specify the resources a Robot can access on your behalf.

After registering your Microsoft 365 application, Azure Active Directory assigns a unique application (client) ID that you enter in the Microsoft 365 Scope activity. The Application ID is used to collect the necessary information about your registered app to initiate authentication.

To learn more about registering your application and assigning permission, see the Setup guide. This guide provides step-by-step instructions to configure your Microsoft 365 application for automation.

Note: For details regarding API scopes and permissions, see Microsoft 365 and Google Workspace Cards - API permissions and scopes.

Authentication types

Authentication types	As a User	As an Application (run as background service)	Attended	Unattended	Unattended (MFA enabled)	Details
Interactive Token						You have the option to register and use your own Azure AD app (i.e., OAuthApplication = Custom) or the one provided by UiPath (OAuthApplication = UiPath).
Integrated Windows Authentication (IWA)						Works only for federated users and if your registered Azure application is configured to support IWA. Doesn't work for Multi-Factor Authentication (MFA). See details here: IWA on GitHub
Username and Password						Not recommended, provided only for legacy reasons (it goes against the principles of modern authentication). It doesn't work for Multi-Factor Authentication (MFA). See details here: User & Password on GitHub
Application ID and Secret						Recommended for unattended executions or when you want to access the Microsoft Graph API as an application (a background service / daemon) without a signed-in user.
Application ID and Certificate						Available starting with v1.9.0. Very similar with Application Id and Secret. The only difference is the usage of a certificate as a secret instead of a client secret string. See the official documentation.

Configuration

• Connection method - Select the connection method you want to use. Options available in the dropdown menu are:
  • Properties Panel - Configure the connection details in the Properties panel.
  • Asset - Use Orchestrator credential assets. We recommend you use this option.

Asset connection method

When you select this option, the authentication fields displayed in the Properties Panel option are hidden, because all the authentication information is stored inside the asset.

• Connection assets - Browse Orchestrator folders to select an asset. This field supports IResource variables. Select the Manage Assets button to open Orchestrator. The list of available assets depends on the Orchestrator your Studio and Robot are connected to.
  • Use the Plus button menu to select Reload Assets if you've updated your assets in Orchestrator. Note that if you add a new asset in Orchestrator while using Studio Desktop, it will not be available straightaway in the Scope activity.

See the asset format in How to use Microsoft 365 activities without Integration Service connections.

Authentication

• Impersonated User Email Address - The email address of the impersonated user. Used for Application permissions.

Username and Password (Unattended)

• Username - The username of your Microsoft 365 account.
• Password - The password of your Microsoft 365 account.

Common

• TimeoutMS - Specifies the amount of time to wait (in milliseconds) for the interactive authentication (consent dialogue box) to complete before an error is thrown. This field supports only integer and Int32 variables. The default value is 30000ms (30 seconds).

Runtime

• Runtime connection assets - Browse to select an asset. This field allows you to select a different asset for runtime. Use the Plus button menu to select Relative path and enter the full path of the Orchestrator asset containing connection details.

Properties Panel connection method

Note: When you select this method, you configure the authentication fields in the Properties Panel, just like in previous versions of this package.

• Connections - Select an account from the list. You can add, delete, and choose what connections to use.
• Authentication Scopes - See the Using the Authentication Scopes wizard section below.

Using the Authentication Scopes wizard

Note: This wizard replaces the Services parameter available in previous versions of this package.

The Scope activity incorporates a universal permissions selector, offering a clear picture of all the used authentication scopes, which the activities need in order to work correctly.

All children activities included in the Microsoft 365 Application Scope activity are automatically detected as required scopes.

If no scopes are manually selected from the Scopes wizard, the Auto-detect function is applied by default at runtime, and the need for configuring the wizard is eliminated. All the minimum required scopes are selected at runtime.

You can also add a scope manually after adding a child activity to Microsoft 365 Application Scope.

Authentication

Important: Microsoft has deprecated Basic Authentication for Exchange online. This impacts some of our activities, such as Microsoft Office365 Scope. We recommend using the OAuth protocol in the activities that support it.

• Authentication Type - The type of authentication required for your registered application. Select one of the five options: InteractiveToken, IntegratedWindowsAuthentication, UsernameAndPassword, ApplicationIdAndSecret or ApplicationIdAndCertificate. The default value is InteractiveToken. For more information about these options and which one to select, see the Unattended vs. Attended Automation section below.
• Environment - The environment, either Azure Global or national clouds that are unique and separate environments from Azure Global. Select one of the five options: Default, Global, China, Germany or USGovernment. The default value is Global.
• Application ID - The unique application (client) ID assigned by the Azure Active Directory when you registered your app during Setup. The application (client) ID represents an instance of a Microsoft 365 application. A single organization can have multiple application (client) IDs for their Microsoft 365 account. Each application (client) ID contains its own permissions and authentication requirements. For example, you and your colleague can both register a Microsoft 365 application in your company's Azure Active Directory with different permissions. Your app could be configured to authorize permissions to interact with files only, while your colleague's app is configured to authorize permissions to interact with files, mail, and calendar. If you enter your application (client) ID into this property and run attended automation, the consent dialogue box would be limited to file permissions (and subsequently, only the Files activities can be used).
• Tenant - The unique directory (tenant) ID assigned by the Azure Active Directory when you registered your app during Setup. Required for multi-tenant applications and IntegratedWindowsAuthentication. The directory (tenant) ID can be found in the overview page of your registered application (under the application (client) ID).
• Impersonated User Email Address - The email address of the impersonated user.

Common

• TimeoutMS - Specifies the amount of time to wait (in milliseconds) for the interactive authentication (consent dialogue box) to complete before an error is thrown. This field supports only integer and Int32 variables. The default value is 30000ms (30 seconds) (not shown).
• ContinueOnError - If set, continue executing the remaining activities even if the current activity has failed.

Interactive token

Note: This is the same authentication method supported in Integration Service, either through the public UiPath App or a private custom application (Bring your own app method).

• OAuth Application - Indicates the application (client) to be used. If UiPath is selected, ApplicationID and Tenant are ignored. This field supports only OAuthApplication variables. Select one of the two options:
  • UiPath - Default. When you want to use the application created by UiPath. In this case, Application ID and Tenant parameter values are ignored.
  • Custom - When you want to create your own application with correct permissions. In this case, a value must be set for Application ID parameter.

Application ID and Certificate (Unattended)

• Certificate As Base64 - The Base64 representation of the certificate. Required if Authentication Type is set to Application ID and Certificate.

• Certificate Password - An optional password that may be required to use the certificate, as a Secure String.

Application ID and Secret (Unattended)

• Application Secret - The secret string that the application uses to provide its identity. Required if Authentication Type is set to Application ID and Secret.
• Secure Application Secret - The Application (client) secret, as a SecureString.

Username and Password (unattended)

These properties apply when you run unattended automation only. When specifying values for these properties, be sure the Authentication Type is set to Username and Password. For more information, see the Username and Password section below.

• Password - The password of your Microsoft 365 account.
• Secure Password - The password of your Microsoft 365 account, as a SecureString.
• Username - The username of your Microsoft 365 account.

How it works

The following steps and message sequence diagram is an example how the activity works from design time (i.e., the activity dependencies and input/output properties) to run time.

1. Complete the Setup steps.
2. Add the Microsoft Office 365 Scope activity to your project.

3. Enter values for the Authentication, Input, and Unattended (if applicable) properties.

   
   

   

   
   

Unattended vs. Attended Automation

The Microsoft 365 Scope activity has four different authentication flows (Authentication Types) that you can choose from when adding the activity to your project. Your selection is dependent on the type of automation mode you plan to run (unattended or attended) and your application authentication requirements (consult with your administrator if you're unsure which authentication requirements apply to your application).

AuthenticationType	Attended	Unattended	API Permission Type
Interactive Token	x		Delegated permissions
Integrated Windows Authentication		x	Delegated permissions
Username and Password		x	Delegated permissions
Application ID and Secret		x	Application permissions
Application ID and Certificate		x	Application permissions

Important:

Integrated Windows Authentication or Username and Password authentication types do not work when Multi-Factor Authentication (MFA) is enabled. If your application requires MFA, you can run attended automation using the Interactive Token authentication type or unattended automation using Application ID and Secret and Application ID and Certificate. Application ID and Secret and Application ID and Certificate authentication types are appropriate for unattended automation and work regardless of whether the MFA is enabled or disabled.

When registering your application, you must select an application type. Consider the following requirements:

• For Attended scenarios (Interactive Token authentication type) and Unattended with Integrated Windows Authentication, use a mobile/desktop application (which uses OAuth 2.0 authorization code flow).

• For Unattended scenarios (Username and Password, Application ID and Secret, Application ID and Certificate), use a confidential/web application (which uses OAuth 2.0 client credentials flow).

Interactive Token

The Interactive Token authentication type can be used for attended automation and when multi-factor authentication (MFA) is required. This is the default option and what we use in our examples. If you're interested in trying out the activity package, this option is easy to configure and works well for personal accounts (using the default redirect URI noted in step 7 of the Register your application section of the Setup guide).

When the Microsoft 365 activity is run for the first time using this authentication type, you are prompted to authorize access to the resources (you granted permissions to when registering your app) via a consent dialogue box.

If you select this option, the Username, Password, and Tenant properties should be left empty.

Integrated Windows Authentication

The Integrated Windows Authentication authentication type can be used for unattended automation. This option can apply to Windows hosted applications running on computers joined to a Windows domain or Azure Active Directory.

You should only select this option if your registered application is configured to support Integrated Windows Authentication (additional information can be found on GitHub).

If you select this option, the Username and Password properties should be left empty. The Tenant property is optional.

Username and Password

The Username and Password authentication type can be used for unattended automation.

Although it is not recommended by Microsoft, you can use this authentication type in public client applications. Using this authentication type imposes constraints on your application. For instance, apps using this flow won't be able to sign in a user who needs to perform multi-factor authentication (conditional access). It won't enable your application to benefit from single sign-on either.

If you select this option, the Username and Password properties are required and the Tenant property is optional for single-tenant applications (required for multi-tenant applications).

Note: The ApplicationID property is required when selecting the Username and Password authentication type. You can register your Microsoft 365 Application using your personal, work, and/or school account.

Application ID and Secret

In the matter of authentication with Application (client) ID and Application (client) Secret, keep in mind the following:

• The appropriate API permissions must be configured for the Azure application in order for Microsoft 365 activities to work properly (e.g. the application permissions Group.Create, Group.Read.All and Group.ReadWrite.All should be configured for Microsoft Graph when using Groups activities).
• Some activities can't be used with this type of authentication because the corresponding Microsoft Graph API does not support application permissions. See the official Microsoft documentation.
• For email activities - Get Mail, Forward Mail, Send Mail, and Move Email - it is mandatory to specify a value for the Account parameter.

Application ID and Certificate

In order to authenticate using a certificate as a secret, please follow these steps:

1. In the Azure portal:

   • Locate your registered Microsoft 365 application.
   • Select Certificates & secrets and upload your certificate (public key) file. It can have one of the following file types: .cer, .pem, .crt.
     
     

     

     
     
2. Convert the raw contents of your .pfx file representing the certificate to a base64 string. To do this, use a web-based tool like Base64.Guru or assign Convert.ToBase64String(System.IO.File.ReadAllBytes(pfxFilePath)) to a String variable.
3. In the Microsoft 365 Scope activity:

• Set Authentication Type to Application ID and Certificate.
• Set Certificate as Base64 to the base64 representation of the certificate.

• If a password is required to use the certificate, set the value for the Certificate Password property as well.

  Note: The same description as for the Application ID and Secret section also applies to Application ID and Certificate.

Troubleshooting

If you encounter any issues with authentication, see Troubleshooting - Authentication.