WSO2 API Management Ubuntu DevOps

WSO2 : c’est quoi ? Guide complet pour installer et configurer WSO2 sur un serveur Ubuntu

Par DJAMA Med · Publié le 7 octobre 2026 · Lecture : 15 min · Testé avec WSO2 API Manager 4.7.0 et Ubuntu 24.04 LTS

WSO2 est une suite open source utilisée par des banques, des opérateurs télécoms et des administrations pour gérer, sécuriser et exposer leurs API. Si vous devez mettre en place une passerelle d’API, un portail développeur ou un serveur d’identité, WSO2 fait partie des solutions incontournables. Dans ce guide, vous allez comprendre ce qu’est WSO2, puis installer et configurer WSO2 API Manager sur un serveur Ubuntu, de la base de données PostgreSQL jusqu’au HTTPS avec Nginx.

💡 WSO2, c’est quoi ?

WSO2 est à la fois le nom d’une entreprise et d’une suite de logiciels. Fondée en 2005 au Sri Lanka, l’entreprise développe des solutions open source pour trois besoins des systèmes d’information modernes :

La gestion des API : publier, sécuriser, limiter et monitorer les API d’une organisation ;
La gestion des identités et des accès (IAM) : authentification unique (SSO), OAuth2, OpenID Connect, SAML, authentification multifacteur ;
L’intégration : faire communiquer des applications hétérogènes (ERP, bases de données, services SOAP et REST, files de messages).

Le code source des produits WSO2 est publié sous licence Apache 2.0. Vous pouvez donc les télécharger, les installer et les utiliser gratuitement, y compris en production. WSO2 vend en parallèle des abonnements qui donnent accès au support et aux mises à jour continues.

2005

Création de WSO2

Apache 2.0

Licence open source

4.7.0

Dernière version d’API Manager (avril 2026)

🧰 Les principaux produits WSO2

Quand on parle « d’installer WSO2 », on installe en réalité un des produits de la suite. Voici les plus utilisés :

🔗 WSO2 API Manager

Plateforme complète de gestion des API : passerelle (API Gateway), portail de publication, portail développeur, quotas, monétisation et analytique. C’est le produit installé dans ce guide.

🔐 WSO2 Identity Server

Serveur de gestion des identités et des accès : SSO, OAuth2, OpenID Connect, SAML, MFA, fédération d’identités. Une alternative à Keycloak.

🔄 WSO2 Micro Integrator

Moteur d’intégration (héritier de l’ESB WSO2) pour orchestrer des services, transformer des messages et connecter des systèmes existants.

☁️ Offres cloud (SaaS)

Asgardeo (identité en tant que service) et Choreo (plateforme de développement interne) pour ceux qui ne veulent pas gérer de serveur.

⚙️ Comment fonctionne WSO2 API Manager ?

WSO2 API Manager se place entre vos clients (applications mobiles, sites web, partenaires) et vos services backend. Au lieu d’appeler directement vos microservices, les clients passent par la passerelle, qui vérifie le jeton d’accès, applique les quotas et enregistre les statistiques. Une installation standard regroupe quatre composants :

🛡️

API Gateway

Reçoit les appels d’API, contrôle les jetons OAuth2 ou les clés d’API, applique le throttling et route vers le backend. Ports 8243 (HTTPS) et 8280 (HTTP).

📝

Publisher

Portail où les équipes créent, documentent, versionnent et publient leurs API (REST, GraphQL, WebSocket, SOAP, AsyncAPI).

👨‍💻

Developer Portal

Catalogue où les développeurs découvrent les API, s’abonnent, génèrent leurs clés et testent les appels.

🔑

Key Manager et Admin Portal

Le Key Manager délivre et valide les jetons d’accès. L’Admin Portal permet de définir les politiques de quotas, les environnements et les paramètres globaux.

