Connecter des applications Python à l'aide de mTLS

S'APPLIQUE À : Applicable Exadata Cloud@Customer seulement

Vous pouvez connecter des applications Python à votre instance Autonomous Database à l'aide de mTLS.

La connexion d'une application Python avec mTLS assure une sécurité renforcée lors de l'authentification et du chiffrement, et la sécurité est appliquée à l'aide de données d'identification de client (en fournissant un nom d'utilisateur et un mot de passe).

Le "mode léger" par défaut du pilote python-oracledb se connecte directement à Oracle Database. Le pilote peut éventuellement utiliser les bibliothèques du client Oracle, "mode lourd", pour certaines fonctionnalités supplémentaires. Les bibliothèques du client Oracle peuvent être celles d'Oracle Instant Client, du client Oracle complet ou d'une installation d'Oracle Database.

Suivez ces étapes pour connecter votre application Python à une instance Autonomous Database à l'aide du protocole mTLS :

  1. Installer Python et le pilote python-oracledb
  2. Obtenir des données d'identification de sécurité (Oracle Wallet) et activer la connectivité réseau
  3. Effectuez cette étape pour vous connecter uniquement en mode léger : Exécuter une application Python en mode léger python-oracledb (mTLS)
  4. Effectuez cette étape pour vous connecter en mode lourd : Exécuter une application Python en mode lourd python-oracledb (mTLS)

Installer Python et le pilote python-oracledb

Pour vous connecter à Autonomous Database à partir de votre application Python, installez Python et le pilote python-oracledb.

  1. Installez Python 3, s'il n'est pas déjà disponible.

    La version de Python que vous utilisez dépend de votre système d'exploitation et de votre matériel côté client. Par exemple Windows, Linux, macOS et d'autres.

    Note :

    Oracle vous recommande de rester à jour avec les versions de pilote Python et python-oracledb.
  2. Installez le pilote python-oracledb à partir de PyPI.

    Le pilote python-oracledb est un module d'extension du langage de programmation Python qui permet aux programmes Python de se connecter à Oracle Database. Le pilote python-oracledb est la nouvelle version majeure du pilote cx_Oracle populaire, renommée.

    Versions du pilote python-oracledb prises en charge : python-oracledb 1.0 (ou version ultérieure)

    Exécutez la commande suivante pour mettre à niveau Python :

    python -m pip install oracledb --upgrade

    Un résultat semblable au suivant :

    Collecting oracledb
      Downloading oracledb-1.0.3-cp310-cp310-win_amd64.whl (1.0 MB)
         ---------------------------------------- 1.0/1.0 MB 1.8 MB/s eta 0:00:00
    Collecting cryptography>=3.4
      Downloading cryptography-37.0.4-cp36-abi3-win_amd64.whl (2.4 MB)
         ---------------------------------------- 2.4/2.4 MB 3.5 MB/s eta 0:00:00
    Collecting cffi>=1.12
      Downloading cffi-1.15.1-cp310-cp310-win_amd64.whl (179 kB)
         ---------------------------------------- 179.1/179.1 kB 5.4 MB/s eta 0:00:00
    Collecting pycparser
      Downloading pycparser-2.21-py2.py3-none-any.whl (118 kB)
         ---------------------------------------- 118.7/118.7 kB 7.2 MB/s eta 0:00:00
    Installing collected packages: pycparser, cffi, cryptography, oracledb
    Successfully installed cffi-1.15.1 cryptography-37.0.4 oracledb-1.0.3 pycparser-2.21

    Notes sur l'installation de python-oracledb :

    • Si vous êtes derrière un mandataire, utilisez l'option --proxy pour ajouter un serveur mandataire à la commande. Par exemple :

      python -m pip install oracledb --upgrade --proxy=http://proxy.example.com:80
    • Si vous n'êtes pas autorisé à écrire dans les répertoires du système, ajoutez l'option --user. Par exemple :

      python -m pip install oracledb --upgrade --user
    • Si un ensemble binaire n'est pas disponible pour votre plate-forme, l'exécution de pip télécharge l'ensemble source. La source est compilée et le binaire produit est installé.

    Voir Installation de python-oracledb pour obtenir des options et des conseils supplémentaires.

  3. Si vous souhaitez utiliser le pilote python-oracledb en mode lourd, installez le logiciel client Oracle.

    Par défaut, python-oracledb s'exécute en mode léger et se connecte directement à Oracle Database. En mode léger, les bibliothèques Oracle Client ne sont pas nécessaires. Cependant, certaines fonctionnalités supplémentaires sont disponibles lorsque python-oracledb s'exécute en mode lourd.

    Note :

    Voir Fonctions d'Oracle Database prises en charge par python-oracledb pour plus d'informations sur les fonctions prises en charge dans les modes python-oracledb léger et lourd. Toutes les fonctions auxquelles ce lien permet d'accéder ne sont pas disponibles avec la base de données autonome.

    Python-oracledb utilise le mode lourd lorsque vous utilisez les bibliothèques d'Oracle Instant client ou Oracle Database Client et que vous appelez oracledb.init_oracle_client() dans votre code Python.

    Lorsque vous installez le logiciel client Oracle, il existe des différences entre les versions minimales requises pour les connexions mTLS et TLS, comme suit :

    • Connexions TLS mutuelles (mTLS) :

      • Si votre base de données se trouve sur un ordinateur distant, téléchargez l'ensemble gratuit Oracle Instant Client "Basic" ou "Basic Light" pour votre architecture de système d'exploitation. Utilisez une version prise en charge : Oracle Instant Client : 18.19 (ou version ultérieure), 19.2 (ou version ultérieure) ou 21 (version de base ou version ultérieure).

      • Vous pouvez également utiliser les bibliothèques du client Oracle Database complet lorsqu'elles sont disponibles sur votre système (y compris le client Oracle Database complet : Client Oracle Database : 18.19 (ou plus récente), 19.2 (ou plus récente) ou 21 (version de base ou plus récente).

    • Connexions TLS : Les clients Oracle Call Interface (OCI) prennent en charge l'authentification TLS si vous utilisez les versions de client suivantes :

      • Oracle Instant Client/Oracle Database Client 19.14 (ou version ultérieure) et 21.5 (ou version ultérieure) - toutes les plates-formes
      • Vous pouvez également utiliser les bibliothèques du client Oracle Database complet lorsqu'elles sont disponibles sur votre système, y compris le client Oracle Database complet versions 19.14 (ou supérieure) et 21.5 (ou supérieure).

Obtenir des données d'identification de sécurité (Oracle Wallet) et activer la connectivité réseau

Obtenez les données d'identification de sécurité du client pour la connexion à une instance de base de données autonome.

  1. Téléchargez un fichier de portefeuille à partir de l'instance Autonomous Database pour obtenir un fichier zip contenant les données d'identification de sécurité du client et les paramètres de configuration de réseau requis pour accéder à une instance Autonomous Database.

    Obtenez les données d'identification de sécurité du client (fichier wallet.zip) :

    • Utilisateur ADMIN : Dans la console Oracle Cloud Infrastructure, cliquez sur Connexion à la base de données. Reportez-vous à la section Télécharger les données d'identification du client (pôts).

    • Autre utilisateur (non administrateur) : Obtenez le portefeuille Oracle Wallet pour l'instance de base de données autonome auprès de l'administrateur.

    Note :

    Protégez le fichier wallet.zip et son contenu pour empêcher l'accès non autorisé à la base de données.
  2. décompressez le fichier de données d'identification du client (wallet.zip).

Exécuter l'application Python en mode léger python-oracledb (mTLS)

Par défaut, python-oracledb utilise le mode léger pour se connecter directement à votre instance de base de données autonome.

En mode léger, seuls deux fichiers du fichier zip du portefeuille sont nécessaires :

  • tnsnames.ora : Mappe les noms de service de réseau utilisés pour les chaînes de connexion d'application à vos services de base de données.

  • ewallet.pem : Active les connexions SSL/TLS en mode léger.

Pour vous connecter en mode léger :

  1. Déplacez les fichiers tnsnames.ora et ewallet.pem vers un emplacement sur votre système.

    Par exemple, sous Linux :

    /opt/OracleCloud/MYDB

    Par exemple, sous Windows :

    C:\opt\OracleCloud\MYDB
  2. Dans votre application Python, définissez les paramètres de connexion suivants pour vous connecter à une instance Autonomous Database :
    • config_dir : Spécifie le répertoire contenant tnsnames.ora.
    • dsn : Spécifiez l'alias de réseau voulu à partir du fichier tnsnames.ora.
    • password : Spécifie le mot de passe de l'utilisateur de la base de données.
    • user : Spécifie l'utilisateur de base de données.
    • wallet_location : Spécifie le répertoire contenant le fichier PEM (ewallet.pem).
    • wallet_password : Spécifie le mot de passe pour le fichier PEM (ewallet.pem. Vous définissez ce mot de passe lorsque vous téléchargez le fichier wallet.zip.

    Par exemple, sous Linux pour vous connecter en tant qu'utilisateur ADMIN à l'aide de oracledb.connect avec le nom du service de réseau db2024_low (le nom du service se trouve dans tnsnames.ora) :

    connection=oracledb.connect(
         config_dir="/opt/OracleCloud/MYDB",
         user="admin",
         password=password,
         dsn="db2024_low",
         wallet_location="/opt/OracleCloud/MYDB",
         wallet_password=wallet_pw)

    Par exemple, sous Windows pour vous connecter en tant qu'utilisateur ADMIN à l'aide de oracledb.connect avec le nom du service de réseau db2024_low (le nom du service se trouve dans tnsnames.ora) :

    connection=oracledb.connect(
         config_dir=r"C:\opt\OracleCloud\MYDB",
         user="admin",
         password=password,
         dsn="db2024_low",
         wallet_location=r"C:\opt\OracleCloud\MYDB",
         wallet_password=wallet_pw)

    L'utilisation d'une chaîne brute r"..." signifie que les barres obliques inverses sont traitées comme des séparateurs de répertoire.

    Comme illustré dans cet exemple, wallet_location et config_dir sont réglés au même répertoire (et celui-ci contient tnsnames.ora et ewallet.pem). Il n'est pas nécessaire de spécifier le même répertoire pour ces fichiers.

Si vous êtes derrière un pare-feu, vous pouvez tunneliser les connexions TLS/SSL au moyen d'un mandataire à l'aide de HTTPS_PROXY dans le descripteur de connexion ou en définissant des attributs de connexion. La connexion réussie dépend de configurations de mandataire spécifiques. Oracle ne recommande pas l'utilisation d'un mandataire dans un environnement de production, en raison de l'incidence possible sur les performances. Pour plus d'informations, voir HTTPS_PROXY dans Informations de référence sur les services nets de base de données pour Oracle Database 19c ou Informations de référence sur les services nets de base de données pour Oracle Database 23ai.

En mode léger, vous pouvez spécifier un mandataire en ajoutant les paramètres https_proxy et http_proxy_port.

Par exemple, sous Linux :

connection=oracledb.connect(
     config_dir="/opt/OracleCloud/MYDB",
     user="admin",
     password=password,
     dsn="db2024_low",
     wallet_location="/opt/OracleCloud/MYDB",
     wallet_password=wallet_pw,
     https_proxy='myproxy.example.com',
     https_proxy_port=80)

Par exemple, sous Windows :

connection=oracledb.connect(
     config_dir=r"C:\opt\OracleCloud\MYDB",
     user="admin",
     password=password,
     dsn="db2024_low",
     wallet_location=r"C:\opt\OracleCloud\MYDB",
     wallet_password=wallet_pw,
     https_proxy='myproxy.example.com',
     https_proxy_port=80)

Exécuter l'application Python en mode lourd python-oracledb (mTLS)

Par défaut, python-oracledb s'exécute en mode léger et se connecte directement à Oracle Database. Des fonctions python-oracledb supplémentaires sont disponibles lorsque le pilote s'exécute en mode lourd.

Note :

Le mode lourd nécessite que les bibliothèques du client Oracle soient installées là où vous exécutez Python. Vous devez également appeler oracledb.init_oracle_client() dans votre code Python.

En mode lourd, les trois fichiers suivants du fichier zip de portefeuille sont requis :

  • tnsnames.ora : Contient les noms de service de réseau utilisés pour les chaînes de connexion d'application et mappe ces chaînes à vos services de base de données.

  • sqlnet.ora : Spécifie la configuration SQL*Net côté client.

  • cwallet.sso : Contient le portefeuille d'authentification unique à ouverture automatique.

Pour vous connecter en mode lourd :

  1. Placez les fichiers tnsnames.ora, sqlnet.ora et cwallet.sso sur votre système.

    Utilisez l'une des deux options suivantes pour placer ces fichiers sur votre système :

    • Si vous utilisez Instant Client, déplacez les fichiers vers un sous-répertoire network/admin sous le répertoire Instant Client. Par exemple, selon l'architecture ou le système client et l'endroit où vous avez installé Instant Client, les fichiers doivent se trouver dans un répertoire tel que :

      /home/myuser/instantclient_19_21/network/admin

      ou

      /usr/lib/oracle/19.21/client64/lib/network/admin

      Par exemple, sous Linux, si vous utilisez le client Oracle complet, déplacez les fichiers vers $ORACLE_HOME/network/admin.

    • Vous pouvez également déplacer les fichiers vers tout répertoire accessible.

      Par exemple, sous Linux, déplacez les fichiers vers le répertoire /opt/OracleCloud/MYDB et modifiez sqlnet.ora pour remplacer le répertoire du portefeuille par celui contenant le fichier cwallet.sso.

      Par exemple, sous Linux, modifiez sqlnet.ora comme suit :

      WALLET_LOCATION = (SOURCE = (METHOD=file) (METHOD_DATA = (DIRECTORY="/opt/OracleCloud/MYDB")))
      SSL_SERVER_DN_MATCH=yes

      Lorsque les fichiers de configuration ne se trouvent pas dans l'emplacement par défaut, votre application doit indiquer où ils se trouvent, soit avec le paramètre config_dir dans l'appel oracledb.init_oracle_client(), soit en définissant la variable d'environnement TNS_ADMIN.

      Note :

      Aucun de ces paramètres n'est nécessaire et vous n'avez pas besoin de modifier sqlnet.ora si vous placez tous les fichiers de configuration dans le répertoire network/admin.
  2. Dans votre application Python, définissez les paramètres d'initialisation et de connexion suivants pour vous connecter à l'instance Autonomous Database :
    • config_dir : Spécifie le répertoire de configuration lorsque vous placez les fichiers de configuration. Cela n'est requis que lorsque les fichiers de configuration sont placés dans un répertoire en dehors du répertoire de configuration du client instantané network/admin.
    • dsn : Spécifie l'alias de réseau voulu à partir du fichier tnsnames.ora.
    • password : Spécifie le mot de passe de l'utilisateur de la base de données.
    • user : Spécifie l'utilisateur de base de données.

    Dans le premier cas pour le placement des fichiers de configuration, connectez-vous à l'instance Autonomous Database à l'aide de vos données d'identification de base de données en réglant le paramètre dsn à l'alias de réseau souhaité à partir de tnsnames.ora.

    Par exemple, pour vous connecter en tant qu'utilisateur ADMIN à l'aide de oracledb.init_oracle_client et vous connecter au nom du service de réseau db2024_low (où le nom du service se trouve dans tnsnames.ora) :

    oracledb.init_oracle_client()
       connection=oracledb.connect(
           user="admin",
           password=password,
           dsn="db2024_low")

    Lorsque les fichiers de configuration se trouvent dans un répertoire en dehors du répertoire de configuration du client instantané, définissez le paramètre config_dir lorsque vous appelez oracledb.init_oracle_client.

    Par exemple, sous Linux pour vous connecter en tant qu'utilisateur ADMIN à l'aide du nom du service de réseau db2024_low :

    oracledb.init_oracle_client(config_dir="/opt/OracleCloud/MYDB")
       connection=oracledb.connect(
          user="admin",
          password=password,
          dsn="db2024_low")

    Par exemple, sous Windows pour vous connecter en tant qu'utilisateur ADMIN à l'aide du nom du service de réseau db2024_low :

    oracledb.init_oracle_client(config_dir=r"C:\opt\OracleCloud\MYDB")
       connection=oracledb.connect(
          user="admin",
          password=password,
          dsn="db2024_low")

    L'utilisation d'une chaîne brute r"..." signifie que les barres obliques inverses sont traitées comme des séparateurs de répertoire.

Si vous êtes derrière un pare-feu, vous pouvez tunneliser les connexions TLS/SSL au moyen d'un mandataire à l'aide de HTTPS_PROXY dans le descripteur de connexion ou en définissant des attributs de connexion. La connexion réussie dépend de configurations de mandataire spécifiques. Oracle ne recommande pas l'utilisation d'un mandataire dans un environnement de production, en raison de l'incidence possible sur les performances. Pour plus d'informations, voir HTTPS_PROXY dans Informations de référence sur les services nets de base de données pour Oracle Database 19c ou Informations de référence sur les services nets de base de données pour Oracle Database 23ai.

En mode lourd, vous pouvez spécifier un mandataire en modifiant le fichier sqlnet.ora et en ajoutant une ligne :

SQLNET.USE_HTTPS_PROXY=on

En outre, modifiez tnsnames.ora et ajoutez un nom de mandataire HTTPS_PROXY et un port HTTPS_PROXY_PORT à la liste d'adresses de descripteur de connexion de tout nom de service que vous souhaitez utiliser.

Par exemple :

mydb_high=(description=
(address=(https_proxy=myproxy.example.com)
(https_proxy_port=80)
(protocol=tcps)(port=1522)(host=...)

Voir Activation du mode lourd python-oracledb pour plus d'informations sur le mode lourd.