Token

class O365.utils.token.AWSS3Backend(bucket_name, filename)

Bases: BaseTokenBackend

An AWS S3 backend to store tokens

__init__(bucket_name, filename)

Init Backend :param str bucket_name: Name of the S3 bucket :param str filename: Name of the S3 file

check_token() → bool

Checks if the token exists :return bool: True if it exists on the store

delete_token() → bool

Deletes the token from the store :return bool: Success / Failure

load_token() → bool

Retrieves the token from the store

return bool:

Success / Failure

save_token(force=False) → bool

Saves the token dict in the store :param bool force: Force save even when state has not changed :return bool: Success / Failure

bucket_name

S3 bucket name.

   Type: str

filename

S3 file name.

   Type: str

class O365.utils.token.AWSSecretsBackend(secret_name, region_name)

Bases: BaseTokenBackend

An AWS Secrets Manager backend to store tokens

__init__(secret_name, region_name)

Init Backend :param str secret_name: Name of the secret stored in Secrets Manager :param str region_name: AWS region hosting the secret (for example, ‘us-east-2’)

check_token() → bool

Checks if the token exists :return bool: True if it exists on the store

delete_token() → bool

Deletes the token from the store :return bool: Success / Failure

load_token() → bool

Retrieves the token from the store :return bool: Success / Failure

save_token(force=False) → bool

Saves the token dict in the store :param bool force: Force save even when state has not changed :return bool: Success / Failure

region_name

AWS Secret region name.

   Type: str

secret_name

AWS Secret secret name.

   Type: str

class O365.utils.token.BaseTokenBackend

Bases: TokenCache

A base token storage class

__init__()

add(event, **kwargs) → None

Add to the current cache.

check_token() → bool

Optional Abstract method to check for the token existence in the backend

delete_token() → bool

Optional Abstract method to delete the token from the backend

deserialize(token_cache_state: bytes | str) → dict

Deserialize the cache from a state previously obtained by serialize()

get_access_token(*, username: str | None = None) → dict | None

Retrieve the stored access token If username is None, then the first access token will be retrieved :param str username: The username from which retrieve the access token

get_account(*, username: str | None = None, home_account_id: str | None = None) → dict | None

Gets the account object for the specified username or home_account_id

get_all_accounts() → list[dict]

Returns a list of all accounts present in the token cache

get_id_token(*, username: str | None = None) → dict | None

Retrieve the stored id token If username is None, then the first id token will be retrieved :param str username: The username from which retrieve the id token

get_refresh_token(*, username: str | None = None) → dict | None

Retrieve the stored refresh token If username is None, then the first access token will be retrieved :param str username: The username from which retrieve the refresh token

get_token_scopes(*, username: str | None = None, remove_reserved: bool = False) → list | None

Retrieve the scopes the token (refresh first then access) has permissions on :param str username: The username from which retrieve the refresh token :param bool remove_reserved: if True RESERVED_SCOPES will be removed from the list

load_token() → bool

Abstract method that will retrieve the token data from the backend This MUST be implemented in subclasses

modify(credential_type, old_entry, new_key_value_pairs=None) → None

Modify content in the cache.

remove_data(*, username: str) → bool

Removes all tokens and all related data from the token cache for the specified username. Returns success or failure. :param str username: The username from which remove the tokens and related data

save_token(force=False) → bool

Abstract method that will save the token data into the backend This MUST be implemented in subclasses

serialize() → bytes | str

Serialize the current cache state into a string.

should_refresh_token(con: Connection | None = None, *, username: str | None = None) → bool | None

This method is intended to be implemented for environments where multiple Connection instances are running on parallel.

This method should check if it’s time to refresh the token or not. The chosen backend can store a flag somewhere to answer this question. This can avoid race conditions between different instances trying to refresh the token at once, when only one should make the refresh.

This is an example of how to achieve this:

1. Along with the token store a Flag

2. The first to see the Flag as True must transactional update it to False. This method then returns True and therefore the connection will refresh the token.

3. The save_token method should be rewritten to also update the flag back to True always.

4. Meanwhile between steps 2 and 3, any other token backend checking for this method should get the flag with a False value.

This method should then wait and check again the flag.

This can be implemented as a call with an incremental backoff factor to avoid too many calls to the database.

At a given point in time, the flag will return True.

Then this method should load the token and finally return False signaling there is no need to refresh the token.

If this returns True, then the Connection will refresh the token.

If this returns False, then the Connection will NOT refresh the token as it was refreshed by another instance or thread.

If this returns None, then this method has already executed the refresh and also updated the access token into the connection session and therefore the Connection does not have to.

By default, this always returns True

There is an example of this in the example’s folder.

Parameters:

• con – the Connection instance passed by the caller. This is passed because maybe the locking mechanism needs to refresh the token within the lock applied in this method.

• username – The username from which retrieve the refresh token

Returns:

True if the Connection should refresh the token

False if the Connection should not refresh the token as it was refreshed by another instance

None if the token was refreshed by this method and therefore the Connection should do nothing.

token_expiration_datetime(*, username: str | None = None) → datetime | None

Returns the current access token expiration datetime If the refresh token is present, then the expiration datetime is extended by 3 months :param str username: The username from which check the tokens :return dt.datetime or None: The expiration datetime

token_is_expired(*, username: str | None = None) → bool

Checks whether the current access token is expired :param str username: The username from which check the tokens :return bool: True if the token is expired, False otherwise

token_is_long_lived(*, username: str | None = None) → bool