La version 4.7.0, sortie en avril 2026, ajoute notamment une passerelle basée sur Envoy, des clés d’API liées à une API précise, le chiffrement AES-256 GCM par défaut, la prise en charge d’AsyncAPI 3.0 et des fonctions de gouvernance pour les serveurs MCP (Model Context Protocol) utilisés par les agents d’IA.

📋 Prérequis pour installer WSO2 sur Ubuntu

Ce tutoriel a été préparé pour Ubuntu 24.04 LTS (il fonctionne aussi sur Ubuntu 22.04). Configuration minimale selon la documentation officielle de WSO2 :

🖥️

2 cœurs CPU minimum

🧠

4 Go de RAM (8 Go conseillés)

💾

10 Go de disque libre

☕

JDK 21 ou 25

Il vous faut aussi :

un accès SSH avec un utilisateur sudo ;
deux sous-domaines pointant vers l’IP du serveur, par exemple api.mondomaine.com (portails) et gw.mondomaine.com (passerelle) ;
les ports 80 et 443 ouverts chez votre hébergeur.

⚠️ Attention à Java : WSO2 API Manager 4.7 ne fonctionne qu’avec Java 21 ou Java 25. Les JDK 11 et 17, utilisés par les anciennes versions, ne sont plus supportés.

🚀 Installer WSO2 API Manager sur Ubuntu

Étape 1 : mettre à jour le serveur et installer Java 21

bash

sudo apt update && sudo apt upgrade -y
sudo apt install -y openjdk-21-jdk unzip curl
java -version

La commande java -version doit afficher openjdk version "21…". Déclarez ensuite la variable JAVA_HOME pour tout le système :

bash

echo 'JAVA_HOME="/usr/lib/jvm/java-21-openjdk-amd64"' | sudo tee -a /etc/environment
source /etc/environment
echo $JAVA_HOME

👉 Sur un serveur ARM (Ampere, Graviton), le chemin se termine par -arm64 au lieu de -amd64. Vérifiez avec ls /usr/lib/jvm/.

Étape 2 : créer un utilisateur dédié et télécharger WSO2

Ne lancez jamais WSO2 en root. Créez un utilisateur système wso2, puis téléchargez l’archive officielle depuis GitHub :

bash

sudo useradd --system --create-home --home-dir /opt/wso2 --shell /usr/sbin/nologin wso2

cd /tmp
curl -LO https://github.com/wso2/product-apim/releases/download/v4.7.0/wso2am-4.7.0.zip
sudo unzip -q wso2am-4.7.0.zip -d /opt/wso2
sudo chown -R wso2:wso2 /opt/wso2
ls /opt/wso2/wso2am-4.7.0

Dans la suite, le dossier /opt/wso2/wso2am-4.7.0 est appelé <API-M_HOME>, comme dans la documentation officielle. Les fichiers importants :

bin/api-manager.sh : script de démarrage ;
repository/conf/deployment.toml : le fichier de configuration central ;
repository/components/lib/ : emplacement des pilotes JDBC ;
repository/logs/wso2carbon.log : journal principal ;
dbscripts/ : scripts SQL de création des tables.

Étape 3 : premier démarrage de test

Avant toute configuration, vérifiez que le serveur démarre avec la base H2 embarquée :

bash

sudo -u wso2 env JAVA_HOME=$JAVA_HOME /opt/wso2/wso2am-4.7.0/bin/api-manager.sh

Attendez le message WSO2 Carbon started in X sec. Pour ouvrir les portails sans exposer de port, créez un tunnel SSH depuis votre poste :

bash — sur votre ordinateur

ssh -L 9443:localhost:9443 utilisateur@ip_du_serveur

Ouvrez ensuite https://localhost:9443/publisher dans votre navigateur, acceptez l’avertissement de certificat (certificat auto-signé) et connectez-vous avec admin / admin. Si tout s’affiche, arrêtez le serveur avec Ctrl+C : nous allons maintenant le configurer pour la production. Supprimez au passage l’index de recherche créé pendant ce test, pour repartir de zéro avec PostgreSQL : sudo rm -rf /opt/wso2/wso2am-4.7.0/solr.

