Documentation

Ce document en français.

The use of this software subjects you to our Terms Of Use and Data Protection Policy.

version 1.3.9

Introduction:

OAuth2OOo is part of a Suite of LibreOffice and/or OpenOffice extensions allowing to offer you innovative services in these office suites.

This extension is the implementation of the OAuth 2.0 protocol. Protocol allowing you to obtain your consent so that an application can access your data present at the GAFA.

It allows executing HTTP requests in BASIC and provides the following macros as an example:

• HTTPGetRequest
• HTTPPostRequest
• ChatGPTRequest
• GoogleAPIRequest
• GraphAPIRequest

If you open a document beforehand, you can launch them by:
Tools -> Macros -> Run Macro… -> My Macros -> OAuth2OOo -> macro-name -> Main -> Run

It also allows grabbing internet data in a Calc sheet. See the following Calc files as an example:

• LDLC MacBook Pro.ods
• LDLC Asus Zenbook.ods

And finally, it allows you to drive Firefox using a Calc file (or any other browser supported by Selenium). See the following files:

• Page Jaunes (Windows).ods
• Page Jaunes (Linux).ods

Being free software I encourage you:

• To duplicate its source code.
• To make changes, corrections, improvements.
• To open issue if needed.

In short, to participate in the development of this extension. Because it is together that we can make Free Software smarter.

---

Requirement:

In order to take advantage of the latest versions of the Python libraries used in OAuth2OOo, version 2 of Python has been abandoned in favor of Python 3.8 minimum.
This means that OAuth2OOo no longer supports OpenOffice and LibreOffice 6.x on Windows since version 1.1.0. I can only advise you to migrate to LibreOffice 7.x.

The requirement depend on the platform (architecture) on which the extension is installed:

• If you are on Windows (win32 or win_amd64) you must use LibreOffice version 7.x minimum.

• If you are on Linux (x86_64) with a Python version from 3.8 to 3.12 you must use LibreOffice version 6.x or higher (LibreOffice version 7.x is strongly recommended).

• For all other platforms / architectures (Linux, macOS… / aarch64, arm64…) or Python version, you need:

  • Make sure your version of Python is 3.8 minimum.
  • Download the file requirements.txt.
  • Install using pip, the Python packages necessary for the extension with the command:
    pip install requirements.txt
  • Install the extension under LibreOffice version 6.x or higher.

On Linux and macOS the packages used by the extension, if already installed, may come from the system and therefore may not be up to date.
To ensure that your Python packages are up to date it is recommended to use the System Info option in the extension Options accessible by:
Tools -> Options -> Internet -> OAuth2 protocol -> View log -> System Info
If outdated packages appear, you can update them with the command:
sudo -i pip3 install --upgrade <package-name>

For more information see: What has been done for version 1.3.0.

If you want to drive Firefox in Calc on Ubuntu then you need to reinstall Firefox from the Mozilla PPA.
To install the Mozilla PPA please type the command:
sudo add-apt-repository ppa:mozillateam/ppa

---

Installation:

It seems important that the file was not renamed when it was downloaded.
If necessary, rename it before installing it.

• Install OAuth2OOo.oxt extension

Restart LibreOffice after installation.
Be careful, restarting LibreOffice may not be enough.

• On Windows to ensure that LibreOffice restarts correctly, use Windows Task Manager to verify that no LibreOffice services are visible after LibreOffice shuts down (and kill it if so).
• Under Linux or macOS you can also ensure that LibreOffice restarts correctly, by launching it from a terminal with the command soffice and using the key combination Ctrl + C if after stopping LibreOffice, the terminal is not active (no command prompt).

---

Use:

This extension is not made to be used alone, but provide OAuth2 service to other LibreOffice / OpenOffice extensions.
Here’s how we use its API:

Create OAuth2 service:

identifier = “io.github.prrvchr.OAuth2OOo.OAuth2Service”
service = ctx.ServiceManager.createInstanceWithContext(identifier, ctx)

Initialize Session or at least Url:

• Initialize Session:

initialized = service.initializeSession(registered_url, user_account)

The return value: initialized is True if user_account is already authorized for registered_url.

• Initialize Url:

initialized = service.initializeUrl(registered_url)

The return value: initialized is True if registered_url was successfully found in the OAuth2 service configuration.

Get the access token:

format = ‘Bearer %s’
token = service.getToken(format)

---

Uno OAuth2.0 API for LibreOffice.

The OAuth2 protocol allows access to server resources, after accepting the connection authorization, by exchanging tokens.

The revocation takes place in the management of the applications associated with your account.

No more password is stored in LibreOffice.

---

Has been tested with:

• LibreOffice 7.3.7.2 - Lubuntu 22.04 - Python version 3.10.12