Returns if the token backend has a refresh token

cryptography_manager: CryptographyManagerType | None

Optional cryptography manager.

   Type: CryptographyManagerType

property has_data: bool

Does the token backend contain data.

serializer = <module 'json' from '/opt/hostedtoolcache/Python/3.12.9/x64/lib/python3.12/json/__init__.py'>

class O365.utils.token.BitwardenSecretsManagerBackend(access_token: str, secret_id: str)

Bases: BaseTokenBackend

A Bitwarden Secrets Manager backend to store tokens

__init__(access_token: str, secret_id: str)

Init Backend :param str access_token: Access Token used to access the Bitwarden Secrets Manager API :param str secret_id: ID of Bitwarden Secret used to store the O365 token

load_token() → bool

Retrieves the token from Bitwarden Secrets Manager :return bool: Success / Failure

save_token(force=False) → bool

Saves the token dict in Bitwarden Secrets Manager :param bool force: Force save even when state has not changed :return bool: Success / Failure

client

Bitwarden client.

   Type: BitWardenClient

secret

Bitwarden secret.

   Type: str

secret_id

Bitwarden secret is.

   Type: str

class O365.utils.token.CryptographyManagerType(*args, **kwargs)

Bases: Protocol

Abstract cryptography manager

__init__(*args, **kwargs)

decrypt(data: bytes) → str

encrypt(data: str) → bytes

class O365.utils.token.DjangoTokenBackend(token_model=None)

Bases: BaseTokenBackend

A Django database token backend to store tokens. To use this backend add the TokenModel model below into your Django application.

class TokenModel(models.Model):
    token = models.JSONField()
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    def __str__(self):
        return f"Token for {self.token.get('client_id', 'unknown')}"

Example usage:

from O365.utils import DjangoTokenBackend
from models import TokenModel

token_backend = DjangoTokenBackend(token_model=TokenModel)
account = Account(credentials, token_backend=token_backend)

__init__(token_model=None)

Initializes the DjangoTokenBackend.

Parameters:

token_model – The Django model class to use for storing and retrieving tokens (defaults to TokenModel).

check_token() → bool

Checks if any token exists in the Django database :return bool: True if it exists, False otherwise

delete_token() → bool

Deletes the latest token from the Django database :return bool: Success / Failure

load_token() → bool

Retrieves the latest token from the Django database :return bool: Success / Failure

save_token(force=False) → bool

Saves the token dict in the Django database :param bool force: Force save even when state has not changed :return bool: Success / Failure

token_model

Django token model

   Type: TokenModel

class O365.utils.token.EnvTokenBackend(token_env_name=None)

Bases: BaseTokenBackend

A token backend based on environmental variable.

__init__(token_env_name=None)

Init Backend :param str token_env_name: the name of the environmental variable that will hold the token

check_token() → bool

Checks if the token exists in the environmental variables :return bool: True if exists, False otherwise

delete_token() → bool

Deletes the token environmental variable :return bool: Success / Failure

load_token() → bool

Retrieves the token from the environmental variable :return bool: Success / Failure

save_token(force=False) → bool

Saves the token dict in the specified environmental variable :param bool force: Force save even when state has not changed :return bool: Success / Failure

token_env_name

Name of the environment token (Default - O365TOKEN).

   Type: str

class O365.utils.token.FileSystemTokenBackend(token_path=None, token_filename=None)

Bases: BaseTokenBackend

A token backend based on files on the filesystem

__init__(token_path=None, token_filename=None)

Init Backend :param str or Path token_path: the path where to store the token :param str token_filename: the name of the token file

check_token() → bool

Checks if the token exists in the filesystem :return bool: True if exists, False otherwise

delete_token() → bool

Deletes the token file :return bool: Success / Failure

load_token() → bool

Retrieves the token from the File System and stores it in the cache :return bool: Success / Failure

save_token(force=False) → bool

Saves the token cache dict in the specified file Will create the folder if it doesn’t exist :param bool force: Force save even when state has not changed :return bool: Success / Failure

token_path

Path to the token stored in the file system.

   Type: str

class O365.utils.token.FirestoreBackend(client, collection, doc_id, field_name='token')

Bases: BaseTokenBackend

A Google Firestore database backend to store tokens

__init__(client, collection, doc_id, field_name='token')

Init Backend :param firestore.Client client: the firestore Client instance :param str collection: the firestore collection where to store tokens (can be a field_path) :param str doc_id: # the key of the token document. Must be unique per-case. :param str field_name: the name of the field that stores the token in the document

check_token() → bool

Checks if the token exists :return bool: True if it exists on the store

delete_token() → bool

Deletes the token from the store :return bool: Success / Failure

load_token() → bool

Retrieves the token from the store :return bool: Success / Failure

save_token(force=False) → bool

Saves the token dict in the store :param bool force: Force save even when state has not changed :return bool: Success / Failure

client

Fire store client.

   Type: firestore.Client

collection

Fire store collection.

   Type: str

doc_id

Fire store token document key.

   Type: str

doc_ref

Fire store document reference.

   Type: any

field_name

Fire store token field name (Default - token).

   Type: str

class O365.utils.token.MemoryTokenBackend

Bases: BaseTokenBackend

A token backend stored in memory.

load_token() → bool

Abstract method that will retrieve the token data from the backend This MUST be implemented in subclasses

save_token(force=False) → bool

Abstract method that will save the token data into the backend This MUST be implemented in subclasses