EDataServer.OAuth2Service

g EDataServer.OAuth2Service EDataServer.OAuth2Service GObject.GInterface GObject.GInterface GObject.GInterface->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:

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.

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:
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.

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:
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.