• LibreOffice 7.5.4.2(x86) - Windows 10 - Python version 3.8.16 (under Lubuntu 22.04 / VirtualBox 6.1.38)

• LibreOffice 7.4.3.2(x64) - Windows 10(x64) - Python version 3.8.15 (under Lubuntu 22.04 / VirtualBox 6.1.38)

• LibreOffice 24.8.0.3 (x86_64) - Windows 10(x64) - Python version 3.9.19 (under Lubuntu 22.04 / VirtualBox 6.1.38)

• Does not work with OpenOffice see bug 128569. Having no solution, I encourage you to install LibreOffice.

I encourage you in case of problem
to create an issue
I will try to solve it

---

Historical:

What has been done for version 0.0.5:

• Writing of a new XWizard interface in order to replace the Wizard service which became defective with version 6.4.x and 7.x of LibreOffice (see bug 132110).

  This new interface also fixes bug 132661 and bug 132666 and allows access to versions 6.4.x and 7.x of LibreOffice…

  In addition this new XWizard adds new functionality such as:

  • Automatic resizing of the Wizard to the dimensions of the first displayed page.
  • Automatic move to page X on opening if possible.

• Fixed an issue with tokens without expiration (as used by Dropbox) on testing their validity…

• Many other fix…

What has been done for version 0.0.6:

• Rewrite of the OAuth2 wizard trying to follow the MVA model as best as possible. This wizard is made up of 5 pages inheriting from the UNO XWizardPage interface:

  • Page 1: Adapter and View
  • Page 2: Adapter and View
  • Page 3: Adapter and View
  • Page 4: Adapter and View
  • Page 5: Adapter and View

• Rewrite of the three UNO services provided by the OAuth2OOo extension in three separate files:

  • The OAuth2Service service implementing the interface described in the XOAuth2Service IDL file.
  • The OAuth2Dispacher service implementing the UNO interface XDispatchProvider.
  • The OAuth2Handler service implementing the UNO interface XInteractionHandler2.

• Rewrite of the options dialog accessible by Tools -> Options -> Internet -> Protocol OAuth2. This dialog is composed of two windows:

  • The logging window: Adapter and View.
  • The OAuth2OOo extension configuration options window: Adapter and View.

• Rewrite a single data model: OAuth2Model managing wizard, services and options dialog.

• Google loopback flow error has been fixed. See Issue #10

• Use for Dropbox their new OAuth2 API with expirable tokens.

• Many other fix…

What has been done for version 1.0.0:

• Porting Python API Requests to LibreOffice / OpenOffice UNO API. Two UNO interfaces are accessible:

  • HTTP request parameters: com.sun.star.rest.XRequestParameter.idl
  • The response to the HTTP request: com.sun.star.rest.XRequestResponse.idl

  The XRequestParameter interface supports sync token handling as well as HTTP request paging, as used in the HTTP Rest APIs

• Uploading and downloading files is possible thanks to the methods or properties:

  • XOAuth2Service.download() allowing resumable file download.
  • XOAuth2Service.upload() allowing resumable file upload.
  • XOAuth2Service.getInputStream() to get an input stream.
  • XRequestParameter.DataSink to set an input stream.
  • XRequestResponse.getInputStream() to get an input stream.

• Porting Java API javax.json to LibreOffice / OpenOffice UNO API as defined in idl files: com.sun.star.json.*

  • A factory of JSON structures is accessible via the getJsonBuilder() interface of XRequestParameter.
  • A Json parser is returned by the getJson() interface of XRequestResponse.

This makes HTTP requests using JSON easily usable in the BASIC language of LibreOffice.

What has been done for version 1.0.1:

• Writing of 15 functions in Calc AddIns as described in the following files:

  • The file OAuth2Plugin.idl which declares new interfaces to UNO.
  • The file CalcAddIns.xcu which makes available these new interfaces in the list of Calc functions.
  • The file OAuth2Plugin.py which is the implementation of the UNO service com.sun.star.auth.Oauth2Plugin providing these new interfaces.
  • The file plugin.py which is the library implementing the interfaces of this new UNO service.

• These 4 new files give access to 15 new Calc formulas which are:

  • GETHTTPBOBY(URL,METHOD,ENCODING,PARAMETERS)
  • PARSEHTML(DATA,PATH,BASEURL)
  • PARSEXML(DATA,PATH,BASEURL)
  • PARSEJSON(DATA,PATH)
  • JAVASCRIPT2XML(DATA,PATH)
  • XML2JSON(DATA,PATH)
  • JAVASCRIPT2JSON(DATA,PATH)
  • DUBLINCORE2JSON(DATA,BASEURL)
  • JSONLD2JSON(DATA,BASEURL)
  • MICRODATA2JSON(DATA,BASEURL)
  • MICROFORMAT2JSON(DATA,BASEURL)
  • OPENGRAPH2JSON(DATA,BASEURL)
  • RDFA2JSON(DATA,BASEURL)
  • FLATTENJSON(DATA,TYPENAME,PATH,SEPARATOR)
  • SPLITJSON(DATA,TYPENAME,PATH,SEPARATOR)

