HowTo Restore a Google Drive backup file in OPNsense

A description on how to use Google Drive backup feature in OPNsense can be found here:
https://github.com/opnsense/docs/blob/master/source/manual/how-tos/cloud_backup.rst

But this is a rather complicated process, so read carefully!

You probably already know that you need a P12 key to store the backup files on Google Drive. Why is that?

The P12 key you created for use with Google Drive backups in OPNsense plays an important role in the authentication process between OPNsense and Google’s API. Here's exactly what the P12 key does during the backup and restore process:

---

1. What does the P12 key do?

The P12 key (a so-called PKCS#12 file) contains a private key that OPNsense uses to cryptographically authenticate itself as a service account to Google. It is linked to a Google Cloud service account that has access to your Google Drive.

In short:

1. Authentication
   When creating a backup, OPNsense connects to the Google Drive API.

2. Signing a JWT (JSON Web Token)
   OPNsense generates a specially formatted token (JWT) and signs it with the private key from the P12 file.

3. Token exchange with Google
   The signed JWT is sent to Google’s OAuth 2.0 token endpoint, and in return, OPNsense receives an access token.

4. Access to Google Drive
   With that access token, OPNsense can upload or download files from Google Drive on behalf of the service account.

---

Why is this necessary?

Unlike user-based authentication (which uses a browser and interactive OAuth consent), this is a server-to-server authentication method. That’s ideal because OPNsense needs to perform automated backups without requiring manual login or user consent each time.

---

What happens during a restore?

During a restore:

1. OPNsense follows the same authentication process to access Google Drive.

2. It retrieves the list of XML backup files.

3. The user selects a file, and OPNsense downloads it via the API (authorized through the same token process).

---

Important security note

• Treat the P12 file as a secret.
  Anyone with access to this key — and who knows the associated service account — can access your backup files.

• Make sure only OPNsense (and you as the administrator) have access to this file.

2. How to restore a backup from Google Drive when using Linux?

With kio-Gdrive installed in Dolphin is not working because Google blocks this

That’s a known limitation of kio-gdrive in combination with Google’s stricter security policies. Google now blocks applications that are not verified or have not gone through OAuth validation, which applies to many open-source or locally installed apps like kio-gdrive.

Why does Google block kio-gdrive?

Google sees kio-gdrive as an "unverified app" requesting access to sensitive scopes (such as full access to your Drive). Because of that, Google refuses to complete the OAuth flow.

Solutions

1. Use rclone instead of kio-gdrive (recommended)

As mentioned earlier, rclone is the most robust and Google-compliant way to access Google Drive locally without running into OAuth issues. Rclone is recognized by Google, uses approved scopes, and just works.

➡️ Advantage: Stable and compatible with service accounts.

Installeren en instellen

Install rclone:

sudo apt install rclone

Configure rclone for Google Drive:

rclone config

Choose:

• n to create a new remote configuration.

• Enter a name, for example: gdrive.

• Choose option 13 for Google Drive.

• Leave Client ID and Client Secret blank (or enter the values from your Google Cloud Console if you have them).

• Select "service_account_file" when prompted and provide the path to your .p12 or .json file.

   

  ⚠️ Note: rclone works best with JSON service account keys rather than P12.
  If you only have a P12 key, you may first need to manually generate a JSON key via the Google Cloud Console.

  Because we use OPNsense, we have no choice but using a P12 key.

   

Verify your setup:

rclone ls gdrive:

Download a backup file:

rclone copy gdrive:opnsense-backups/config-2025-05-28.xml .

Upload the file via the OPNsense web interface:

Go to:
System → Configuration → Backups → Restore → Upload the .xml file.

2. Create your own Google API project (advanced)

If you really want to keep using kio-gdrive (not recommended), then you’ll need to:

➡️ Google will still show a warning ("unverified app") and you’ll need to bypass it by clicking “Advanced” → “Proceed to...”.

⚠️ This is unstable and error-prone, especially if you use 2FA.

3. Download backups manually via your browser 

This is the easiest method for occasional use: just log in to Google Drive via your browser and download the XML backup file manually. Because I have no need for frequent accessing the backup files I use this method and select the downloaded file under Restore:

You don't need the P12 key to restore, because it is already known in OPNsense.