Stable Version (PyPI)

The latest stable package is hosted onPyPI.

To install using pip, run:

pip install o365

or use uv:

uv add o365

Requirements: >= Python 3.9

Project dependencies installed by pip:

• requests

• msal

• beatifulsoup4

• python-dateutil

• tzlocal

• tzdata

Latest Development Version (GitHub)

The latest development version is available onGitHub.This version may include new features but could be unstable.Use at your own risk.

Using pip, run:

pip install git+https://github.com/O365/python-o365.git

Or with uv, run:

uv add "o365 @ git+https://github.com/O365/python-o365"

Types

You can only authenticate using OAuth authentication because Microsoft deprecated basic auth on November 1st 2018.

There are currently three authentication methods:

• Authenticate on behalf of a user: Any user will give consent to the app to access its resources. This OAuth flow is called authorization code grant flow. This is the default authentication method used by this library.

• Authenticate on behalf of a user (public): Same as the former but for public apps where the client secret can’t be secured. Client secret is not required.

• Authenticate with your own identity: This will use your own identity (the app identity). This OAuth flow is called client credentials grant flow.

When to use one or the other and requirements:

Note: *O365 will automatically refresh the token for you on either authentication method. The refresh token lasts 90 days, but it’s refreshed on each connection so as long as you connect within 90 days you can have unlimited access.

The Connection Class handles the authentication.

With auth_flow_type ‘credentials’ you can authenticate using a certificate based authentication by just passing the client_secret like so:

client_secret={"thumbprint":<thumbprintofcertfile>,"private_key":<privatekeyfromtheprivate_key_file>}credentials=client_id,client_secretaccount=Account(credentials)

OAuth Setup (Prerequisite)

Before you can use python-o365, you must register your application in theMicrosoft Entra Admin Center. Follow the steps below:

1. Log in to the Microsoft Entra Admin Center

   • Visithttps://entra.microsoft.com/ and sign in.

2. Create a new application and note its App (client) ID

   • In the left navigation bar, selectApplications >App registrations.

   • Click+ New registration.

   • Provide aName for the application and keep all defaults.

   • From theOverview of your new application, copy the (client_id)Application (client) ID for later reference.

3. Generate a new password (client_secret)

   • In theOverview window, selectCertificates & secrets.

   • ClickNew client secret.

   • In theAdd a client secret window, provide a Description and Expiration, then clickAdd.

   • Save the (client_secret)Value for later reference.

4. Add redirect URIs

   • In theOverview window, clickAdd a redirect URI.

   • Click+ Add a platform, then selectWeb.

   • Addhttps://login.microsoftonline.com/common/oauth2/nativeclient as the redirect URI.

   • ClickSave.

5. Add required permissions

   • In the left navigation bar, selectAPI permissions.

   • Click+ Add a permission.

   • UnderMicrosoft Graph, selectDelegated permissions.

   • Add the delegated permissions you plan to use (for example):

     • Mail.Read

     • Mail.ReadWrite

     • Mail.Send

     • User.Read

     • User.ReadBasic.All

     • offline_access

   • ClickAdd permissions.

Examples

Then you need to log in for the first time to get the access token that will grant access to the user resources.

To authenticate (login) you can useDifferent interfaces. On the following examples we will be using the Console Based Interface, but you can use any of them.

