EDataServer.OAuth2Service

g EDataServer.OAuth2Service EDataServer.OAuth2Service GObject.GInterface GObject.GInterface GObject.GInterface->EDataServer.OAuth2Service

Implementations:

EDataServer.OAuth2ServiceGoogle, EDataServer.OAuth2ServiceOutlook, EDataServer.OAuth2ServiceYahoo

Methods

class

util_compile_value (compile_value, out_glob_buff_size)

class

util_extract_from_uri (in_uri)

class

util_set_to_form (form, name, value)

class

util_take_to_form (form, name, value)

can_process (source)

delete_token_sync (source, cancellable)

extract_authorization_code (source, page_title, page_uri, page_content)

extract_error_message (source, page_title, page_uri, page_content)

get_access_token_sync (source, ref_source, ref_source_user_data, cancellable)

get_authentication_policy (source, uri)

get_authentication_uri (source)

get_client_id (source)

get_client_secret (source)

get_display_name ()

get_flags ()

get_name ()

get_redirect_uri (source)

get_refresh_uri (source)

guess_can_process (protocol, hostname)

prepare_authentication_uri_query (source, uri_query)

prepare_get_token_form (source, authorization_code, form)

prepare_get_token_message (source, message)

prepare_refresh_token_form (source, refresh_token, form)

prepare_refresh_token_message (source, message)

receive_and_store_token_sync (source, authorization_code, ref_source, ref_source_user_data, cancellable)

refresh_and_store_token_sync (source, refresh_token, ref_source, ref_source_user_data, cancellable)

Virtual Methods

do_can_process (source)

do_extract_authorization_code (source, page_title, page_uri, page_content)

do_extract_error_message (source, page_title, page_uri, page_content)

do_get_authentication_policy (source, uri)

do_get_authentication_uri (source)

do_get_client_id (source)

do_get_client_secret (source)

do_get_display_name ()

do_get_flags ()

do_get_name ()

do_get_redirect_uri (source)

do_get_refresh_uri (source)

do_guess_can_process (protocol, hostname)

do_prepare_authentication_uri_query (source, uri_query)

do_prepare_get_token_form (source, authorization_code, form)

do_prepare_get_token_message (source, message)

do_prepare_refresh_token_form (source, refresh_token, form)

do_prepare_refresh_token_message (source, message)

Properties

None

Signals

None

Fields

None

Class Details

class EDataServer.OAuth2Service
Bases:

GObject.GInterface

Structure:

EDataServer.OAuth2ServiceInterface

Contains only private data that should be read and manipulated using the functions below.

New in version 3.28.

classmethod util_compile_value(compile_value, out_glob_buff_size)
Parameters:

  • compile_value (str) – a value provided in the compile time

  • out_glob_buff_size (int) – size of the out_glob_buff

Returns:

processed compile_value, saved into *out_glob_buff

out_glob_buff:

a global buffer to store the processed value to

Return type:

(str, out_glob_buff: str)

Processes the compile_value and returns the result, which is stored into the out_glob_buff. The out_glob_buff should be large enough to hold the processed value and it should be a global memory buffer (usually statically allocated) initialized to 0, which is used to short-circuit the call, because the processing is done only if the first element of the out_glob_buff is 0, in all other cases the function immediately returns the out_glob_buff.

New in version 3.46.

classmethod util_extract_from_uri(in_uri)
Parameters:

in_uri (str) – a URI returned from the server

Returns:

True, when any of the non-None out arguments had been populated.

out_authorization_code:

extracted authorization code, can be None

out_error_code:

extracted error code, can be None

out_error_description:

extracted error description, can be None

Return type:

(bool, out_authorization_code: str or None, out_error_code: str or None, out_error_description: str or None)

Extracts either an authorization code from a ‘code’ argument of the in_uri, or an error code from an ‘error’ argument of the in_uri and an error description from the ‘error_description’ argument of the in_uri.

New in version 3.48.

classmethod util_set_to_form(form, name, value)
Parameters:

Sets value for name to form. The form should be the one used in EDataServer.OAuth2Service.prepare_authentication_uri_query(), EDataServer.OAuth2Service.prepare_get_token_form() or EDataServer.OAuth2Service.prepare_refresh_token_form().

