Informations de référence › Manuel de référence du catalogue d'application › Applications de services Web › WS_API : application API de services Web

WS_API : application API de services Web

Dernière version : 2.0.0-2

Présentation fonctionnelle

L'application WS_API fournit une interface de services Web vers une ou plusieurs grilles par le biais d'un service REST (Representational State Transfer). Vous pouvez utiliser l'une des méthodes d'accès suivantes avec l'interface REST WS_API :

• HTTP : appels API REST HTTP simples.
• HTTPS : appels d'API REST HTTPS sécurisés.
• VPN : les requêtes HTTP sont envoyées via un tunnel VPN sécurisé.

Périmètre

Important : Les adresses IP configurées dans les propriétés d'interface externe iface.vpn, iface.in et iface.net doivent être des adresses IP disponibles sur votre grille CA AppLogic®. Elles figurent, avec les serveurs DNS, dans le tableau de bord de votre grille.

Ressources

Application "WS_API"

Volumes virtuels d'application

L'application proprement dite utilise plusieurs volumes. Ils font partie de celle-ci et sont déjà configurés dans les instances d'appliance. Aucun volume ne doit être configuré sur le périmètre de l'application.

Fonctionnement

Avant de démarrer l'application WS_API, elle doit être configurée pour accéder aux grilles qui vont être gérées via l'interface de service Web. Cela implique de créer un fichier vdcs.conf dans le sous-répertoire de données sur le volume conf. Une paire de clés privée/publique doit être créer et un utilisateur doit être configuré sur le contrôleur de grille cible avec la clé publique générée. Pour plus d'informations sur comment remplir vdcs.conf et comment configurer des clés SSH et créer un utilisateur de grille pour l'API de service Web, voir la section Configuration.

Vous pouvez configurer WS_API pour travailler dans un des modes suivants (ou une combinaison de ces modes) :

Utilisation d'HTTP

Dans ce mode, vous pouvez accéder à l'API REST via l'interface HTTP standard.
Par exemple, exécutez la commande curl http://iface.in/api/v1/app/list?vdc=nom_contrôleur.
Pour lancer l'application de manière à travailler dans ce mode, vous devez définir des valeurs adéquates pour les propriétés obligatoires et la propriété http_mode sur http. Pour plus d'informations sur la procédure de configuration de l'application pour qu'elle fonctionne dans ce mode, reportez-vous à la section Configuration.

Utilisation d'HTTPS

Dans ce mode, vous pouvez accéder à l'API REST via l'interface HTTP sécurisée.
Par exemple, bouclez -k -E /path/to/client_key.pem https://IP_utilisateur/api/v1/app/list?vdc=nom_contrôleur.
Pour lancer l'application de manière à travailler dans ce mode, vous devez définir des valeurs adéquates pour les propriétés obligatoires et la propriété http_mode sur https. Vous pouvez également définir la propriété opts avec les options affichées dans le tableau de propriétés ci-dessus pour que votre certificat soit signé en conséquence. Une fois l'application démarrée, les certificats du client doivent être copiés à partir du sous-répertoire de clés SSL dans le volume conf vers l'application cliente ou le navigateur à utiliser pour accéder à WS_API. Pour plus d'informations sur la façon de configurer l'application dans ce mode, reportez-vous à la section Configuration.

Utilisation d'un tunnel VPN

Dans ce mode, un tunnel VPN sécurisé est créé entre le serveur VPN in_vpn dans l'application et un client VPN du côté client. Une fois que le tunnel est correctement créé à l'aide d'un des différents types de tunneling VPN disponibles, vous pouvez accéder à l'API REST via l'interface HTTP standard.
Par exemple, exécutez la commande curl http://iface.in/api/v1/app/list?vdc=nom_contrôleur.
Pour lancer l'application dans ce mode, vous devez définir des valeurs appropriées pour les propriétés obligatoires, la propriété d'interface externe iface.vpn sur l'adresse IP définie pour l'accès VPN et la propriété vpn_standby sur 0. Par défaut, vpn_ports est défini sur 80,443 pour permettre les connexions aux ports 80 et 443 (HTTP et HTTPS respectivement) et vpn_type est défini sur certificate pour qu'un client VPN puisse se connecter au serveur VPN de l'application via un tunnel basé sur un certificat SSL. Vous pouvez également définir la propriété in_standby sur 1 pour que seules les requêtes via le tunnel VPN soient autorisées. Toute requête API ne provenant pas du tunnel VPN est abandonnée. Pour plus d'informations sur la façon de configurer l'application dans ce mode, reportez-vous à la section Configuration.

Architecture de l'application

L'infrastructure de l'application "WS_API" des services Web de CA AppLogic® est illustrée ci-dessous :

Elle contient les composants suivants.

• Une passerelle d'entrée derrière un pare-feu : prend en charge les requêtes HTTP et HTTPS.
• Un serveur VPN : transmet les requêtes API via un tunnel sécurisé au client VPN du côté client.
• Un serveur Web : traite les requêtes API REST.
• Un stockage centralisé des fichiers de configuration.
• Un journal centralisé - collecte les journaux et stocke des données temporaires
• Une passerelle NET derrière un pare-feu pour les connexions avec les grilles.
• Une appliance de surveillance.

  