• When authenticating on behalf of a user:

  1. Instantiate anAccount object with the credentials (client id and client secret).

  2. Callaccount.authenticate and pass the scopes you want (the ones you previously added on the app registration portal).

     > Note: when using the “on behalf of a user” authentication, you can pass the scopes to either theAccount init or to the authenticate method. Either way is correct.

     You can pass “protocol scopes” (like: “https://graph.microsoft.com/Calendars.ReadWrite”) to the method or use “[scope helpers](https://github.com/O365/python-o365/blob/master/O365/connection.py#L34)” like (“message_all”).If you pass protocol scopes, then theaccount instance must be initialized with the same protocol used by the scopes. By using scope helpers you can abstract the protocol from the scopes and let this library work for you.Finally, you can mix and match “protocol scopes” with “scope helpers”.Go to the [procotol section](#protocols) to know more about them.

     For Example (following the previous permissions added):

     fromO365importAccountcredentials=('my_client_id','my_client_secret')# the default protocol will be Microsoft Graph# the default authentication method will be "on behalf of a user"account=Account(credentials)ifaccount.authenticate(scopes=['basic','message_all']):print('Authenticated!')# 'basic' adds: 'https://graph.microsoft.com/User.Read'# 'message_all' adds: 'https://graph.microsoft.com/Mail.ReadWrite' and 'https://graph.microsoft.com/Mail.Send'

     When using the “on behalf of the user” authentication method, this method call will print an url that the user must visit to give consent to the app on the required permissions.

     The user must then visit this url and give consent to the application. When consent is given, the page will rediret to: “https://login.microsoftonline.com/common/oauth2/nativeclient” by default (you can change this) with an url query param called ‘code’.

     Then the user must copy the resulting page url and paste it back on the console.The method will then return True if the login attempt was succesful.

• When authenticating with your own identity:

  1. Instantiate anAccount object with the credentials (client id and client secret), specifying the parameterauth_flow_type to“credentials”. You also need to provide a ‘tenant_id’. You don’t need to specify any scopes.

  2. Callaccount.authenticate. This call will request a token for you and store it in the backend. No user interaction is needed. The method will store the token in the backend and return True if the authentication succeeded.

  For Example:

  fromO365importAccountcredentials=('my_client_id','my_client_secret')# the default protocol will be Microsoft Graphaccount=Account(credentials,auth_flow_type='credentials',tenant_id='my-tenant-id')ifaccount.authenticate():print('Authenticated!')

At this point you will have an access token stored that will provide valid credentials when using the api.

The access token only lasts60 minutes, but the app will automatically request new access tokens if you added the ‘offline access’ permission.

When using the “on behalf of a user” authentication method this is accomplished through the refresh tokens (if and only if you added the “offline_access” permission), but note that a refresh token only lasts for 90 days. So you must use it before, or you will need to request a new access token again (no new consent needed by the user, just a login). If your application needs to work for more than 90 days without user interaction and without interacting with the API, then you must implement a periodic call to Connection.refresh_token before the 90 days have passed.

Different interfaces

To accomplish the authentication you can basically use different approaches. The following apply to the “on behalf of a user” authentication method as this is 2-step authentication flow. For the “with your own identity” authentication method, you can just use account.authenticate as it’s not going to require a console input.

1. Console based authentication interface:

   You can authenticate using a console. The best way to achieve this is by using the authenticate method of the Account class.

   account = Account(credentials)account.authenticate(scopes=[‘basic’, ‘message_all’])The authenticate method will print into the console an url that you will have to visit to achieve authentication. Then after visiting the link and authenticate you will have to paste back the resulting url into the console. The method will return True and print a message if it was succesful.

   Tip: When using macOS the console is limited to 1024 characters. If your url has multiple scopes it can exceed this limit. To solve this. Just import readline at the top of your script.

2. Web app based authentication interface:

   You can authenticate your users in a web environment by following these steps:

   1. First ensure you are using an appropiate TokenBackend to store the auth tokens (See Token storage below).

   2. From a handler redirect the user to the Microsoft login url. Provide a callback. Store the flow dictionary.

   3. From the callback handler complete the authentication with the flow dict and other data.

   The following example is done using Flask.

   fromflaskimportrequestfromO365importAccount@route('/stepone')defauth_step_one():# callback = absolute url to auth_step_two_callback() page, https://domain.tld/steptwocallback=url_for('auth_step_two_callback',_external=True)# Flask exampleaccount=Account(credentials)url,flow=account.con.get_authorization_url(requested_scopes=my_scopes,redirect_uri=callback)flow_as_string=serialize(flow)# convert the dict into a string using json for example# the flow must be saved somewhere as it will be needed latermy_db.store_flow(flow_as_string)# example...returnredirect(url)@route('/steptwo')defauth_step_two_callback():account=Account(credentials)# retrieve the state saved in auth_step_onemy_saved_flow_str=my_db.get_flow()# example...my_saved_flow=deserialize(my_saved_flow_str)# convert from a string to a dict using json for example.# rebuild the redirect_uri used in auth_step_onecallback='my absolute url to auth_step_two_callback'# get the request URL of the page which will include additional auth information# Example request: /steptwo?code=abc123&state=xyz456requested_url=request.url# uses Flask's request() methodresult=account.con.request_token(requested_url,flow=my_saved_flow)# if result is True, then authentication was successful#  and the auth token is stored in the token backendifresult:returnrender_template('auth_complete.html')# else ....

3. Other authentication interfaces:

   Finally, you can configure any other flow by usingconnection.get_authorization_url andconnection.request_token as you want.

Permissions

When using oauth, you create an application and allow some resources to be accessed and used by its users. These resources are managed with permissions. These can either be delegated (on behalf of a user) or application permissions. The former are used when the authentication method is “on behalf of a user”. Some of these require administrator consent. The latter when using the “with your own identity” authentication method. All of these require administrator consent.

Scopes

The scopes only matter when using the “on behalf of a user” authentication method.

The user of this library can then request access to one or more of these resources by providing scopes to the OAuth provider.

For example your application can have Calendar.Read, Mail.ReadWrite and Mail.Send permissions, but the application can request access only to the Mail.ReadWrite and Mail.Send permission. This is done by providing scopes to the Account instance or account.authenticate method like so:

fromO365importAccountcredentials=('client_id','client_secret')scopes=['Mail.ReadWrite','Mail.Send']account=Account(credentials,scopes=scopes)account.authenticate()# The latter is exactly the same as passing scopes to the authenticate method like so:# account = Account(credentials)# account.authenticate(scopes=scopes)

Scope implementation depends on the protocol used. So by using protocol data you can automatically set the scopes needed. This is implemented by using ‘scope helpers’. Those are little helpers that group scope functionality and abstract the protocol used.

You can get the same scopes as before using protocols and scope helpers like this:

protocol_graph=MSGraphProtocol()scopes_graph=protocol.get_scopes_for('message_all')# scopes here are: ['https://graph.microsoft.com/Mail.ReadWrite', 'https://graph.microsoft.com/Mail.Send']account=Account(credentials,scopes=scopes_graph)