🐘 Étape 4 : configurer PostgreSQL pour WSO2

La base H2 fournie par défaut est pratique pour tester, mais déconseillée en production. WSO2 API Manager prend en charge PostgreSQL, MySQL, Oracle, SQL Server et DB2. Nous utilisons ici PostgreSQL (voir notre comparatif PostgreSQL vs MySQL).

API Manager utilise deux bases : apim_db (données des API, applications, abonnements) et shared_db (utilisateurs, rôles et registre).

bash

sudo apt install -y postgresql libpostgresql-jdbc-java

sudo -u postgres psql <<'SQL'
CREATE USER apimadmin WITH PASSWORD 'ChangezMoi_Apim2026';
CREATE USER sharedadmin WITH PASSWORD 'ChangezMoi_Shared2026';
CREATE DATABASE apim_db OWNER apimadmin;
CREATE DATABASE shared_db OWNER sharedadmin;
SQL

👉 Rendre chaque utilisateur propriétaire de sa base (OWNER) évite l’erreur permission denied for schema public que l’on rencontre avec PostgreSQL 15 et plus récent lorsqu’on se contente d’un GRANT.

Créez ensuite les tables à l’aide des scripts fournis par WSO2 :

bash

cd /opt/wso2/wso2am-4.7.0

PGPASSWORD='ChangezMoi_Shared2026' psql -h localhost -U sharedadmin -d shared_db -f dbscripts/postgresql.sql
PGPASSWORD='ChangezMoi_Apim2026' psql -h localhost -U apimadmin -d apim_db -f dbscripts/apimgt/postgresql.sql

Enfin, copiez le pilote JDBC PostgreSQL installé par le paquet libpostgresql-jdbc-java dans WSO2 :

bash

sudo cp /usr/share/java/postgresql.jar /opt/wso2/wso2am-4.7.0/repository/components/lib/
sudo chown wso2:wso2 /opt/wso2/wso2am-4.7.0/repository/components/lib/postgresql.jar

Vous débutez avec PostgreSQL ? Consultez notre guide pour installer PostgreSQL.

🛠️ Étape 5 : configurer WSO2 avec deployment.toml

Toute la configuration de WSO2 API Manager passe par un seul fichier : repository/conf/deployment.toml. Faites d’abord une sauvegarde, puis ouvrez-le :

bash

cd /opt/wso2/wso2am-4.7.0/repository/conf
sudo cp deployment.toml deployment.toml.bak
sudo nano deployment.toml

⚠️ Important : les sections ci-dessous ([server], [super_admin], [database.apim_db]…) existent déjà dans le fichier. Modifiez-les sur place au lieu de les ajouter en double, sinon le format TOML sera invalide et le serveur refusera de démarrer.

Nom d’hôte, compte administrateur et proxy

deployment.toml

[server]
hostname = "api.mondomaine.com"

[super_admin]
username = "admin"
password = "Un_Mot_De_Passe_Tres_Solide"
create_admin_account = true

# WSO2 est derrière Nginx qui écoute en HTTPS sur le port 443
[transport.https.properties]
proxyPort = 443

👉 Le mot de passe administrateur est créé au premier démarrage sur une base vide. Changez-le donc maintenant, avant de démarrer WSO2 avec PostgreSQL. Par la suite, il se modifie depuis la console d’administration.

Connexion aux bases de données

deployment.toml

[database.apim_db]
type = "postgre"
url = "jdbc:postgresql://localhost:5432/apim_db"
username = "apimadmin"
password = "ChangezMoi_Apim2026"
driver = "org.postgresql.Driver"
validationQuery = "SELECT 1"

[database.shared_db]
type = "postgre"
url = "jdbc:postgresql://localhost:5432/shared_db"
username = "sharedadmin"
password = "ChangezMoi_Shared2026"
driver = "org.postgresql.Driver"
validationQuery = "SELECT 1"

