Microsoft 365 - Credentials¶

Use the BotCity plugin for Microsoft Credentials to authenticate your account and be able to use Microsoft 365 services.

Warning

To be able to use this plugin, you need to have a Microsoft 365 account with a properly created and configured project.

For more details, see the Creating Microsoft 365 Credentials section.

Installation¶

PythonJava

pip install botcity-ms365-credentials-plugin

Importing the Plugin¶

After you installed this package, the next step is to import the package into your code and start using the functions.

PythonJava

from botcity.plugins.ms365.credentials import MS365CredentialsPlugin

Setting up project credentials¶

First, let's authenticate our Microsoft 365 account using the project credentials created in the Creating Microsoft 365 Credentials section.

At this point, we will need the information we extracted during the process, the Application (client) ID and the Secret Value of the project.

PythonJava

# Instantiate the plugin
service = MS365CredentialsPlugin(
    client_id='<APPLICATION ID>',
    client_secret='<SECRET VALUE>',
)

Defining scopes and authenticating¶

In this step, we will define the scope of the services we want to use.

To define the scopes that will be used, we will use the permissions that we added to the project as a reference.

You can create a list of scopes using the values defined in the Scopes class, the table below describes the available scopes:

Scope	Description
`Scopes.BASIC`	Basic authentication, used for `User.Read`, `offline_access` pemissions
`Scopes.FILES_READ`	Used for `Files.Read.All` permission
`Scopes.FILES_READ_WRITE_ALL`	Used for `Files.ReadWrite.All` permission
`Scopes.SITES_READ_ALL`	Used for `Sites.Read.All` permission
`Scopes.SITES_READ_WRITE_ALL`	Used for `Sites.ReadWrite.All` permission
`Scopes.MAIL_READ`	Used for `Mail.Read` permission
`Scopes.MAIL_SEND`	Used for `Mail.Send` permission
`Scopes.MAIL_READ_WRITE`	Used for `Mail.ReadWrite` permission (read, write and send emails)

Important

When instantiating the plugin, the list of scopes must match the permissions added to the project.

This step is essential to ensure no permission issues when using the APIs.

PythonJava

from botcity.plugins.ms365.credentials import MS365CredentialsPlugin, Scopes

# Instantiate the plugin
service = MS365CredentialsPlugin(
    client_id='<APPLICATION ID>',
    client_secret='<SECRET VALUE>',
)
# Defining the scopes list
scopes_list = [Scopes.BASIC, Scopes.FILES_READ_WRITE_ALL, Scopes.MAIL_READ_WRITE]

service.authenticate(scopes=scopes_list)

Tip

The FILES_READ_WRITE_ALL scope referring to the Files.ReadWrite.All permission, is already enough to use OneDrive and Excel services.

The example scopes above would be enough for us to use OneDrive, Excel, and Outlook services.

Finishing the authentication flow¶

Warning

In the first run, it is necessary that the process be done manually so that the token file is generated.

For the subsequent runs, authentication is done automatically if the token file already exists and is still valid.

At this point, when running the code for the first time, a link will be displayed in the terminal to be opened in the browser.

In the opened browser, you have to log in to your Microsoft account that is being used, copy the complete URL that was generated and paste it into the terminal where you ran the code.

The generated URL will be something like this:

After that, a file called o365_token.txt will be created. This file will be used for the next authentications, it is not necessary to perform this process again until the token expires.

Using Microsoft 365 services¶

At this point, you already have an instance of MS365CredentialsPlugin properly configured.

You can directly access the APIs through the ms365_account property, or use this plugin instance when instantiating the OneDrive, Excel, and Outlook plugins.