maestral.oauth

This module is responsible for authorization and token store in the system keyring.

class maestral.oauth.OAuth2Session(config_name, app_key='2jmbq42w7vof78h')[source]

Bases: object

Provides Dropbox OAuth flow and key store interface

OAuth2Session provides OAuth 2 login and token store in the preferred system keyring. To authenticate with Dropbox, run get_auth_url() first and direct the user to visit that URL and retrieve an auth token. Verify the provided auth token with verify_auth_token() and save it in the system keyring together with the corresponding Dropbox ID by calling save_creds(). Supported keyring backends are, in order of preference:

macOS Keychain

Any keyring implementing the SecretService Dbus specification

KWallet

Plain text storage

When the auth flow is completed, a short-lived access token and a long-lived refresh token are generated. They can be accessed through the properties access_token and refresh_token. Only the long-lived refresh token will be saved in the system keychain for future sessions, the Dropbox SDK will use it to generate short-lived access tokens as needed.

If the auth flow was previously completed before Dropbox migrated to short-lived tokens, the token_access_type will be ‘legacy’ and only a long-lived access token will be available.

Note

Once the token has been stored with a keyring backend, that backend will be saved in the config file and remembered until the user unlinks the account. This module will therefore never switch keyring backends while linked.

Warning

Unlike macOS Keychain, Gnome Keyring and KWallet do not support app-specific access to passwords. If the user unlocks those keyrings, we and any other application in the same user session get access to all saved passwords.

Parameters

config_name (str) – Name of maestral config.
app_key (str) – Public key of the app, as registered with Dropbox. Used for the PKCE OAuth 2.0 flow.

Return type

None

Success = 0: Exit code for successful auth.

InvalidToken = 1: Exit code for invalid token.

ConnectionFailed = 2: Exit code for connection errors.

default_token_access_type = 'offline'

property keyring: keyring.backend.KeyringBackend: The keyring backend currently being used to store auth tokens. If set to None, the best viable backend will be determined automatically.

property linked: bool: Whether we have full auth credentials (read only).

property account_id: Optional[str]: The account ID (read only). This call may block until the keyring is unlocked.

property token_access_type: Optional[str]: The type of access token (read only). If ‘legacy’, we have a long-lived access token. If ‘offline’, we have a short-lived access token with an expiry time and a long-lived refresh token to generate new access tokens. This call may block until the keyring is unlocked.

property access_token: Optional[str]: The access token (read only). This will always be set for a ‘legacy’ token. For an ‘offline’ token, this will only be set if we completed the auth flow in the current session. In case of an ‘offline’ token, use the refresh token to retrieve a short-lived access token through the Dropbox API instead. This call may block until the keyring is unlocked.

property refresh_token: Optional[str]: The refresh token (read only). This will only be set for an ‘offline’ token. This call may block until the keyring is unlocked.

property access_token_expiration: Optional[datetime.datetime]: The expiry time for the short-lived access token (read only). This will only be set for an ‘offline’ token and if we completed the flow during the current session.

load_token()[source]

Loads auth token from system keyring. This will be called automatically when accessing any of the properties linked, access_token, refresh_token or token_access_type. This call may block until the keyring is unlocked.

Raises: KeyringAccessError – if the system keyring is locked or otherwise cannot be accessed (for example if the app bundle signature has been invalidated).
Return type: None

get_auth_url()[source]

Retrieves an auth URL to start the OAuth2 implicit grant flow.

Returns: Dropbox auth URL.
Return type: str

verify_auth_token(code)[source]

If the user approves the app, they will be presented with a single usage “authorization code”. Have the user copy/paste that authorization code into the app and then call this method to exchange it for a long-lived auth token.

Parameters: code (str) – Ephemeral auth code.
Returns: Success, InvalidToken, or ConnectionFailed.
Return type: int

save_creds()[source]

Saves the auth token to system keyring. Falls back to plain text storage if the user denies access to keyring. This should be called after verify_auth_token() returned successfully.

Return type: None

delete_creds()[source]

Deletes auth token from system keyring.

Raises: KeyringAccessError – if the system keyring is locked or otherwise cannot be accessed (for example if the app bundle signature has been invalidated).
Return type: None