URL publique de la passerelle

Pour que le Developer Portal affiche la bonne adresse de vos API, cherchez le bloc [[apim.gateway.environment]] et modifiez uniquement ces deux lignes :

deployment.toml — dans [[apim.gateway.environment]]

http_endpoint = "http://gw.mondomaine.com"
https_endpoint = "https://gw.mondomaine.com"

💡 Astuce sécurité : en production, évitez les mots de passe en clair dans deployment.toml. WSO2 fournit l’outil bin/ciphertool.sh (Secure Vault) pour les chiffrer. Pensez aussi à remplacer le keystore par défaut wso2carbon.jks par vos propres clés.

🔄 Étape 6 : lancer WSO2 comme service systemd

Pour que WSO2 démarre automatiquement au boot et redémarre en cas de crash, créez un service systemd :

/etc/systemd/system/wso2am.service

[Unit]
Description=WSO2 API Manager 4.7.0
After=network.target postgresql.service
Requires=postgresql.service

[Service]
Type=simple
User=wso2
Group=wso2
Environment=JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
ExecStart=/opt/wso2/wso2am-4.7.0/bin/api-manager.sh
SuccessExitStatus=143
Restart=on-failure
RestartSec=10
TimeoutStopSec=60
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

bash

sudo systemctl daemon-reload
sudo systemctl enable --now wso2am
sudo systemctl status wso2am

# Suivre le démarrage
sudo tail -f /opt/wso2/wso2am-4.7.0/repository/logs/wso2carbon.log

Le démarrage prend généralement entre 30 secondes et 2 minutes. Attendez la ligne WSO2 Carbon started avant de continuer.

🔒 Étape 7 : Nginx en reverse proxy et HTTPS avec Let’s Encrypt

Plutôt que d’exposer les ports 9443 et 8243 sur Internet, placez Nginx devant WSO2. Il gère le certificat HTTPS gratuit de Let’s Encrypt et transmet les requêtes en local.

bash

sudo apt install -y nginx certbot python3-certbot-nginx
sudo nano /etc/nginx/sites-available/wso2

/etc/nginx/sites-available/wso2

# Portails : Publisher, Developer Portal, Admin, Carbon
server {
    listen 80;
    server_name api.mondomaine.com;
    client_max_body_size 20m;

    location / {
        proxy_pass https://127.0.0.1:9443;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 300s;
    }
}

# Passerelle d'API (API Gateway)
server {
    listen 80;
    server_name gw.mondomaine.com;
    client_max_body_size 20m;

    location / {
        proxy_pass https://127.0.0.1:8243;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 300s;
    }
}

Activez la configuration puis demandez les certificats. Certbot ajoute automatiquement le HTTPS et la redirection HTTP vers HTTPS :

bash

sudo ln -s /etc/nginx/sites-available/wso2 /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d api.mondomaine.com -d gw.mondomaine.com

👉 WSO2 utilise en interne un certificat auto-signé. Nginx ne vérifie pas le certificat du serveur en amont par défaut, la connexion locale fonctionne donc sans configuration supplémentaire.

Étape 8 : configurer le pare-feu UFW

N’ouvrez au public que SSH, HTTP et HTTPS. Les ports internes de WSO2 (9443, 8243, 8280, 9099…) restent accessibles uniquement en local :

bash

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
sudo ufw status

✅ Étape 9 : tester l’installation de WSO2

Redémarrez WSO2 pour prendre en compte la configuration (sudo systemctl restart wso2am), puis ouvrez les différents portails :

Portail	URL
Publisher	https://api.mondomaine.com/publisher
Developer Portal	https://api.mondomaine.com/devportal
Admin Portal	https://api.mondomaine.com/admin
Console Carbon	https://api.mondomaine.com/carbon
Passerelle (appels d’API)	https://gw.mondomaine.com/<contexte>/<version>