If the value is None, then the property named name is removed from the form instead.

New in version 3.28.

classmethod util_take_to_form(form, name, value)
Parameters:

Takes ownership of value and sets it for name to form. The value will be freed with GLib.free(), when no longer needed. The form should be the one used in EDataServer.OAuth2Service.prepare_authentication_uri_query(), EDataServer.OAuth2Service.prepare_get_token_form() or EDataServer.OAuth2Service.prepare_refresh_token_form().

If the value is None, then the property named name is removed from the form instead.

New in version 3.28.

can_process(source)
Parameters:

source (EDataServer.Source) – an EDataServer.Source

Returns:

Whether the self can be used for the given source

Return type:

bool

Checks whether the self can be used with the given source.

The default implementation checks whether the source has an EDataServer.SourceAuthentication extension and when its method matches EDataServer.OAuth2Service.get_name(), then it automatically returns True. Contrary, when the source contains GNOME Online Accounts or Ubuntu Online Accounts extension, then it returns False.

The default implementation is tried always as the first and when it fails, then the descendant’s implementation is called.

New in version 3.28.

delete_token_sync(source, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

whether succeeded

Return type:

bool

Deletes token information for the self and source from the secret store.

New in version 3.28.

extract_authorization_code(source, page_title, page_uri, page_content)
Parameters:
Returns:

whether could recognized successful or failed server response. The out_authorization_code is populated on success too.

out_authorization_code:

the extracted authorization code

Return type:

(bool, out_authorization_code: str)

Tries to extract an authorization code from a web page provided by the server. The function can be called multiple times, whenever the page load is finished. The default implementation uses EDataServer.OAuth2Service.util_extract_from_uri() to get the code from the given page_uri.

There can happen three states: 1) either the self cannot determine the authentication code from the page information, then the False is returned and the out_authorization_code is left untouched; or 2) the server reported a failure, in which case the function returns True and lefts the out_authorization_code untouched; or 3) the self could extract the authentication code from the given arguments, then the function returns True and sets the received authorization code to out_authorization_code.

The page_content is None, unless flags returned by EDataServer.OAuth2Service.get_flags() contain also EDataServer.OAuth2ServiceFlags.EXTRACT_REQUIRES_PAGE_CONTENT.

This method is always called after EDataServer.OAuth2Service.get_authentication_policy().

New in version 3.28.

extract_error_message(source, page_title, page_uri, page_content)
Parameters:
Returns:

whether could recognized failed server response. The out_error_message is populated on success.

out_error_message:

the extracted error message

Return type:

(bool, out_error_message: str)

Tries to extract error message from the server response, return True, when an error message could be found, in which case also sets the out_error_message with it. The default implementation uses EDataServer.OAuth2Service.util_extract_from_uri(), returning either the error description or the error code, when the description is not found.

The out_error_message is expected to be plain text.

New in version 3.48.