Configuration

Cette section explique la procédure de configuration de l'application WS_API pour qu'elle démarre dans l'un des trois modes de fonctionnement possibles.

Pour configurer l'application WS_API

1. Provisionnez WS_API à l'aide de l'assistant de provisionnement d'application dans l'interface utilisateur graphique CA AppLogic® ou utilisez la commande de provisionnement d'application dans le shell. Toutefois, ne définissez pas encore de propriété. Vérifiez que l'assistant est configuré pour ne pas lancer l'application après avoir provisionné ou, si vous utilisez la ligne de commande, appliquez l'option --skipstart .

   app provision WS_API ws_api_instance --skipstart 
   

2. Gérez le volume de données de l'application :

   vol manage ws_api_instance:conf 
   

3. Dans le sous-répertoire de données, vérifiez qu'un fichier nommé vdcs.conf existe.

   cd /mnt/vol/data
   ls vdcs.conf 
   

   Ce fichier contient des informations nécessaires pour accéder aux grilles qui seront gérées via l'API REST.

4. Ouvrez-le à l'aide de l'éditeur de texte vi :

   vi vdcs.conf 
   

5. Modifiez le fichier en vous aidant du modèle :

   vdcs
      { 
      vdc nom_contrôleur : host = IP_contrôleur ou FQDN
         { 
         location  = "ville, état, pays" 
         latitude  = latitude 
         longitude = longitude 
         } 
   
   #  vdc nom_contrôleur : host = IP_contrôleur ou FQDN 
   #     { 
   #     location = "ville, état, pays"
   #     latitude  = latitude
   #     longitude = longitude
   #     }
      } 
   

6. Entrez les informations pertinentes pour les grilles auxquelles accéder avec l'API. Pour ajouter des informations pour une grille supplémentaire, supprimez les commentaires des lignes (supprimez le #) et ajoutez des informations pour la deuxième grille. Vous pouvez ajouter plus de grilles en répétant le bloc vdc dans la section vdcs {...}. Par ailleurs, notez que la définition de valeurs pour la latitude et la longitude est facultative.
7. Enregistrez et fermez l'éditeur de texte.
8. Générez une paire de clés publique/privée pour l'accès ssh aux grilles configurées dans vdcs.conf.

   Pour générer la paire de clés :

   ssh-keygen -t dsa -f /mnt/vol/data/gridkey
   Lorsque vous êtes invité à entrer un mot de passe, appuyez sur Entrée. N'ENTREZ PAS DE MOT DE PASSE.
   chmod 600 /mnt/vol/data/gridkey*
   chown 99:99 /mnt/vol/data/gridkey*
   

9. Copiez la clé publique :

   cat /mnt/vol/data/gridkey.pub 
   

10. Dans le contrôleur de grille, créez un utilisateur API avec cette clé comme clé SSH sshkey sur chacune des grilles :

    user create api@domain.com pwd=- sshkey="ssh-dsa AAA.................xyz" 
    

    L'utilisateur est créé.