Pour valider toute la chaîne :

Dans le Publisher, créez une API REST pointant vers un backend public de test, puis déployez-la et publiez-la.
Dans le Developer Portal, créez une application, abonnez-la à l’API et générez un jeton d’accès.
Appelez l’API à travers la passerelle :

bash

curl -H "Authorization: Bearer VOTRE_JETON" https://gw.mondomaine.com/monapi/1.0.0/ressource

Si vous recevez la réponse du backend, votre WSO2 API Manager est opérationnel. Sans jeton, la passerelle doit répondre 401 Unauthorized : c’est le signe que la sécurité fonctionne.

🐳 Alternative rapide : tester WSO2 avec Docker

Pour un simple test en local, l’image officielle évite toute installation :

bash

docker run -d --name wso2am -p 9443:9443 -p 8243:8243 -p 8280:8280 wso2/wso2am:4.7.0

Pour WSO2 Identity Server, la logique est identique : image wso2/wso2is:7.3.0, ou archive wso2is-7.x.zip avec le script bin/wso2server.sh et la console sur https://localhost:9443/console. Les étapes Java, utilisateur dédié, systemd et Nginx de ce guide s’appliquent de la même façon.

🧪 Dépannage : les erreurs WSO2 les plus courantes

« Unsupported class file major version » ou le serveur s’arrête aussitôt

Mauvaise version de Java. Vérifiez java -version et JAVA_HOME : WSO2 API Manager 4.7 exige Java 21 ou 25.

« Address already in use »

Un autre service utilise déjà le port 9443 ou 8243. Identifiez-le avec sudo ss -tlnp | grep 9443, ou décalez tous les ports de WSO2 avec offset = 1 dans la section [server].

502 Bad Gateway dans le navigateur

WSO2 n’a pas fini de démarrer ou a planté. Consultez wso2carbon.log et sudo journalctl -u wso2am -n 100.

Redirection vers localhost:9443 après la connexion

Le hostname ou le proxyPort n’est pas configuré dans deployment.toml. Corrigez puis redémarrez le service.

OutOfMemoryError ou serveur très lent

Le serveur manque de RAM. Passez à 8 Go, ou ajoutez un fichier d’échange (swap) sur un petit VPS de test.

Erreur de connexion à PostgreSQL au démarrage

Vérifiez que postgresql.jar est bien dans repository/components/lib/, puis les identifiants. Testez-les à la main avec psql -h localhost -U apimadmin -d apim_db.

❓ Questions fréquentes sur WSO2

WSO2 est-il gratuit ?

Le code source des produits WSO2 est open source sous licence Apache 2.0 et peut être téléchargé et utilisé gratuitement, y compris en production. WSO2 vend en plus des abonnements qui donnent accès au support et aux mises à jour continues des versions publiées.

Quelle configuration minimale pour installer WSO2 API Manager ?

La documentation officielle demande au minimum 2 cœurs CPU, 4 Go de RAM et 10 Go d’espace disque libre, ainsi qu’un JDK 21 ou 25 pour la version 4.7. Pour la production, prévoyez davantage de mémoire.

Quelle est la différence entre WSO2 Identity Server et Keycloak ?

Les deux sont des solutions open source de gestion des identités (SSO, OAuth2, OpenID Connect, SAML). Keycloak est plus léger et très répandu dans l’écosystème Java et Kubernetes. WSO2 Identity Server propose des fonctions avancées pour les grandes organisations et s’intègre naturellement avec WSO2 API Manager. Pour Keycloak, voir notre guide de déploiement de Keycloak sur un VPS Ubuntu.

Peut-on utiliser MySQL au lieu de PostgreSQL avec WSO2 ?

Oui. WSO2 API Manager prend en charge MySQL, PostgreSQL, Oracle, Microsoft SQL Server et IBM DB2. La base H2 fournie par défaut est réservée aux tests.

Peut-on installer WSO2 avec Docker ?