get_access_token_sync(source, ref_source, ref_source_user_data, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True, when the returned access token has been set and it’s not expired, False otherwise.

out_access_token:

return location for the access token

out_expires_in:

how many seconds the access token expires in

Return type:

(bool, out_access_token: str, out_expires_in: int)

Reads access token information from the secret store for the source and in case it’s expired it refreshes the token, if possible.

Free the returned out_access_token with GLib.free(), when no longer needed.

New in version 3.28.

get_authentication_policy(source, uri)
Parameters:
Returns:

one of EDataServer.OAuth2ServiceNavigationPolicy

Return type:

EDataServer.OAuth2ServiceNavigationPolicy

Used to decide what to do when the server redirects to the next page. The default implementation always returns EDataServer.OAuth2ServiceNavigationPolicy.ALLOW.

This method is called before EDataServer.OAuth2Service.extract_authorization_code() and can be used to block certain resources or to abort the authentication when the server redirects to an unexpected page (like when user denies authorization in the page).

New in version 3.28.

get_authentication_uri(source)
Parameters:

source (EDataServer.Source) – an associated EDataServer.Source

Returns:

an authentication URI, to be used to obtain the authentication code

Return type:

str

New in version 3.28.

get_client_id(source)
Parameters:

source (EDataServer.Source) – an associated EDataServer.Source

Returns:

application client ID, as provided by the server

Return type:

str

New in version 3.28.

get_client_secret(source)
Parameters:

source (EDataServer.Source) – an associated EDataServer.Source

Returns:

application client secret, as provided by the server, or None

Return type:

str or None

New in version 3.28.

get_display_name()
Returns:

the display name of the self

Return type:

str

Returns a human readable name of the service. This is similar to EDataServer.OAuth2Service.get_name(), except this string should be localized, because it will be used in user-visible strings.

New in version 3.28.

get_flags()
Returns:

bit-or of EDataServer.OAuth2ServiceFlags for the self. The default implementation returns EDataServer.OAuth2ServiceFlags.NONE.

Return type:

int

New in version 3.28.

get_name()
Returns:

the name of the self

Return type:

str

Returns a unique name of the service. It can be named for example by the server or the company from which it receives the OAuth2 token and where it refreshes it, like “Company” for login.company.com.

New in version 3.28.

get_redirect_uri(source)
Parameters:

source (EDataServer.Source) – an associated EDataServer.Source

Returns:

The redirect_uri to use, or None for none

Return type:

str or None

Returns a value for the “redirect_uri” keys in the authenticate and get_token operations. The default implementation returns “urn:ietf:wg:oauth:2.0:oob”.

New in version 3.28.

get_refresh_uri(source)
Parameters:

source (EDataServer.Source) – an associated EDataServer.Source

Returns:

a URI to be used to refresh the authentication token

Return type:

str

New in version 3.28.

guess_can_process(protocol, hostname)
Parameters:

  • protocol (str or None) – a protocol to search the service for, like “imap”, or None

  • hostname (str or None) – a host name to search the service for, like “server.example.com”, or None

Returns:

Whether the self can be used for the given arguments

Return type:

bool

Checks whether the self can be used with the given protocol and/or hostname. Any of protocol and hostname can be None, but not both. It’s up to each implementer to decide, which of the arguments are important and whether all or only any of them can be required.

The function is meant to check whether the self can be offered for example when configuring a new account. The real usage is determined by EDataServer.OAuth2Service.can_process().

The default implementation consults org.gnome.evolution-data-server.oauth2-services-hint Gio.Settings key against given hostname. See its description for more information.

The default implementation is tried always as the first and when it fails, then the descendant’s implementation is called.

New in version 3.28.

prepare_authentication_uri_query(source, uri_query)
Parameters:

The self can change what arguments are passed in the authentication URI in this method. The default implementation sets some values too, namely “response_type”, “client_id”, “redirect_uri” and “login_hint”, if available in the source. These parameters are always provided, even when the interface implementer overrides this method.

The uri_query hash table expects both key and value to be newly allocated strings, which will be freed together with the hash table or when the key is replaced.

New in version 3.28.

prepare_get_token_form(source, authorization_code, form)
Parameters:

Sets additional form parameters to be used in the POST request when requesting access token after successfully obtained authorization code. The default implementation sets some values too, namely “code”, “client_id”, “client_secret”, “redirect_uri” and “grant_type”. These parameters are always provided, even when the interface implementer overrides this method.

The form hash table expects both key and value to be newly allocated strings, which will be freed together with the hash table or when the key is replaced.

New in version 3.28.

prepare_get_token_message(source, message)
Parameters:

The self can change the message before it’s sent to the EDataServer.OAuth2Service.get_authentication_uri(), with POST data being provided by EDataServer.OAuth2Service.prepare_get_token_form(). The default implementation does nothing with the message.

New in version 3.28.

prepare_refresh_token_form(source, refresh_token, form)
Parameters:

Sets additional form parameters to be used in the POST request when requesting to refresh an access token. The default implementation sets some values too, namely “refresh_token”, “client_id”, “client_secret” and “grant_type”. These parameters are always provided, even when the interface implementer overrides this method.

The form hash table expects both key and value to be newly allocated strings, which will be freed together with the hash table or when the key is replaced.

New in version 3.28.

prepare_refresh_token_message(source, message)
Parameters:

The self can change the message before it’s sent to the EDataServer.OAuth2Service.get_refresh_uri(), with POST data being provided by EDataServer.OAuth2Service.prepare_refresh_token_form(). The default implementation does nothing with the message.

New in version 3.28.

receive_and_store_token_sync(source, authorization_code, ref_source, ref_source_user_data, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

whether succeeded

Return type:

bool

Queries self at EDataServer.OAuth2Service.get_refresh_uri() with a request to obtain a new access token, associated with the given authorization_code and stores it into the secret store on success.

New in version 3.28.

refresh_and_store_token_sync(source, refresh_token, ref_source, ref_source_user_data, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

whether succeeded

Return type:

bool

Queries self at EDataServer.OAuth2Service.get_refresh_uri() with a request to refresh existing access token with provided refresh_token and stores it into the secret store on success.

New in version 3.28.

do_can_process(source) virtual
Parameters:

source (EDataServer.Source) – an EDataServer.Source

Returns:

Whether the service can be used for the given source

Return type:

bool

Checks whether the service can be used with the given source.

The default implementation checks whether the source has an EDataServer.SourceAuthentication extension and when its method matches EDataServer.OAuth2Service.get_name(), then it automatically returns True. Contrary, when the source contains GNOME Online Accounts or Ubuntu Online Accounts extension, then it returns False.

The default implementation is tried always as the first and when it fails, then the descendant’s implementation is called.

New in version 3.28.

do_extract_authorization_code(source, page_title, page_uri, page_content) virtual
Parameters:
Returns:

whether could recognized successful or failed server response. The out_authorization_code is populated on success too.

out_authorization_code:

the extracted authorization code

Return type:

(bool, out_authorization_code: str)

Tries to extract an authorization code from a web page provided by the server. The function can be called multiple times, whenever the page load is finished. The default implementation uses EDataServer.OAuth2Service.util_extract_from_uri() to get the code from the given page_uri.

There can happen three states: 1) either the service cannot determine the authentication code from the page information, then the False is returned and the out_authorization_code is left untouched; or 2) the server reported a failure, in which case the function returns True and lefts the out_authorization_code untouched; or 3) the service could extract the authentication code from the given arguments, then the function returns True and sets the received authorization code to out_authorization_code.