What has been done for version 1.1.0:

• End of support for Python 2.x and therefore for OpenOffice.

• Integration of Selenium version 4.10 in the extension in order to make LibreOffice able to control a browser via Calc formulas inserted in a spreadsheet.

• Use of webdriver_manager version 3.8.6 to automate the installation of the browser’s WebDriver.

• Creation of 5 Calc formulas allowing the piloting of the browser:

  • BROWSEROPEN(BROWSER,PATH,INIT,OPTIONS)
  • BROWSERCLICK(SESSION,BY,PATH,URL,INIT,WAIT)
  • BROWSERFIELD(SESSION,BY,PATH,VALUE,URL,INIT,WAIT)
  • BROWSERFORM(SESSION,FORM,URL,INIT,WAIT)
  • BROWSERCONTENT(SESSION,URL,ENCODING)

• Creation of a Calc formula allowing HTTP Basic Auth authentication for HTTP requests:

  • HTTPAUTH(NAME,PASSWORD)

• Calc formula GETHTTPBOBY has been renamed to HTTPCONTENT.

What has been done for version 1.1.1:

• Fixed an issue in the implementation of the com.sun.star.rest.XRequestParameter interface not allowing to create empty JSON objects (ie: “Object”: {} ) as requested by the Microsoft Graph API.

What has been done for version 1.1.2:

• Modification of the idl files: XRequestParameter.idl and XRequestResponse.idl and the underlying python implementations: requestparameter.py and requestresponse.py in order to make it possible POST requests with application/x-www-form-urlencoded encoding. See issue #13.

• 3 macros in BASIC: ChatGPTRequest, HTTPGetRequest and HTTPPostRequest are available in: Tools -> Macros -> Run Macros… -> My Macros -> OAuth2OOo. Be careful, these macros will not work if no document is open (I don’t know why?)…

• From now on, with each push, a workflow perform a scan on the code with Fluid Attacks. This has been implemented to follow the Cloud Application Security Assessment (CASA) and meet the requirements for revalidation of the OAuth2OOo extension with Google.

• For the same reasons, the Data Protection Policy has been modified in order to specify the Nature and scope rights over your data.

What has been done for version 1.2.0:

• There are now two methods of creating the OAuth2Service service which are:
  • create() without parameter, returns an instance of the service.
  • createWithOAuth2([in] string sUrl, [in] string sUser) with an Url and the user’s address, returns an instance of the service with the OAuth2 protocol.
    In its second form, the OAuth2 authorization Wizard will launch automatically if the scope of the Url rights has not yet been granted by the user (ie: first connection).
    If this is the case and the Wizard is aborted then a null value will be returned instead of the requested service.
• Two BASIC macros: GoogleAPIRequest and GraphAPIRequest allow you to make HTTP requests on the Google Contact and Microsoft Graph APIs.
  The OAuth2 protocol essential for the use of these APIs is integrated automatically and transparently into HTTP requests. You won’t have to worry about it.

What has been done for version 1.2.1:

• Added a new method isAuthorized() to the XOAuth2Service interface supported by the OAuth2Service service. This method allows you to launch the OAuth2 configuration Wizard if the user is not authorized.

What has been done for version 1.2.2:

• Fixed an error when refreshing OAuth2 tokens.

What has been done for version 1.2.3:

• Fixed an error on isAuthorized() on OAuth2Service.

What has been done for version 1.2.4:

• Updated embedded python packages.

What has been done for version 1.3.0:

• Using the new version 3.6.2 of pyRdfa3.
• All Python packages necessary for the extension are now recorded in a requirements.txt file following PEP 508.
• Now if you are not on Windows then the Python packages necessary for the extension can be easily installed with the command:
  sudo -i pip3 install requirements.txt
• Simplification of the Requirement section.
• Many fixes…

What has been done for version 1.3.1:

• Fixed the Headers property in the implementation of the UNO interface XRequestResponse allowing to obtain the headers of an HTTP response.
• Many fixes…

What has been done for version 1.3.2:

• Integration of Python 3.8 binaries for Linux x86_64 and Darwin x86_64, in order to be compatible with the version of LibreOffice 24.2.x for Linux, for the lxml, ijson, cffi and charset-normalizer packages.
• Opening of issue #159988 for the impossibility of importing Python libraries containing binary files with LibreOffice 24.2.x under Linux.

