EDataServer.OAuth2Service¶

Implementations:
	`EDataServer.OAuth2ServiceGoogle`, `EDataServer.OAuth2ServiceOutlook`

Methods¶

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)
	`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_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_set_to_form(form, name, value)¶

Parameters:	form ({`str`: `str`}) – a `GLib.HashTable` name (`str`) – a property name value (`str` or `None`) – a property value

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:	form ({`str`: `str`}) – a `GLib.HashTable` name (`str`) – a property name value (`str` or `None`) – a property value

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:	source (`EDataServer.Source`) – an `EDataServer.Source` cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
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:

source (EDataServer.Source) – an associated EDataServer.Source
page_title (str) – a web page title
page_uri (str) – a web page URI
page_content (str or None) – a web page content

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.

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.

get_access_token_sync(source, ref_source, ref_source_user_data, cancellable)¶

Parameters:

source (EDataServer.Source) – an EDataServer.Source
ref_source (EDataServer.OAuth2ServiceRefSourceFunc) – an EDataServer.OAuth2ServiceRefSourceFunc function to obtain an EDataServer.Source
ref_source_user_data (object or None) – user data for ref_source
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

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:	source (`EDataServer.Source`) – an associated `EDataServer.Source` uri (`str`) – a URI of the navigation resource
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:	source (`EDataServer.Source`) – an associated `EDataServer.Source` uri_query ({`str`: `str`}) – query for the URI to use

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:	source (`EDataServer.Source`) – an associated `EDataServer.Source` authorization_code (`str`) – authorization code, as returned from `EDataServer.OAuth2Service.extract_authorization_code`() form ({`str`: `str`}) – form parameters to be used in the POST request

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:	source (`EDataServer.Source`) – an associated `EDataServer.Source` message (`Soup.Message`) – a `Soup.Message`

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:	source (`EDataServer.Source`) – an associated `EDataServer.Source` refresh_token (`str`) – a refresh token to be used form ({`str`: `str`}) – form parameters to be used in the POST request

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:	source (`EDataServer.Source`) – an associated `EDataServer.Source` message (`Soup.Message`) – a `Soup.Message`

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:	source (`EDataServer.Source`) – an `EDataServer.Source` authorization_code (`str`) – authorization code provided by the server ref_source (`EDataServer.OAuth2ServiceRefSourceFunc`) – an `EDataServer.OAuth2ServiceRefSourceFunc` function to obtain an `EDataServer.Source` ref_source_user_data (`object` or `None`) – user data for ref_source cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
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:	source (`EDataServer.Source`) – an `EDataServer.Source` refresh_token (`str`) – refresh token as provided by the server ref_source (`EDataServer.OAuth2ServiceRefSourceFunc`) – an `EDataServer.OAuth2ServiceRefSourceFunc` function to obtain an `EDataServer.Source` ref_source_user_data (`object` or `None`) – user data for ref_source cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
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:

source (EDataServer.Source) – an associated EDataServer.Source
page_title (str) – a web page title
page_uri (str) – a web page URI
page_content (str or None) – a web page content

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.

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_get_authentication_policy(source, uri) virtual¶

Parameters:	source (`EDataServer.Source`) – an associated `EDataServer.Source` uri (`str`) – a URI of the navigation resource
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:	source (`EDataServer.Source`) – an associated `EDataServer.Source` uri_query ({`str`: `str`}) – query for the URI to use

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:	source (`EDataServer.Source`) – an associated `EDataServer.Source` authorization_code (`str`) – authorization code, as returned from `EDataServer.OAuth2Service.extract_authorization_code`() form ({`str`: `str`}) – form parameters to be used in the POST request

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:	source (`EDataServer.Source`) – an associated `EDataServer.Source` message (`Soup.Message`) – a `Soup.Message`

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:	source (`EDataServer.Source`) – an associated `EDataServer.Source` refresh_token (`str`) – a refresh token to be used form ({`str`: `str`}) – form parameters to be used in the POST request

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:	source (`EDataServer.Source`) – an associated `EDataServer.Source` message (`Soup.Message`) – a `Soup.Message`

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.