Guide de configuration

Comment connecter OPNsense Mobile à votre firewall OPNsense en 3 étapes.

Sommaire

  1. Exporter le certificat SSL depuis OPNsense
  2. Créer un utilisateur et générer l'API Key
  3. Installer le certificat sur Android
1

Exporter le certificat SSL

Nécessaire pour que l'app puisse se connecter en HTTPS sans erreur.

ℹ️ Si votre OPNsense utilise un certificat signé par une autorité publique (Let's Encrypt…), cette étape n'est pas nécessaire.
1

Accéder au gestionnaire de certificats

Dans l'interface web OPNsense, naviguez vers :

Système› Confiance› Autorités
2

Identifier le bon certificat

Repérez l'autorité de certification (CA) qui a signé le certificat de l'interface web. Si vous utilisez le certificat auto-signé par défaut, c'est généralement OPNsense-CA.

💡 Pour vérifier quel CA est utilisé : Système › Administration › GUI — regardez le champ Certificat SSL.
⚠️
Vérifiez la date de validité du certificat. Un certificat expiré provoquera une erreur de connexion dans l'app même si le CA est correctement installé sur le téléphone. La date d'expiration est visible dans la colonne Valide jusqu'au de la liste des certificats.
3

Exporter le certificat CA

Cliquez sur l'icône de téléchargement (⬇) à droite du CA, puis choisissez :

Exporter le certificat CA→Format .crt

Vous obtenez un fichier opnsense-ca.crt (ou similaire).

4

Vérifier que le certificat web contient l'adresse IP

Si vous vous connectez via une IP (ex : 192.168.1.1), le certificat doit avoir cette IP dans son Subject Alternative Name (SAN). Sans ça, Android refusera la connexion même après installation du CA.

⚠️
Certificat sans SAN IP ? Créez un nouveau certificat dans Système › Confiance › Certificats avec votre IP dans le champ Subject Alternative Names, puis assignez-le dans Système › Administration › SSL Certificate.
2

Créer un utilisateur et générer l'API Key

L'app se connecte via l'API REST d'OPNsense avec une clé dédiée.

⚠️ Ne réutilisez pas le compte root pour l'API. Créez un compte dédié avec des droits limités.
1

Créer un nouveau groupe (optionnel mais recommandé)

Allez dans :

Système› Accès› Groupes

Créez un groupe api-mobile et assignez-lui les privilèges nécessaires :

DiagnosticsGUI Diagnostics
FirewallFirewall: Rules
FirewallFirewall: Logs
SystemSystem: Firmware
2

Créer l'utilisateur

Allez dans :

Système› Accès› Utilisateurs

Cliquez sur + et remplissez :

Nom d'utilisateuropnsense-mobile
Mot de passeUn mot de passe fort (non utilisé par l'app)
Groupesapi-mobile (si créé à l'étape précédente)

Sauvegardez l'utilisateur.

3

Générer la clé API

Ouvrez l'utilisateur nouvellement créé, faites défiler jusqu'à la section API keys et cliquez sur + pour générer une nouvelle paire.

💡 OPNsense affiche l'API Secret une seule fois à la génération. Copiez-le immédiatement dans l'app, il ne sera plus visible ensuite.

Vous obtenez deux valeurs à saisir dans OPNsense Mobile :

API KeyIdentifiant de la clé (visible dans OPNsense)
API SecretSecret associé (affiché une seule fois)
4

Saisir les informations dans l'app

Dans OPNsense Mobile, ajoutez un firewall avec :

URLhttps://192.168.1.1 (ou votre IP/port)
API KeyCopiez la valeur depuis OPNsense
API SecretCopiez la valeur depuis OPNsense
3

Installer le certificat sur Android

Pour que l'app fasse confiance au certificat auto-signé d'OPNsense.

ℹ️ Cette étape est uniquement nécessaire si OPNsense utilise un certificat auto-signé (non signé par une autorité publique reconnue).
1

Transférer le fichier .crt sur votre téléphone

Envoyez le fichier opnsense-ca.crt exporté à l'étape 1 sur votre téléphone :

EmailEnvoyez-vous le fichier en pièce jointe
Google DriveDéposez-le et ouvrez-le depuis l'app Drive
Câble USBCopiez dans le stockage interne du téléphone
2

Installer le certificat CA

Sur Android 11 et supérieur, l'installation se fait uniquement depuis les Paramètres système :

Ouvrez Paramètres
Allez dans Sécurité et vie privée (ou Sécurité)
Appuyez sur Autres paramètres de sécurité
Appuyez sur Installer depuis le stockage de l'appareil
Sélectionnez Certificat CA
Confirmez l'avertissement et sélectionnez votre fichier .crt
⚠️ Android affiche un avertissement de sécurité — c'est normal. Confirmez uniquement si vous faites confiance à votre propre firewall OPNsense.
3

Vérifier l'installation

Pour confirmer que le certificat est bien installé :

Paramètres › Sécurité › Certificats approuvés › onglet Utilisateur
💡 Relancez OPNsense Mobile après l'installation. La connexion devrait maintenant fonctionner sans erreur SSL.

Setup Guide

How to connect OPNsense Mobile to your OPNsense firewall in 3 steps.

Table of contents

  1. Export the SSL certificate from OPNsense
  2. Create a user and generate the API Key
  3. Install the certificate on Android
1

Export the SSL Certificate

Required so the app can connect over HTTPS without errors.

ℹ️ If your OPNsense uses a certificate signed by a public authority (Let's Encrypt…), this step is not required.
1

Open the certificate manager

In the OPNsense web interface, navigate to:

System› Trust› Authorities
2

Identify the right certificate

Find the Certificate Authority (CA) that signed the web interface certificate. If you use the default self-signed certificate, it is usually OPNsense-CA.

💡 To check which CA is in use: System › Administration › GUI — look at the SSL Certificate field.
⚠️
Check the certificate expiry date. An expired certificate will cause a connection error in the app even if the CA is correctly installed on your phone. The expiry date is shown in the Valid until column of the certificate list.
3

Export the CA certificate

Click the download icon (⬇) next to the CA and choose:

Export CA certificate→.crt format

You will get a file named opnsense-ca.crt (or similar).

4

Verify the certificate includes the IP address

If you connect via an IP address (e.g. 192.168.1.1), the certificate must include that IP in its Subject Alternative Name (SAN). Without it, Android will reject the connection even after installing the CA.

⚠️
No SAN IP in the certificate? Create a new certificate under System › Trust › Certificates with your IP in the Subject Alternative Names field, then assign it under System › Administration › SSL Certificate.
2

Create a User and Generate the API Key

The app connects to OPNsense's REST API using a dedicated key.

⚠️ Do not reuse the root account for the API. Create a dedicated account with limited permissions.
1

Create a group (optional but recommended)

Go to:

System› Access› Groups

Create a group named api-mobile and assign the required privileges:

DiagnosticsGUI Diagnostics
FirewallFirewall: Rules
FirewallFirewall: Logs
SystemSystem: Firmware
2

Create the user

Go to:

System› Access› Users

Click + and fill in:

Usernameopnsense-mobile
PasswordA strong password (not used by the app)
Groupsapi-mobile (if created in the previous step)

Save the user.

3

Generate the API key

Open the newly created user, scroll down to the API keys section and click + to generate a new key pair.

💡 OPNsense shows the API Secret only once at generation time. Copy it into the app immediately — it will not be shown again.

You will get two values to enter in OPNsense Mobile:

API KeyThe key identifier (visible in OPNsense)
API SecretThe associated secret (shown once only)
4

Enter the details in the app

In OPNsense Mobile, add a firewall with:

URLhttps://192.168.1.1 (or your IP/port)
API KeyPaste the value from OPNsense
API SecretPaste the value from OPNsense
3

Install the Certificate on Android

So the app trusts OPNsense's self-signed certificate.

ℹ️ This step is only required if OPNsense uses a self-signed certificate (not signed by a publicly trusted authority).
1

Transfer the .crt file to your phone

Send the opnsense-ca.crt file exported in step 1 to your phone:

EmailSend it to yourself as an attachment
Google DriveUpload and open it from the Drive app
USB cableCopy it to the phone's internal storage
2

Install the CA certificate

On Android 11 and above, CA certificate installation must be done from the system Settings:

Open Settings
Go to Security & privacy (or Security)
Tap More security settings
Tap Install from device storage
Select CA certificate
Confirm the warning and select your .crt file
⚠️ Android will display a security warning — this is expected. Confirm only if you trust your own OPNsense firewall.
3

Verify the installation

To confirm the certificate is installed:

Settings › Security › Trusted credentials › User tab
💡 Restart OPNsense Mobile after installing the certificate. The connection should now work without any SSL error.