Eseguire l'autenticazione e connettersi a un database

Pertinente solo per la versione Enterprise di Cloud Firestore.

Requisiti di connessione

Per i client Cloud Firestore con compatibilità MongoDB sono necessari i seguenti elementi:

• I conducenti devono connettersi in modalità load balanced. In questo modo, i driver non tentano di comprendere la topologia esatta del server a cui si connettono.
• I driver devono connettersi con SSL abilitato.
• I driver devono disattivare le scritture ripetibili. Cloud Firestore con compatibilità MongoDB al momento non supporta le scritture ripetibili.

Recuperare la stringa di connessione

La stringa di connessione al database dipende dall'UID del database, dalla posizione del database e dal meccanismo di autenticazione. Le istruzioni seguenti descrivono come viene formata la stringa di connessione.

Nota :un database ha sia un ID database che un UID. L'ID database è il nome della risorsa che hai impostato quando hai creato un database. L'UID è un UUID4 generato dal sistema per il database.

La stringa di connessione esatta dipende dal meccanismo di autenticazione, ma la stringa di connessione di base utilizza il seguente formato:

mongodb://UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&tls=true&retryWrites=false

Puoi ottenere la stringa di connessione di base in uno dei seguenti modi:

Console Firebase

1. Nella console Firebase, vai alla pagina Database Firestore.

   Vai al database Firestore

2. Fai clic sul database da autenticare.
3. Nel riquadro Explorer, fai clic su Visualizza altro.
4. Seleziona Connettiti utilizzando gli strumenti MongoDB.
5. Copia la stringa di connessione.

gcloud

Utilizza gcloud firestore database describe per recuperare l'UID e le informazioni sulla posizione:

gcloud firestore databases describe \
--database=DATABASE_ID \
--format='yaml(locationId, uid)'

Sostituisci DATABASE_ID con l'ID database.

L'output include la posizione e l'UID del database. Utilizza queste informazioni per creare la stringa di connessione di base.

Utilizza la stringa di connessione di base e uno dei seguenti metodi per autenticarti e connetterti al tuo database:

• Nome utente e password (SCRAM)
• Compute Engine service account
• Libreria Google Auth

Connettersi con nome utente e password (SCRAM)

Segui questi passaggi per creare una credenziale utente per il tuo database e connetterti al database.

Prima di iniziare

Per ottenere le autorizzazioni necessarie per creare un utente, chiedi all'amministratore di concederti il ruolo IAM userCredsAdmin (roles/datastore.userCredsAdmin) sul database. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Crea un utente e connettiti a un database

Per creare un utente per il tuo database Cloud Firestore con compatibilità MongoDB, utilizza uno dei seguenti metodi:

Console Google Cloud

1. Nella console Google Cloud, vai alla pagina Database.

   Vai a Database

2. Seleziona un database dall'elenco.
3. Nel menu di navigazione, fai clic su Autenticazione.
4. Fai clic su Aggiungi utente.
5. Inserisci un nome utente.
6. Seleziona un ruolo per il nuovo utente.
7. Fai clic su Aggiungi.

   La password del nuovo utente verrà visualizzata nella finestra di dialogo di conferma.

   Attenzione:la password viene visualizzata una sola volta e non è recuperabile. Memorizza questa password per un uso futuro.

gcloud CLI

1. Per l'autenticazione con SCRAM, devi prima creare una credenziale utente. Utilizza il comando gcloud alpha firestore user-creds:

   gcloud alpha firestore user-creds create USERNAME --database=DATABASE_ID

   Sostituisci quanto segue:
   • USERNAME: il nome utente da creare.
   • DATABASE_ID: l'ID del database.

   L'output di questo comando include la password dell'utente.

   Attenzione:la password viene visualizzata una sola volta e non è recuperabile. Memorizza questa password per un uso futuro.

   L'output è simile al seguente:

   name: projects/PROJECT_NAME/databases/DATABASE_ID/userCreds/USERNAME
   resourceIdentity:
     principal: principal://firestore.googleapis.com/projects/PROJECT_NUMBER/name/databases/DATABASE_ID/userCreds/USERNAME
   securePassword: PASSWORD

2. Per impostazione predefinita, queste nuove credenziali utente non dispongono di autorizzazioni. Per l'accesso in lettura e scrittura al database, aggiungi il ruolo roles/datastore.user per questo database specifico:

   gcloud projects add-iam-policy-binding PROJECT_NAME \
   --member='principal://firestore.googleapis.com/projects/PROJECT_NUMBER/name/databases/DATABASE_ID/userCreds/USERNAME' \
   --role=roles/datastore.user \
   --condition='expression=resource.name == "projects/PROJECT_NAME/databases/DATABASE_ID",title="CONDITION_TITLE"'

   Sostituisci quanto segue:
   • PROJECT_NAME: il nome del progetto.
   • PROJECT_NUMBER: il numero di progetto.
   • DATABASE_ID: l'ID del database.
   • USERNAME: il nome utente che hai creato in precedenza.
   • CONDITION_TITLE: un titolo per questa condizione. Questa condizione limita l'accesso solo a questo database.

Utilizza la seguente stringa di connessione per connetterti al tuo database con SCRAM:

mongodb://USERNAME:[e-mail]:443/DATABASE_ID?loadBalanced=true&authMechanism=SCRAM-SHA-256&tls=true&retryWrites=false

Sostituisci quanto segue:

• USERNAME: il nome utente.
• PASSWORD: la password che hai generato per questo utente.
• UID: l'UID del database.
• LOCATION: la posizione del database.
• DATABASE_ID: l'ID del database.

Connettersi alla libreria di autenticazione Google

Il seguente codice campione registra un gestore di callback OIDC che utilizza la Google Cloud libreria OAuth standard.

Questa libreria ti consente di utilizzare diversi tipi di autenticazione (credenziali predefinite dell'applicazione, federazione delle identità per la forza lavoro).

Per questo è necessario aggiungere la libreria di autenticazione come dipendenza:

// Maven
<dependency>
  <groupId>com.google.auth</groupId>
  <artifactId>google-auth-library-oauth2-http</artifactId>
  <version>1.19.0</version>
</dependency>

// Gradle
implementation 'com.google.auth:google-auth-library-oauth2-http:1.19.0'

Il seguente esempio di codice mostra come connettersi:

val db = MongoClients.create(
    clientSettings(
      "DATABASE_UID",
      "LOCATION"
    ).build()
  ).getDatabase("DATABASE_ID")


/**
 * Creates a connection to a Firestore with MongoDB Compatibility database.
 * @param databaseUid The uid of the database to connect to as a string. For example: f116f93a-519c-208a-9a72-3ef6c9a1f081
 * @param locationId The location of the database to connect to, for example: nam5, us-central1, us-east4 etc...
 * @param environment Determines whether to try and fetch an authentication credential from the
 * Compute Engine VM metadata service or whether to call gcloud.
 */
private static MongoClientSettings.Builder clientSettings(
  String databaseUid: String
  String locationId:String
): MongoClientSettings.Builder {
  MongoCredential credential =
    MongoCredential.createOidcCredential(null)
      .withMechanismProperty(
        MongoCredential.OIDC_CALLBACK_KEY,
        new MongoCredential.OidcCallback() {
          @Override
          MongoCredential.OidcCallbackResult onRequest(
MongoCredential.OidcCallbackContext context) {
     // Customize this credential builder for additional credential types.
     GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
            return new MongoCredential.OidcCallbackResult(
         credentials.getAccessToken().getTokenValue(),
         Duration.between(Instant.now(),
credentials.getAccessToken().getExpirationTime().toInstant()));
          }
        },
      );
  return MongoClientSettings.builder()
    .hosts(listOf(ServerAddress(
        "$databaseUid.$locationId.firestore.goog", 443)))
    .credential(credential)
    .applyToClusterSettings(builder ->
         builder.mode(ClusterConnectionMode.LOAD_BALANCED))
    ).applyToSslSettings(ssl -> ssl.enabled(true)).retryWrites(false);
}

Sostituisci quanto segue:

• DATABASE_UID: il nome del progetto.
• LOCATION: la posizione del database.
• DATABASE_ID l'ID database.

Connettiti da una VM Compute Engine

Puoi autenticarti e connetterti al tuo database utilizzando un service account Compute Engine. Per farlo, crea un criterio IAM per il progetto Google Cloud che contiene il tuo database.

Prima di iniziare

Configura un service account gestito dall'utente per la tua VM:

• Per configurare il service account durante la creazione della VM, consulta Crea una VM che utilizza un service account gestito dall'utente.
• Per configurare il service account su una VM esistente, consulta Modifica il service account collegato.

Prendi nota dell'indirizzo email del service account.

Configurare le credenziali

Per concedere all'account di servizio il ruolo roles/datastore.user per la lettura e la scrittura in Cloud Firestore, esegui questo comando:

gcloud projects add-iam-policy-binding PROJECT_NAME --member="SERVICE_ACCOUNT_EMAIL" --role=roles/datastore.user

Sostituisci quanto segue:

• PROJECT_NAME: il nome del progetto.
• SERVICE_ACCOUNT_EMAIL: l'indirizzo email del service account che hai creato.

Costruisci la stringa di connessione

Utilizza il seguente formato per creare la stringa di connessione:

mongodb://DATABASE_UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&tls=true&retryWrites=false&authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:FIRESTORE

Sostituisci quanto segue:

• DATABASE_UID: il nome del progetto.
• LOCATION: la posizione del database.
• DATABASE_ID l'ID database.

Per ulteriori informazioni sul recupero dell'UID e della posizione, consulta Recuperare la stringa di connessione.

Connettiti con un token di accesso temporaneo

Puoi utilizzare un token di accesso temporaneo Google Cloud per eseguire strumenti di diagnostica come mongosh. Puoi utilizzare gcloud auth print-access-token per l'autenticazione con un token di accesso a breve termine. Questo token è valido per un'ora.

Ad esempio, utilizza il seguente comando per connetterti al tuo database con mongosh:

mongosh --tls \
      --username access_token --password $(gcloud auth print-access-token) \
      'mongodb://UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&authMechanism=PLAIN&authSource=$external&retryWrites=false'

Sostituisci quanto segue:

• DATABASE_UID: l'UID del database
• LOCATION: la posizione del database
• DATABASE_ID: un ID database