Oui. WSO2 publie des images officielles sur Docker Hub, par exemple wso2/wso2am:4.7.0 pour API Manager et wso2/wso2is:7.3.0 pour Identity Server. C’est la méthode la plus rapide pour tester.

Combien de temps faut-il à WSO2 pour démarrer ?

En général entre 30 secondes et 2 minutes selon la machine. Le serveur est prêt lorsque le message « WSO2 Carbon started » apparaît dans les logs.

WSO2 API Manager offre gratuitement des fonctions de gestion des API que l’on ne trouve souvent que dans des solutions commerciales coûteuses : passerelle, portail développeur, quotas et analytique.

🎯 Conclusion

Vous savez maintenant ce qu’est WSO2 et vous disposez d’un WSO2 API Manager 4.7 installé sur Ubuntu, configuré pour la production : Java 21, base PostgreSQL, utilisateur dédié, service systemd, reverse proxy Nginx, certificat HTTPS et pare-feu.

Pour aller plus loin : chiffrez les mots de passe avec Secure Vault, remplacez les keystores par défaut, mettez en place des sauvegardes régulières de PostgreSQL et, pour une forte charge, séparez la passerelle du plan de contrôle sur plusieurs serveurs.

Java 21 ou 25 — obligatoire depuis la version 4.7
PostgreSQL ou MySQL — jamais H2 en production
deployment.toml — le seul fichier à maîtriser pour configurer WSO2
Nginx + HTTPS — ne jamais exposer directement les ports 9443 et 8243

🔗

Besoin d’aide pour déployer WSO2 ou sécuriser vos API ?

Installation, configuration, intégration SSO ou architecture d’API — je peux vous accompagner dans votre projet.

Discutons de votre projet

Sources

Mots-clés : WSO2, WSO2 c’est quoi, installer WSO2, WSO2 Ubuntu, WSO2 API Manager, installation WSO2 API Manager, configurer WSO2, WSO2 deployment.toml, WSO2 PostgreSQL, WSO2 Nginx, WSO2 Identity Server, API Gateway open source, gestion des API, WSO2 Docker.

WSO2 : c’est quoi ? Guide complet pour installer et configurer WSO2 sur un serveur Ubuntu

💡 WSO2, c’est quoi ?

🧰 Les principaux produits WSO2

⚙️ Comment fonctionne WSO2 API Manager ?

📋 Prérequis pour installer WSO2 sur Ubuntu

🚀 Installer WSO2 API Manager sur Ubuntu

Étape 1 : mettre à jour le serveur et installer Java 21

Étape 2 : créer un utilisateur dédié et télécharger WSO2

Étape 3 : premier démarrage de test

🐘 Étape 4 : configurer PostgreSQL pour WSO2

🛠️ Étape 5 : configurer WSO2 avec deployment.toml

Nom d’hôte, compte administrateur et proxy

Connexion aux bases de données

URL publique de la passerelle

🔄 Étape 6 : lancer WSO2 comme service systemd

🔒 Étape 7 : Nginx en reverse proxy et HTTPS avec Let’s Encrypt

Étape 8 : configurer le pare-feu UFW

✅ Étape 9 : tester l’installation de WSO2

🐳 Alternative rapide : tester WSO2 avec Docker

🧪 Dépannage : les erreurs WSO2 les plus courantes

❓ Questions fréquentes sur WSO2

WSO2 est-il gratuit ?

Quelle configuration minimale pour installer WSO2 API Manager ?

Quelle est la différence entre WSO2 Identity Server et Keycloak ?

Peut-on utiliser MySQL au lieu de PostgreSQL avec WSO2 ?

Peut-on installer WSO2 avec Docker ?

Combien de temps faut-il à WSO2 pour démarrer ?

🎯 Conclusion

Articles recommandés

C’est quoi Keycloak et quand l’utiliser ?

Déployer Keycloak en production sur un VPS Ubuntu

PostgreSQL vs MySQL : le match