11. Configurez l'accès pour l'utilisateur créé :

    grid modify_acl api@domain.com=grid_administrator
    

    Remarque : Vous pouvez utiliser d'autres niveaux d'accès (pour plus d'information, consultez le manuel RBAC), mais cela limitera les commandes que ws_api peut exécuter.

12. Fermez le gestionnaire de volumes.

    Vous pouvez maintenant configurer le périmètre de l'application pour travailler dans l'un des trois modes de fonctionnement.

Mode HTTPS

L'application WS_API fournit une interface de services Web vers une ou plusieurs grilles par le biais d'un service REST (Representational State Transfer). La méthode d'accès HTTPS active les appels d'API REST HTTP sécurisés.

Pour configurer l'application en mode HTTPS

1. Définissez la propriété http_mode sur https (valeur par défaut).
2. Définissez les valeurs adéquates pour les propriétés obligatoires.
3. Définissez la propriété opts pour générer un certificat SSL personnalisé.

   Remarque : Si opts reste vide, un certificat SSL générique est créé au démarrage de l'application. Les paramètres des propriétés http_mode et allowed_hosts peuvent garder leur valeur par défaut. Par exemple :

   app config ws_api_instance iface.in=IP_utilisateur iface.net=IP_réseau dns1=dns1 dns2=dns2 opts=ssl_country=pays,ssl_state=état,ssl_local=ville,ssl_org_name=organisation,ssl_org_unit=unité,ssl_common_name=nom_commun,ssl_email_address=société@domaine.com,ssl_export_pass=clé_accès 
   

4. Démarrez l'application à l'aide de la commande app start ou du bouton Démarrer l'application dans l'interface utilisateur graphique.

   Au premier démarrage de l'application, une clé cliente au format PEM, constituée du certificat client et de la clé privée nommée api_client.pem, ainsi qu'une clé équivalente au format PKCS12 pour les navigateurs, nommée api_client.p14, sont créées dans le sous-répertoire /mnt/config/ssl_keys/keys/ du volume conf. Vous pouvez utiliser le fichier de clé api_client.p14 pour tout accès API basé sur un navigateur et la clé api_client.pem pour tout accès API non basé sur un navigateur.

Pour générer des certificats de client supplémentaires :

1. Connectez-vous au composant main.api_srv de l'instance ws_api_instance en cours d'exécution.
2. Définissez le répertoire sur /mnt/config/ssl_keys.
3. Générez une clé privée pour un compte d'utilisateur "API". openssl genrsa -out keys/api_client2_privkey.pem 2048
4. Générez une demande de signature de certificat (CSR) pour que l'autorité de certification la signe. openssl req -new -key keys/api_client2_privkey.pem -out keys/api_client2_request.csr.
5. Signez la CSR avec notre autorité de certification. openssl x509 -req -days 365 -in keys/api_client2_request.csr -CA CA/CA_cert.pem -CAkey CA/private/CA_key.pem -CAserial CA/CA_cert.srl -out keys/api_client2.cer.
6. Appliquez une commande cat sur api_client2_a.pem et cert pour les regrouper afin de les utiliser comme une clé SSL/PEM de ligne de commande. cat keys/api_client2_privkey.pem keys/api_client2.cer > keys/api_client2.pem.
7. Exportez la clé dans un format qui peut être utilisé par les navigateurs Web communs. openssl pkcs12 -export -in keys/api_client2.cer -inkey keys/api_client2_privkey.pem -out keys/api_client2.p14.

Mode HTTP

L'application WS_API fournit une interface de services Web vers une ou plusieurs grilles par le biais d'un service REST (Representational State Transfer). La méthode d'accès HTTP active les appels d'API REST HTTP simples.

Remarque : Ce mode devrait être utilisé avec une extrême prudence. Il ne comporte aucun contrôle de sécurité et quiconque peut créer une requête API sans aucune authentification. De plus, tout le trafic entre le client et l'application ws_api_instance s'effectue en texte clair.

Pour configurer l'application en mode HTTP, définissez la propriété http_mode sur http et spécifiez les valeurs adéquates pour les propriétés obligatoires. Par exemple :

app config ws_api_instance iface.in=usr-ip iface.net=net-ip dns1=dns1 dns2=dns2 http_mode=http 

L'application peut maintenant être lancée à l'aide de la commande app start ou du bouton Démarrer l'application dans l'interface utilisateur graphique.

Mode VPN

L'application WS_API fournit une interface de services Web vers une ou plusieurs grilles par le biais d'un service REST (Representational State Transfer). La méthode d'accès VPN permet aux requêtes HTTP d'être envoyées via un tunnel VPN sécurisé.

Pour configurer l'application en mode VPN

1. Définissez l'interface externe iface.vpn sur l'adresse IP souhaitée et désactivez vpn_standby (définissez sa valeur sur 0).
2. Définissez in_standby sur 1 afin de limiter l'accès via le VPN défini.

   Par exemple :

   app config ws_api_instance iface.in=IP_utilisateur iface.vpn=IP_VPN iface.net=IP_réseau dns1=dns1 dns2=dns2 vpn_standby=0 in_standby=1 
   

3. Démarrez l'application à l'aide de la commande app start ou du bouton Démarrer l'application dans l'interface utilisateur graphique.

   Une fois l'application démarrée, l'appliance de serveur VPN génère les certificats de serveur et les fichiers de clés nécessaires si ces fichiers ne sont pas déjà présents.

4. Connectez-vous à l'appliance et exécutez le script security.sh situé dans le répertoire /appliance pour générer la clé et les certificats de client.

   [ws_api_instance:main.in_vpn appliance]# ./security.sh generate_client
   Generated client SSL cerfiticate and key file.
   ==============================================
   Ces fichiers, avec le fichier de certificat de CA, doivent être copiés sur le serveur VPN dans le sous-répertoire 
   /client/ sous-répertoire de volume de données ou monté sur un système de fichiers volume.
   Le chemin d'accès aux fichiers clients (client.a1c65e2bae3d0b57) doit être spécifié dans la propriété auth_path.
   Emplacement de fichiers :
   Certificat client : /mnt/data/server/client.a1c65e2bae3d0b57.crt
   Fichier de clé client : /mnt/data/server/client.a1c65e2bae3d0b57.key
   Fichier de certificat de CA situé à l'emplacement /mnt/data/server/ca.crt
   

   Le certificat client (par exemple, client.xxxxxxxxxxxxxxxx.crt) et le fichier de clé client (par exemple, client.xxxxxxxxxxxxxxxx.key) sont générés dans le sous-répertoire client et le certificat de CA (ca.crt) est généré dans le sous-répertoire de serveur du volume conf.

5. Copiez les certificats dans l'appliance de client VPN distant dans le sous-répertoire /client/ sur le volume de données ou le volume monté NFS.

Notes

Logiciels libres et logiciels tiers utilisés

Les logiciels tiers libres suivants sont installés sur le volume de code.