The page_content is None, unless flags returned by EDataServer.OAuth2Service.get_flags() contain also EDataServer.OAuth2ServiceFlags.EXTRACT_REQUIRES_PAGE_CONTENT.

This method is always called after EDataServer.OAuth2Service.get_authentication_policy().

New in version 3.28.

do_extract_error_message(source, page_title, page_uri, page_content) virtual
Parameters:
Returns:

whether could recognized failed server response. The out_error_message is populated on success.

out_error_message:

the extracted error message

Return type:

(bool, out_error_message: str)

Tries to extract error message from the server response, return True, when an error message could be found, in which case also sets the out_error_message with it. The default implementation uses EDataServer.OAuth2Service.util_extract_from_uri(), returning either the error description or the error code, when the description is not found.

The out_error_message is expected to be plain text.

New in version 3.48.

do_get_authentication_policy(source, uri) virtual
Parameters:
Returns:

one of EDataServer.OAuth2ServiceNavigationPolicy

Return type:

EDataServer.OAuth2ServiceNavigationPolicy

Used to decide what to do when the server redirects to the next page. The default implementation always returns EDataServer.OAuth2ServiceNavigationPolicy.ALLOW.

This method is called before EDataServer.OAuth2Service.extract_authorization_code() and can be used to block certain resources or to abort the authentication when the server redirects to an unexpected page (like when user denies authorization in the page).

New in version 3.28.

do_get_authentication_uri(source) virtual
Parameters:

source (EDataServer.Source) – an associated EDataServer.Source

Returns:

an authentication URI, to be used to obtain the authentication code

Return type:

str

New in version 3.28.

do_get_client_id(source) virtual
Parameters:

source (EDataServer.Source) – an associated EDataServer.Source

Returns:

application client ID, as provided by the server

Return type:

str

New in version 3.28.

do_get_client_secret(source) virtual
Parameters:

source (EDataServer.Source) – an associated EDataServer.Source

Returns:

application client secret, as provided by the server, or None

Return type:

str or None

New in version 3.28.

do_get_display_name() virtual
Returns:

the display name of the service

Return type:

str

Returns a human readable name of the service. This is similar to EDataServer.OAuth2Service.get_name(), except this string should be localized, because it will be used in user-visible strings.

New in version 3.28.

do_get_flags() virtual
Returns:

bit-or of EDataServer.OAuth2ServiceFlags for the service. The default implementation returns EDataServer.OAuth2ServiceFlags.NONE.

Return type:

int

New in version 3.28.

do_get_name() virtual
Returns:

the name of the service

Return type:

str

Returns a unique name of the service. It can be named for example by the server or the company from which it receives the OAuth2 token and where it refreshes it, like “Company” for login.company.com.

New in version 3.28.

do_get_redirect_uri(source) virtual
Parameters:

source (EDataServer.Source) – an associated EDataServer.Source

Returns:

The redirect_uri to use, or None for none

Return type:

str or None

Returns a value for the “redirect_uri” keys in the authenticate and get_token operations. The default implementation returns “urn:ietf:wg:oauth:2.0:oob”.

New in version 3.28.

do_get_refresh_uri(source) virtual
Parameters:

source (EDataServer.Source) – an associated EDataServer.Source

Returns:

a URI to be used to refresh the authentication token

Return type:

str

New in version 3.28.

do_guess_can_process(protocol, hostname) virtual
Parameters:

  • protocol (str or None) – a protocol to search the service for, like “imap”, or None

  • hostname (str or None) – a host name to search the service for, like “server.example.com”, or None

Returns:

Whether the service can be used for the given arguments

Return type:

bool

Checks whether the service can be used with the given protocol and/or hostname. Any of protocol and hostname can be None, but not both. It’s up to each implementer to decide, which of the arguments are important and whether all or only any of them can be required.

The function is meant to check whether the service can be offered for example when configuring a new account. The real usage is determined by EDataServer.OAuth2Service.can_process().

The default implementation consults org.gnome.evolution-data-server.oauth2-services-hint Gio.Settings key against given hostname. See its description for more information.

The default implementation is tried always as the first and when it fails, then the descendant’s implementation is called.

New in version 3.28.

do_prepare_authentication_uri_query(source, uri_query) virtual
Parameters:

The service can change what arguments are passed in the authentication URI in this method. The default implementation sets some values too, namely “response_type”, “client_id”, “redirect_uri” and “login_hint”, if available in the source. These parameters are always provided, even when the interface implementer overrides this method.

The uri_query hash table expects both key and value to be newly allocated strings, which will be freed together with the hash table or when the key is replaced.

New in version 3.28.

do_prepare_get_token_form(source, authorization_code, form) virtual
Parameters:

Sets additional form parameters to be used in the POST request when requesting access token after successfully obtained authorization code. The default implementation sets some values too, namely “code”, “client_id”, “client_secret”, “redirect_uri” and “grant_type”. These parameters are always provided, even when the interface implementer overrides this method.

The form hash table expects both key and value to be newly allocated strings, which will be freed together with the hash table or when the key is replaced.

New in version 3.28.

do_prepare_get_token_message(source, message) virtual
Parameters:

The service can change the message before it’s sent to the EDataServer.OAuth2Service.get_authentication_uri(), with POST data being provided by EDataServer.OAuth2Service.prepare_get_token_form(). The default implementation does nothing with the message.

New in version 3.28.

do_prepare_refresh_token_form(source, refresh_token, form) virtual
Parameters:

Sets additional form parameters to be used in the POST request when requesting to refresh an access token. The default implementation sets some values too, namely “refresh_token”, “client_id”, “client_secret” and “grant_type”. These parameters are always provided, even when the interface implementer overrides this method.

The form hash table expects both key and value to be newly allocated strings, which will be freed together with the hash table or when the key is replaced.

New in version 3.28.

do_prepare_refresh_token_message(source, message) virtual
Parameters:

The service can change the message before it’s sent to the EDataServer.OAuth2Service.get_refresh_uri(), with POST data being provided by EDataServer.OAuth2Service.prepare_refresh_token_form(). The default implementation does nothing with the message.

New in version 3.28.