Utiliser la bibliothèque cliente Java pour se connecter à Spanner Omni

La bibliothèque cliente Java pour Spanner fonctionne avec Spanner Omni de la même manière qu'avec Spanner. Ce document vous explique comment établir des connexions sécurisées à Spanner Omni en configurant la bibliothèque cliente Java. Vous établissez ces connexions en définissant des options client lorsque vous créez un client administratif ou un client de base de données.

La bibliothèque cliente Java est compatible avec les connexions en texte brut, TLS, TLS avec identifiants et mTLS.

Pour en savoir plus, consultez Premiers pas avec Spanner en Java dans la documentation Spanner.

Avant de commencer

Pour commencer à utiliser Spanner Omni en Java, utilisez la bibliothèque cliente Java version 6.119.0 ou ultérieure.

Si vous utilisez Maven sans la nomenclature (BOM), ajoutez les éléments suivants aux dépendances du fichier pom.xml :

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner</artifactId>
  <version>6.119.0</version>
</dependency>

Configurations de sécurité

La bibliothèque cliente Java Spanner est compatible avec quatre configurations de sécurité, qui définissent la façon dont la communication est chiffrée et authentifiée entre le client et Spanner Omni. Le tableau suivant décrit chaque configuration :

Configuration de la sécurité Description
Texte brut La communication n'est pas chiffrée.
TLS La communication est chiffrée à l'aide du protocole TLS (Transport Layer Security). Cette configuration nécessite que vous ajoutiez le certificat Spanner Omni CA au truststore Java, comme décrit dans Configurer le truststore Java.
TLS avec identifiants La communication est chiffrée à l'aide du protocole TLS, et l'authentification est effectuée à l'aide d'un nom d'utilisateur et d'un mot de passe.
mTLS La communication est chiffrée à l'aide du protocole TLS mutuel (mTLS). Cette configuration nécessite que vous fournissiez à la fois un certificat client et une clé privée client.

Configurer le truststore Java

Pour tous les types de connexion chiffrée (TLS, TLS avec identifiants et mTLS), vous devez ajouter le certificat CA Spanner Omni au truststore Java afin que le client puisse valider le certificat du serveur.

Pour ajouter le certificat CA au truststore Java par défaut, exécutez la commande suivante :

sudo keytool -import -trustcacerts -file ~/.spanner/certs/ca.crt -alias spanner-ca -keystore $JAVA_HOME/lib/security/cacerts

Vous pouvez également spécifier un truststore personnalisé lorsque vous exécutez l'application :

  1. Pour assurer la compatibilité avec d'autres services qui utilisent des autorités de certification (AC) standards, copiez le truststore Java par défaut :

    cp $JAVA_HOME/lib/security/cacerts /PATH_TO_CUSTOM_CACERTS

  2. Importez le certificat CA dans votre truststore personnalisé :

    keytool -import -trustcacerts -file ~/.spanner/certs/ca.crt -alias spanner-ca -keystore /PATH_TO_CUSTOM_CACERTS

  3. Spécifiez le truststore personnalisé à l'aide des propriétés système JVM lorsque vous exécutez l'application :

    java -Djavax.net.ssl.trustStore=/PATH_TO_CUSTOM_CACERTS -Djavax.net.ssl.trustStorePassword=changeit app

Configurer l'objet SpannerOptions

Lorsque vous configurez l'objet SpannerOptions pour créer un DatabaseClient ou un DatabaseAdminClient, spécifiez le point de terminaison Spanner Omni à l'aide de setHost() suivi de setType(SpannerOptions.InstanceType.OMNI).

Les exemples suivants montrent comment configurer l'objet SpannerOptions pour chaque configuration de sécurité compatible :

Texte brut

Pour établir une connexion en texte brut, spécifiez le point de terminaison Spanner Omni avec http:// et utilisez la méthode usePlainText() :

SpannerOptions options =
    SpannerOptions.newBuilder()
        .setHost("http://ENDPOINT") // Replace with your Spanner Omni endpoint
        .setType(SpannerOptions.InstanceType.OMNI)
        .usePlainText()
        .build();
Spanner spanner = options.getService();

TLS

Lorsque vous configurez l'objet SpannerOptions pour une connexion TLS, vous n'avez pas besoin de spécifier les identifiants (nom d'utilisateur et mot de passe). Spécifiez le point de terminaison Spanner Omni à l'aide de https:// :

SpannerOptions options =
    SpannerOptions.newBuilder()
        .setHost("https://ENDPOINT") // Replace with your Spanner Omni endpoint
        .setType(SpannerOptions.InstanceType.OMNI)
        .build();
Spanner spanner = options.getService();

TLS avec identifiants

Pour établir une connexion TLS avec authentification par nom d'utilisateur et mot de passe, spécifiez le point de terminaison Spanner Omni à l'aide de https://, et le nom d'utilisateur et le mot de passe à l'aide de la méthode login() :

SpannerOptions options =
    SpannerOptions.newBuilder()
        .setHost("https://ENDPOINT") // Replace with your Spanner Omni endpoint
        .setType(SpannerOptions.InstanceType.OMNI)
        .login("USERNAME", "PASSWORD".toCharArray())
        .build();
Spanner spanner = options.getService();

mTLS

 Pour utiliser une connexion mTLS, convertissez la clé générée par Spanner Omni dans un format compatible avec Java à l'aide de la commande suivante :

openssl pkcs8 -topk8 -in ~/.spanner/certs/client.key -out ~/.spanner/certs/java-client.key -nocrypt

L'exemple suivant montre comment configurer l'objet SpannerOptions pour utiliser un certificat client :

SpannerOptions options =
    SpannerOptions.newBuilder()
        .setHost("https://ENDPOINT") // Replace with your Spanner Omni endpoint
        .setType(SpannerOptions.InstanceType.OMNI)
        .useClientCert(
            "PATH_TO_CLIENT_CERT",
            "PATH_TO_CLIENT_CERT_KEY")
        .build();
Spanner spanner = options.getService();

Obtenir un client de base de données

Une fois l'objet SpannerOptions configuré, vous pouvez obtenir un client de base de données. Étant donné que Spanner Omni n'utilise pas d'ID de projet ni d'ID d'instance Google Cloud, spécifiez default pour l'ID de projet et l'ID d'instance lorsque vous créez un DatabaseId :

DatabaseId dbId = DatabaseId.of("default", "default", "DATABASE_ID");
DatabaseClient client = spanner.getDatabaseClient(dbId);