What has been done for version 1.3.3:

• Implemented a workaround for issue #159988 which may take time to resolve.

What has been done for version 1.3.4:

• Updated the Python Idna package to version 3.7 in order to respond to the security vulnerability alert.
• Some fixes…

What has been done for version 1.3.5:

• Updated the Python tqdm package to version 4.66.4 in order to respond to the security vulnerability alert.
• Updated the Python Requests package to version 2.32.3 in order to respond to the security vulnerability alert.
• In order to avoid any conflict with the Python oauth2 package, the folder put in the python path by the extension has been renamed to oauth20. This should also resolve issue #15.
• Some fixes…

What has been done for version 1.3.6:

• Updated the Python beautifulsoup package to version 4.12.3.
• Updated the Python certifi package to version 2024.7.4.
• Added binaries for Python/Manylinux versions 3.9, 3.11 and 3.12 for package Python cffi version 1.16.0.
• Updated the Python charset-normalizer package to version 3.3.2.
• Updated the Python exceptiongroup package to version 1.2.2.
• Updated the Python extruct package to version 0.17.0.
• Updated the Python html-text package to version 0.6.2.
• Updated the Python ijson package to version 3.3.0.
• Updated the Python jsonpath_ng package to version 1.6.1.
• Updated the Python lxml package to version 5.2.2.
• Added package Python lxml-html-clean version 0.2.0.
• Updated the Python packaging package to version 24.1.
• Updated the Python prasel package to version 1.9.1.
• Updated the Python pycparser package to version 2.22.
• Updated the Python pyparsing package to version 3.1.2.
• Updated the Python pyRdfa3 package to version 3.6.4.
• Updated the Python python-dotenv package to version 1.0.1.
• Updated the Python selenium package to version 4.23.1.
• Updated the Python setuptools package to version 72.1.0 in order to respond to the security vulnerability alert.
• Updated the Python sniffio package to version 1.3.1.
• Updated the Python trio package to version 0.26.0.
• Added package Python typing-extensions version 4.12.2.
• Updated the Python urllib3 package to version 2.2.2.
• Updated the Python validators package to version 0.33.2.
• Updated the Python w3lib package to version 2.2.1.
• Updated the Python webdriver-manager package to version 4.0.2.
• Added package Python websocket-client version 1.8.0.

Updating all these Python packages should make it possible to use Python 3.8, 3.9, 3.10, 3.11 and 3.12 under ManyLinux x86_64 architecture.
For win32 and win_amd64 architectures, only Python version 3.8 is supported. This means that since Python is embedded into LibreOffice for these architectures, only LibreOffice versions 7.x and 24.x are supported.
If your architecture is not yet supported by OAuth2OOo (Mac OSX, arm…), I advise you to open an issue so that I can add the missing binaries.

What has been done for version 1.3.7:

• Updated the Python attrs package to version 24.2.0.
• Updated the Python cffi package to version 1.17.0.
• Updated the Python idna package to version 3.8.
• Updated the Python lxml package to version 5.3.0.
• Updated the Python pyparsing package to version 3.1.4.
• Updated the Python setuptools package to version 73.0.1.
• Updated the Python soupsieve package to version 2.6.
• Updated the Python tqdm package to version 4.66.5.
• Updated the Python trio package to version 0.26.2.
• Logging accessible in extension options now displays correctly on Windows.
• Changes to extension options that require a restart of LibreOffice will result in a message being displayed.
• To work with LibreOffice 24.8.x and Windows (32 and 64 bit), added binaries, for Python version 3.9 and win32 or win_adm64 architectures, to all Python packages included in the extension.

What has been done for version 1.3.8:

• Modification of the extension options accessible via: Tools -> Options… -> Internet -> OAuth2 Protocol in order to comply with the new graphic charter.

What has been done for version 1.3.9:

• Added a new fromJson() method to the XRequestParameter interface to make it easier to execute an HTTP request from parameters coming from LibreOffice configuration files (ie: xcu/xcs XML files).
• Preparation for the migration of the scopes of rights specific to connections to Google servers.
• Some fixes…

What has been done for version 1.4.0:

• All data needed for OAuth2 authorization code flow management is now stored in LibreOffice configuration file Options.xcu.
• Yahoo’s OAuth2 API has been integrated and will be available in the eMailerOOo extension soon.
• It is now possible to have an OAuth2 redirect uri (ie: redirect_uri) in https mode as required when using the Yahoo API. Thanks to JavaScript and Github.
• The TCP/IP port allowing the reception of the GAFA authorization code is now chosen randomly among the free ports (ie: no more conflict problems).

What remains to be done for version 1.4.0:

• Add new language for internationalization…

• Anything welcome…