Comienza a usar la biblioteca de Google Auth

La biblioteca de autenticación de Google es una biblioteca cliente de autenticación de código abierto para Java. En este documento, se describe cómo usar esta biblioteca para autenticar tus aplicaciones de Java y acceder a los servicios de Google Cloud .

Si sigues esta guía, aprenderás a hacer lo siguiente:

  • Agrega las dependencias necesarias de la biblioteca de Auth a tu proyecto con Maven, Gradle o Simple Build Tool (SBT).
  • Autentica con varios métodos, con un enfoque en las credenciales predeterminadas de la aplicación (ADC).
  • Configura situaciones avanzadas de autenticación, como la federación de Workload Identity, la federación de identidades de personal y la suplantación de cuentas de servicio.
  • Genera y usa tokens con alcance reducido para limitar los permisos.
  • Integra las credenciales con las bibliotecas cliente HTTP de Google.

Esta documentación está dirigida a desarrolladores de Java. Para obtener detalles completos de la API, consulta la documentación de la API de la biblioteca de Google Auth.

La biblioteca de Google Auth para Java consta de cuatro artefactos:

  • google-auth-library-credentials contiene clases base e interfaces para las credenciales de Google.
  • google-auth-library-appengine contiene credenciales de App Engine y depende del SDK de App Engine.
  • google-auth-library-oauth2-http contiene una variedad de credenciales y métodos de utilidad, incluidas las capacidades para obtener credenciales predeterminadas de la aplicación. También proporciona el enfoque del servidor para generar tokens con alcance reducido.
  • google-auth-library-cab-token-generator proporciona el enfoque del cliente para generar tokens de alcance reducido.

Valida la configuración de credenciales

Cuando usas configuraciones de credenciales, como JSON, rutas de acceso de archivos o transmisiones, desde una fuente externa, debes validarlas. Proporcionar credenciales no validadas a las APIs de Google o a las bibliotecas cliente para la autenticación enGoogle Cloud puede comprometer la seguridad de tus sistemas y datos.

Para obtener más información, consulta Credenciales de origen externo. Credenciales predeterminadas.

Importa la biblioteca de Auth

Para importar la biblioteca de Auth, usa com.google.cloud:libraries-bom o la lista de materiales de la biblioteca de Google Auth con Maven o Gradle.

libraries-bom del SDK de Java

Para autenticarte en una biblioteca cliente del SDK de Java (por ejemplo, google-cloud-datastore) con la biblioteca de Auth, usa libraries-bom, que extraerá las versiones de la biblioteca de Auth compatibles con esa biblioteca cliente.

Por ejemplo, para importar la biblioteca de Auth con Maven usando un pom.xml, haz lo siguiente:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.53.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Si no usas libraries-bom ni otras bibliotecas cliente, importa los módulos de Auth directamente con la lista de materiales de la biblioteca de Google Auth.

Lista de materiales de la biblioteca de Google Auth

Puedes usar la lista de materiales de la biblioteca de Google Auth para asegurarte de que los módulos de Auth y las dependencias transitivas pertinentes sean compatibles.

Maven

Agrega lo siguiente a tu archivo pom.xml:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.auth</groupId>
      <artifactId>google-auth-library-bom</artifactId>
      <version>1.30.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

En la sección <dependencies>, puedes especificar cualquiera de los módulos de Auth que sean necesarios. Por ejemplo, para incluir el módulo google-auth-library-oauth2-http, agrega el siguiente elemento <dependency>:

<dependency>
  <groupId>com.google.auth</groupId>
  <!-- Let the BOM manage the module and dependency versions -->
  <!-- Replace with the module(s) that are needed -->
  <artifactId>google-auth-library-oauth2-http</artifactId>
</dependency>

Reemplaza google-auth-library-oauth2-http en el ejemplo por google-auth-library-credentials o google-auth-library-appengine, según las necesidades de tu aplicación.

Gradle

Al igual que en Maven, los usuarios de Gradle pueden usar google-auth-library-bom para administrar las versiones de las dependencias y garantizar la compatibilidad entre los diferentes módulos de google-auth-library.

Para usar la BoM con Gradle, agrégala como una dependencia platform. Luego, agrega los módulos google-auth-library que necesites. La BoM garantiza que las versiones de todos los módulos que usas sean compatibles. Por ejemplo, agrega lo siguiente a tu archivo build.gradle:

dependencies {
    // The BOM will manage the module versions and transitive dependencies
    implementation platform('com.google.auth:google-auth-library-bom:1.30.1')
    // Replace with the module(s) that are needed
    implementation 'com.google.auth:google-auth-library-oauth2-http'
}

Scala

A diferencia de Maven y Gradle, SBT (Scala Build Tool) no admite las listas de materiales (BOM) de Maven. Como resultado, cuando usas Scala, no puedes importar google-auth-library-bom para controlar automáticamente las versiones compatibles de los módulos de la biblioteca de Auth y sus dependencias transitivas.

En cambio, deberás agregar cada submódulo requerido directamente a tu archivo build.sbt. Es fundamental especificar y alinear de forma explícita las versiones de todos los módulos google-auth-library que uses. Si no mantienes las versiones coherentes, se pueden producir conflictos de versiones entre las dependencias transitivas, lo que podría causar comportamientos inesperados o errores de tiempo de ejecución en tu aplicación.

Si usas SBT, agrega esto a tus dependencias:

// Replace this with the implementation module that suits your needs
libraryDependencies += "com.google.auth" % "google-auth-library-oauth2-http" % "1.30.1"

Migra de GoogleCredential a GoogleCredentials

GoogleCredential de google-api-java-client dejó de estar disponible y GoogleCredentials es el reemplazo recomendado.

Crea una instancia de GoogleCredentials con las credenciales predeterminadas de la aplicación (ADC). Este es el enfoque recomendado:

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();

La forma en que usas GoogleCredentials depende de la biblioteca cliente:

Credencial predeterminada de la aplicación

La biblioteca de Google Auth proporciona una implementación de las credenciales predeterminadas de la aplicación (ADC) para Java. Las ADC proporcionan una forma de obtener credenciales de autorización para llamar a las APIs de Google.

Usa las ADC cuando tu aplicación requiera un nivel de identidad y autorización coherente, independientemente del usuario. Te recomendamos que uses ADC para autorizar llamadas a las API de Cloud, en especial cuando compilas aplicaciones en Google Cloud.

El ADC también admite la federación de Workload Identity, lo que permite que las aplicaciones accedan a recursos de plataformas externas, como Amazon Web Services (AWS), Microsoft Azure o cualquier proveedor de identidad que admita OpenID Connect (OIDC). Google Cloud Recomendamos la federación de Workload Identity para entornos que no son deGoogle Cloud , ya que elimina la necesidad de descargar, administrar y almacenar claves privadas de cuentas de servicio de forma local.

Obtén credenciales predeterminadas de la aplicación

Para obtener credenciales predeterminadas de la aplicación, usa GoogleCredentials.getApplicationDefault() o GoogleCredentials.getApplicationDefault(HttpTransportFactory). Estos métodos devuelven credenciales predeterminadas de la aplicación para identificar y autorizar toda la aplicación.

Para encontrar las credenciales predeterminadas de la aplicación, se buscan los siguientes elementos en este orden:

  1. Archivo de credenciales al que apunta la variable de entorno GOOGLE_APPLICATION_CREDENTIALS
  2. Credenciales que proporciona el comando gcloud auth application-default login del SDK de Google Cloud
  3. Son las credenciales integradas de Google App Engine.
  4. Google Cloud Credenciales integradas en el shell.
  5. Son las credenciales integradas de Google Compute Engine.
    • Para omitir esta verificación, configura la variable de entorno NO_GCE_CHECK=true.
    • Personaliza la dirección del servidor de metadatos configurando la variable de entorno GCE_METADATA_HOST=<hostname>.

Carga explícita de credenciales

Para obtener credenciales de una clave JSON de cuenta de servicio, usa GoogleCredentials.fromStream(InputStream) o GoogleCredentials.fromStream(InputStream, HttpTransportFactory), como se muestra en el siguiente ejemplo de código.

Las credenciales se deben actualizar antes de que esté disponible el token de acceso.

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));
credentials.refreshIfExpired();
AccessToken token = credentials.getAccessToken();
// OR
AccessToken token = credentials.refreshAccessToken();

Suplantación de credenciales

Usa ImpersonatedCredentials para permitir que una credencial (la principal) actúe en nombre de una cuenta de servicio (el destino). Esto permite que la principal acceda a los recursos como el destino, sin necesidad de la clave privada del destino.

Para usar ImpersonatedCredentials, debes cumplir con los siguientes requisitos:

  • El proyecto de la principal debe tener habilitada la API de IAMCredentials.
  • El principal debe tener el rol de Service Account Token Creator (Identity and Access Management) en la cuenta de servicio de destino.

En el siguiente muestra de código, se crea ImpersonatedCredentials. La credencial de la principal se obtiene de las credenciales predeterminadas de la aplicación (ADC). Luego, los ImpersonatedCredentials resultantes se usan para acceder a Google Cloud Storage como la cuenta de servicio de destino.

// The principal (ADC) has the Service Account Token Creator role on the target service account.
GoogleCredentials sourceCredentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList("https://www.googleapis.com/auth/iam"));

ImpersonatedCredentials credentials =
    ImpersonatedCredentials.newBuilder()
        .setSourceCredentials(sourceCredentials)
        .setTargetPrincipal(
            "impersonated-account@project.iam.gserviceaccount.com")
        .setScopes(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"))
        .build();

Storage storage =
    StorageOptions.newBuilder().setProjectId("project-id").setCredentials(credentials).build()
        .getService();

for (Bucket b : storage.list().iterateAll()) {
  System.out.println(b);
}

Federación de identidades para cargas de trabajo

La federación de Workload Identity permite que tu aplicación acceda a recursos de Google Cloud Amazon Web Services (AWS), Microsoft Azure o cualquier proveedor de identidad que admita OpenID Connect (OIDC).

Por lo general, las aplicaciones que se ejecutan fuera de Google Cloud usan claves de cuentas de servicio para acceder a los recursos de Google Cloud . Con la federación de identidades, tu carga de trabajo puede actuar en nombre de una cuenta de servicio. Esto permite que la carga de trabajo externa acceda directamente a los recursos, lo que elimina la carga de mantenimiento y seguridad asociada con las claves de cuentas de servicio. Google Cloud

Accede a los recursos desde AWS

Para acceder a los recursos Google Cloud de Amazon Web Services (AWS), primero debes configurar la federación de Workload Identity. El proceso de configuración se detalla en Accede a los recursos desde AWS.

Como parte de ese proceso, generarás un archivo de configuración de credenciales. Este archivo contiene metadatos no sensibles que indican a la biblioteca cómo recuperar tokens externos de asunto y cómo intercambiarlos por tokens de acceso de la cuenta de servicio. Puedes generar el archivo con la Google Cloud CLI:

# Generate an AWS configuration file.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AWS_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --aws \
    --output-file /path/to/generated/config.json

Reemplaza lo siguiente:

  • PROJECT_NUMBER: Es el número del proyecto de Google Cloud .
  • POOL_ID: Es el ID del grupo de identidades para cargas de trabajo.
  • AWS_PROVIDER_ID: Es el ID del proveedor de AWS.
  • SERVICE_ACCOUNT_EMAIL: Es el correo electrónico de la cuenta de servicio que se representará.

El ejemplo genera el archivo de configuración en el archivo de salida especificado.

Si usas AWS IMDSv2, debes agregar una marca adicional --enable-imdsv2 al comando gcloud iam workload-identity-pools create-cred-config:

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/AWS_PROVIDER_ID \
    --service-account SERVICE_ACCOUNT_EMAIL \
    --aws \
    --output-file /path/to/generated/config.json \
    --enable-imdsv2

Ahora puedes usar la biblioteca de Auth para llamar a los recursos deGoogle Cloud desde AWS.

Accede a los recursos desde Microsoft Azure

Para acceder a los recursos Google Cloud de Microsoft Azure, primero debes configurar la federación de identidades para cargas de trabajo. El proceso de configuración se detalla en Accede a los recursos desde Azure.

Como parte de ese proceso, generarás un archivo de configuración de credenciales. Este archivo contiene metadatos no sensibles que indican a la biblioteca cómo recuperar tokens externos de asunto y cómo intercambiarlos por tokens de acceso de la cuenta de servicio. Puedes generar el archivo con la Google Cloud CLI:

# Generate an Azure configuration file.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AZURE_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --azure \
    --output-file /path/to/generated/config.json

Reemplaza lo siguiente:

  • PROJECT_NUMBER: Es el número del proyecto de Google Cloud .
  • POOL_ID: Es el ID del grupo de identidades para cargas de trabajo.
  • AZURE_PROVIDER_ID: Es el ID del proveedor de Azure.
  • SERVICE_ACCOUNT_EMAIL: Es el correo electrónico de la cuenta de servicio que se representará.

Este comando genera el archivo de configuración en el archivo de salida especificado.

Ahora puedes usar la biblioteca de Auth para llamar a recursos de Google CloudAzure.

Acceder a los recursos desde un proveedor de identidad de OIDC

Para acceder a los recursos Google Cloud desde un proveedor de identidad que admita OpenID Connect (OIDC), primero debes configurar la federación de Workload Identity como se detalla en Configura la federación de Workload Identity desde un proveedor de identidad de OIDC.

Como parte de ese proceso, generarás un archivo de configuración de credenciales con Google Cloud CLI. Este archivo contiene metadatos no sensibles que le indican a la biblioteca cómo recuperar tokens externos de asunto y cómo intercambiarlos por tokens de acceso de la cuenta de servicio.

En el caso de los proveedores de OIDC, la biblioteca de Auth puede recuperar tokens de OIDC de un archivo local (credenciales basadas en archivos), un servidor local (credenciales basadas en URLs) o una combinación de certificado X.509 y clave privada (credenciales basadas en certificados X.509).

Credenciales basadas en archivos

En el caso de las credenciales basadas en archivos, un proceso en segundo plano debe actualizar continuamente la ubicación del archivo con un nuevo token de OIDC antes de que caduque. En el caso de los tokens con un ciclo de vida de una hora, debes actualizar el token en el archivo cada hora. Puedes almacenar el token directamente como texto sin formato o en formato JSON.

Para generar una configuración de OIDC basada en archivos, ejecuta el siguiente comando:

# Generate an OIDC configuration file for file-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-file <var>PATH_TO_OIDC_ID_TOKEN</var> \
    # Optional arguments for file types. Default is "text":
    # --credential-source-type "json" \
    # Optional argument for the field that contains the OIDC credential.
    # This is required for json.
    # --credential-source-field-name "id_token" \
    --output-file /path/to/generated/config.json

Reemplaza lo siguiente:

  • PROJECT_NUMBER: Es el número del proyecto de Google Cloud .
  • POOL_ID: Es el ID del grupo de identidades para cargas de trabajo.
  • OIDC_PROVIDER_ID: Es el ID del proveedor de OIDC.
  • SERVICE_ACCOUNT_EMAIL: Es el correo electrónico de la cuenta de servicio que se representará.
  • PATH_TO_OIDC_ID_TOKEN: Es la ruta de acceso que se usa para recuperar el token de OIDC.

Este comando genera el archivo de configuración en el archivo de salida especificado.

Credenciales basadas en URL

En el caso de las credenciales provenientes de URLs, un servidor local debe alojar un extremo GET que proporcione un token de OIDC en texto sin formato o en formato JSON. Puedes especificar encabezados HTTP adicionales para enviar en la solicitud de token, si el extremo lo requiere.

Para generar una configuración de identidad de carga de trabajo de OIDC basada en URL, ejecuta el siguiente comando:

# Generate an OIDC configuration file for URL-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-url <var>URL_TO_GET_OIDC_TOKEN</var> \
    --credential-source-headers <var>HEADER_KEY=HEADER_VALUE</var> \
    # Optional arguments for file types. Default is "text":
    # --credential-source-type "json" \
    # Optional argument for the field that contains the OIDC credential.
    # This is required for json.
    # --credential-source-field-name "id_token" \
    --output-file /path/to/generated/config.json

Reemplaza lo siguiente:

  • PROJECT_NUMBER: Es el número del proyecto de Google Cloud .
  • POOL_ID: Es el ID del grupo de identidades para cargas de trabajo.
  • OIDC_PROVIDER_ID: Es el ID del proveedor de OIDC.
  • SERVICE_ACCOUNT_EMAIL: Es el correo electrónico de la cuenta de servicio que se representará.
  • URL_TO_GET_OIDC_TOKEN: Es la URL del extremo del servidor local al que se debe llamar para recuperar el token de OIDC.
  • HEADER_KEY y HEADER_VALUE: Son los pares clave-valor de encabezado adicionales que se pasarán junto con la solicitud GET a URL_TO_GET_OIDC_TOKEN, por ejemplo, Metadata-Flavor=Google.

Ahora puedes usar la biblioteca de Auth para llamar a recursos deGoogle Cloud desde un proveedor de OIDC.

Accede a recursos con credenciales provenientes de certificados X.509

En el caso de las credenciales basadas en certificados X.509, la biblioteca de autenticación usa un certificado X.509 y una clave privada para demostrar la identidad de tu aplicación. Los certificados X.509 incluyen una fecha de vencimiento y se deben renovar antes de que venzan para mantener el acceso.

Para obtener más información, consulta la documentación oficial.

Genera archivos de configuración para la federación de X.509

Para configurar credenciales basadas en certificados X.509, debes generar dos archivos separados: un archivo de configuración de credenciales principal y un archivo de configuración de certificados.

  • El archivo de configuración de credenciales principal contiene los metadatos necesarios para la autenticación. Este archivo también hace referencia al archivo de configuración del certificado.
  • El archivo de configuración del certificado especifica las rutas de acceso al certificado X.509, la clave privada y la cadena de confianza.

El comando gcloud iam workload-identity-pools create-cred-config se puede usar para crear ambos.

La ubicación en la que gcloud crea el archivo de configuración del certificado depende de si usas la marca --credential-cert-configuration-output-file.

Si omites la marca --credential-cert-configuration-output-file, gcloud crea el archivo de configuración del certificado en una ubicación predeterminada y conocida que la biblioteca de Auth puede descubrir automáticamente. Este enfoque es adecuado para la mayoría de los casos de uso. El archivo de configuración de credenciales predeterminado se llama config.json y el archivo de configuración de certificados predeterminado se llama certificate_config.json.

Por ejemplo, ejecuta el siguiente comando para crear los archivos de configuración con el comportamiento predeterminado:

gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-trust-chain-path "<var>PATH_TO_TRUST_CHAIN</var>" \
    --output-file /path/to/config.json

Reemplaza lo siguiente:

  • PROJECT_NUMBER: Es el número del proyecto de Google Cloud .
  • POOL_ID: Es el ID del grupo de identidades para cargas de trabajo.
  • PROVIDER_ID: Es el ID del proveedor.
  • SERVICE_ACCOUNT_EMAIL: Es el correo electrónico de la cuenta de servicio que se representará.
  • PATH_TO_CERTIFICATE: Es la ruta de acceso en la que se encuentra tu certificado X.509 de hoja.
  • PATH_TO_PRIVATE_KEY: Es la ruta de acceso en la que se encuentra la clave privada correspondiente para el certificado de hoja.
  • PATH_TO_TRUST_CHAIN: Es la ruta de acceso al archivo de la cadena de confianza del certificado X.509. Este archivo debe estar en formato PEM y contener los certificados intermedios necesarios para completar la cadena de confianza entre el certificado de hoja y el almacén de confianza configurado en el grupo de la federación de identidades para cargas de trabajo. El certificado de hoja es opcional en este archivo.

Este comando genera el siguiente resultado:

  • /path/to/config.json: Se creó en la ruta de acceso que especificaste. Este archivo contendrá "use_default_certificate_config": true para indicarle a los clientes que busquen la configuración del certificado en la ruta predeterminada.
  • certificate_config.json: Se crea en la ruta de configuración predeterminada de Google Cloud CLI, que suele ser ~/.config/gcloud/certificate_config.json en Linux y macOS, o %APPDATA%\gcloud\certificate_config.json en Windows.

Comportamiento de ubicación personalizada

Si necesitas almacenar el archivo de configuración del certificado en una ubicación no predeterminada, usa la marca --credential-cert-configuration-output-file.

Comando de ejemplo (ubicación personalizada):

gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-trust-chain-path "<var>PATH_TO_TRUST_CHAIN</var>" \
    --credential-cert-configuration-output-file "/custom/path/cert_config.json" \
    --output-file /path/to/config.json

Este comando genera el siguiente resultado:

  • /path/to/config.json: creado en la ruta de acceso que especificaste. Este archivo contendrá un campo "certificate_config_location" que apunta a tu ruta de acceso personalizada.
  • cert_config.json: Se creó en /custom/path/cert_config.json, según lo especifica la marca.

Ahora puedes usar la biblioteca de Auth para llamar a los recursos deGoogle Cloud con credenciales provenientes de certificados X.509.

Usa credenciales basadas en ejecutables con OIDC y SAML

En el caso de las credenciales basadas en ejecutables, se usa un ejecutable local para recuperar el token de terceros. El ejecutable debe proporcionar un token de ID de OIDC o una aserción SAML válidos y no vencidos en formato JSON a stdout.

Para usar credenciales basadas en ejecutables, la variable de entorno GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES debe establecerse en 1.

Para generar una configuración de identidad de carga de trabajo basada en un ejecutable, ejecuta el siguiente comando:

# Generate a configuration file for executable-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account=<var>SERVICE_ACCOUNT_EMAIL</var> \
    --subject-token-type=<var>SUBJECT_TOKEN_TYPE</var> \
    # The absolute path for the program, including arguments.
    # e.g. --executable-command="/path/to/command --foo=bar"
    --executable-command=<var>EXECUTABLE_COMMAND</var> \
    # Optional argument for the executable timeout. Defaults to 30s.
    # --executable-timeout-millis=<var>EXECUTABLE_TIMEOUT</var> \
    # Optional argument for the absolute path to the executable output file.
    # See below on how this argument impacts the library behaviour.
    # --executable-output-file=<var>EXECUTABLE_OUTPUT_FILE</var> \
    --output-file /path/to/generated/config.json

Reemplaza lo siguiente:

  • PROJECT_NUMBER: Es el número del proyecto de Google Cloud .
  • POOL_ID: Es el ID del grupo de identidades para cargas de trabajo.
  • PROVIDER_ID: Es el ID del proveedor de OIDC o SAML.
  • SERVICE_ACCOUNT_EMAIL: Es el correo electrónico de la cuenta de servicio que se representará.
  • SUBJECT_TOKEN_TYPE: Es el tipo de token del asunto.
  • EXECUTABLE_COMMAND: Es el comando completo que se ejecutará, incluidos los argumentos. Debe ser una ruta de acceso absoluta al programa.

La marca --executable-timeout-millis es opcional y especifica la duración (en milisegundos) durante la cual la biblioteca de Auth esperará a que finalice el ejecutable. Si no se proporciona, el valor predeterminado es 30 segundos. El valor máximo permitido es de dos minutos y el mínimo es de cinco segundos.

La marca opcional --executable-output-file especifica una ruta de acceso para almacenar en caché la respuesta de credenciales de terceros del ejecutable. El almacenamiento en caché ayuda a mejorar el rendimiento, ya que las bibliotecas de Auth primero verifican este archivo para detectar credenciales válidas y no vencidas antes de ejecutar el archivo ejecutable. Si existen credenciales válidas almacenadas en caché, las bibliotecas las usan, lo que evita ejecuciones innecesarias.

Tu archivo ejecutable debe escribir la respuesta de credenciales en este archivo. Las bibliotecas de autenticación solo leen desde esta ubicación. El contenido del archivo debe coincidir con el formato JSON esperado.

Para recuperar el token de terceros, la biblioteca ejecutará el archivo ejecutable con el comando especificado. El resultado del ejecutable debe cumplir con el formato de respuesta especificado en los siguientes ejemplos y debe generar la respuesta en stdout.

Esta es una respuesta de OIDC ejecutable exitosa de ejemplo:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

Y aquí tienes un ejemplo de una respuesta SAML ejecutable exitosa:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}

Cuando especificas un archivo de salida con el argumento --executable-output-file en la configuración de credenciales, las respuestas ejecutables correctas deben incluir un campo expiration_time. Esto permite que la biblioteca de Auth almacene en caché y administre de manera eficaz la validez de las credenciales almacenadas en ese archivo.

Esta es una respuesta de error ejecutable de ejemplo:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Todos estos campos son obligatorios para una respuesta de error. La biblioteca usa los campos de código y mensaje como parte de una excepción que se arroja.

Resumen de los campos de formato de respuesta: * version: Es la versión del resultado de JSON. Solo se admite la versión 1. * success: Cuando es verdadero, la respuesta debe incluir el token de terceros y el tipo de token. La respuesta también debe incluir el campo expiration_time si se especificó un archivo de salida en la configuración de credenciales. El ejecutable también debe salir con un código de salida de 0. Cuando es falso, la respuesta debe incluir el código de error y los campos del mensaje, y salir con un valor distinto de cero. * token_type: En este campo, se especifica el tipo de token del sujeto de terceros. Debe ser urn:ietf:params:oauth:token-type:jwt, urn:ietf:params:oauth:token-type:id_token o urn:ietf:params:oauth:token-type:saml2. * id_token: Es el token de OIDC de terceros. * saml_response: La respuesta SAML de terceros. * expiration_time: Es el tiempo de vencimiento del token del sujeto de terceros en segundos (tiempo de la época de Unix). * code: Es la cadena del código de error. * message: Es el mensaje de error.

Todos los tipos de respuesta deben incluir los campos version y success. * Las respuestas exitosas deben incluir token_type y uno de los siguientes elementos: id_token o saml_response. El campo expiration_time también debe estar presente si se especificó un archivo de salida en la configuración de credenciales. * Las respuestas de error deben incluir los campos code y message.

La biblioteca propaga las siguientes variables de entorno cuando ejecuta el ejecutable:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: El campo de público de la configuración de las credenciales. Siempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: Este tipo de token del asunto esperado. Siempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL: Es la dirección de correo electrónico de la cuenta de servicio. Solo está presente cuando se usa el robo de identidad de cuentas de servicio.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: Es la ubicación del archivo de salida de la configuración de credenciales. Solo está presente cuando se especifica en la configuración de credenciales.

El ejecutable puede usar estas variables de entorno para evitar la codificación de estos valores.

Consideraciones de seguridad

Se recomiendan las siguientes prácticas de seguridad:

  • Evita que los procesos no autorizados ejecuten el archivo ejecutable, ya que este generará credenciales sensibles para esos procesos y sus usuarios a través de stdout.
  • Evita que los procesos no autorizados alteren la configuración o la invocación del ejecutable.

Debido a la complejidad del uso de credenciales basadas en ejecutables, te recomendamos que utilices otros mecanismos compatibles, como fuentes de archivos o URLs, para proporcionar credenciales de terceros, a menos que no cumplan con tus requisitos específicos.

Ahora puedes usar la biblioteca de Auth para llamar a recursos deGoogle Cloud desde un proveedor de OIDC o SAML.

Usa un proveedor personalizado con OIDC y SAML

Se puede usar una implementación personalizada de IdentityPoolSubjectTokenSupplier mientras se compila IdentityPoolCredentials para proporcionar un token de asunto que se pueda intercambiar por un token de acceso de Google Cloud . El proveedor debe devolver un token de asunto válido y no vencido cuando se lo llame con la credencial de Google Cloud.

IdentityPoolCredentials no almacena en caché el token devuelto, por lo que debes implementar lógica de almacenamiento en caché en el proveedor de tokens para evitar varias solicitudes del mismo token de asunto.

import java.io.IOException;

public class CustomTokenSupplier implements IdentityPoolSubjectTokenSupplier {

  @Override
  public String getSubjectToken(ExternalAccountSupplierContext context) throws IOException {
    // Any call to the supplier passes a context object with the requested
    // audience and subject token type.
    string audience = context.getAudience();
    string tokenType = context.getSubjectTokenType();

    try {
      // Return a valid, unexpired token for the requested audience and token type.
      // Note that IdentityPoolCredentials don't cache the subject token so
      // any caching logic needs to be implemented in the token supplier.
      return retrieveToken(audience, tokenType);
    } catch (Exception e) {
      // If token is unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  private String retrieveToken(string tokenType, string audience) {
    // Retrieve a subject token of the requested type for the requested audience.
  }
}

CustomTokenSupplier tokenSupplier = new CustomTokenSupplier();
IdentityPoolCredentials identityPoolCredentials =
    IdentityPoolCredentials.newBuilder()
        .setSubjectTokenSupplier(tokenSupplier) // Sets the token supplier.
        .setAudience(...) // Sets the Google Cloud audience.
        .setSubjectTokenType(SubjectTokenTypes.JWT) // Sets the subject token type.
        .build();

Donde el público es:

//iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

Reemplaza lo siguiente:

  • PROJECT_NUMBER: Es el número del proyecto de Google Cloud .
  • WORKLOAD_POOL_ID: Es el ID del grupo de identidades para cargas de trabajo.
  • PROVIDER_ID: Es el ID del proveedor.

También puedes encontrar los valores del público, la URL de suplantación de la cuenta de servicio y cualquier otro campo del compilador generando un archivo de configuración de credenciales con la CLI de gcloud.

Usa un proveedor personalizado con AWS

Se puede proporcionar una implementación personalizada de AwsSecurityCredentialsSupplier cuando se inicializa AwsCredentials. Si se proporciona, la instancia de AwsCredentials diferirá al proveedor para recuperar las credenciales de seguridad de AWS que se intercambiarán por un token de acceso deGoogle Cloud . El proveedor debe devolver credenciales de seguridad de AWS válidas y no vencidas cuando se lo llame con la credencial Google Cloud .

AwsCredentials no almacenes en caché las credenciales de seguridad o la región de AWS que se devuelven, por lo que debes implementar la lógica de almacenamiento en caché en el proveedor para evitar varias solicitudes de los mismos recursos.

class CustomAwsSupplier implements AwsSecurityCredentialsSupplier {
  @Override
  AwsSecurityCredentials getAwsSecurityCredentials(ExternalAccountSupplierContext context) throws IOException {
    // Any call to the supplier passes a context object with the requested
    // audience.
    String audience = context.getAudience();

    try {
      // Return valid, unexpired AWS security credentials for the requested audience.
      // Note that AwsCredentials don't cache the AWS security credentials so
      // any caching logic needs to be implemented in the credentials' supplier.
      return retrieveAwsSecurityCredentials(audience);
    } catch (Exception e) {
      // If credentials are unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  @Override
  String getRegion(ExternalAccountSupplierContext context) throws IOException {
    try {
      // Return a valid AWS region. i.e. "us-east-2".
      // Note that AwsCredentials don't cache the region so
      // any caching logic needs to be implemented in the credentials' supplier.
      return retrieveAwsRegion();
    } catch (Exception e) {
      // If region is unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  private AwsSecurityCredentials retrieveAwsSecurityCredentials(string audience) {
    // Retrieve Aws security credentials for the requested audience.
  }

  private String retrieveAwsRegion() {
    // Retrieve current AWS region.
  }
}

CustomAwsSupplier awsSupplier = new CustomAwsSupplier();
AwsCredentials credentials = AwsCredentials.newBuilder()
    .setSubjectTokenType(SubjectTokenTypes.AWS4) // Sets the subject token type.
    .setAudience(...) // Sets the Google Cloud audience.
    .setAwsSecurityCredentialsSupplier(supplier) // Sets the supplier.
    .build();

Donde el público es: //iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

Reemplaza lo siguiente:

  • PROJECT_NUMBER: Es el número del proyecto de Google Cloud .
  • WORKLOAD_POOL_ID: Es el ID del grupo de identidades para cargas de trabajo.
  • PROVIDER_ID: Es el ID del proveedor.

También puedes encontrar los valores del público, la URL de suplantación de la cuenta de servicio y cualquier otro campo del compilador generando un archivo de configuración de credenciales con la CLI de gcloud.

Duración del token configurable

Cuando creas una configuración de credenciales con la federación de identidades para cargas de trabajo usando la suplantación de identidad de la cuenta de servicio, puedes proporcionar un argumento opcional para configurar la vida útil del token de acceso de la cuenta de servicio.

Para generar la configuración con una vida útil del token configurable, ejecuta el siguiente comando (en este ejemplo, se usa una configuración de AWS, pero la vida útil del token se puede configurar para todos los proveedores de federación de Workload Identity):

  # Generate an AWS configuration file with configurable token lifetime.
  gcloud iam workload-identity-pools create-cred-config \
      projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AWS_PROVIDER_ID</var> \
      --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
      --aws \
      --output-file /path/to/generated/config.json \
      --service-account-token-lifetime-seconds <var>TOKEN_LIFETIME</var>

Reemplaza lo siguiente:

  • PROJECT_NUMBER: Es el número del proyecto de Google Cloud .
  • POOL_ID: Es el ID del grupo de identidades para cargas de trabajo.
  • AWS_PROVIDER_ID: Es el ID del proveedor de AWS.
  • SERVICE_ACCOUNT_EMAIL: Es el correo electrónico de la cuenta de servicio que se representará.
  • TOKEN_LIFETIME: Es la duración seleccionada del ciclo de vida del token de acceso a la cuenta de servicio en segundos.

La marca service-account-token-lifetime-seconds es opcional. Si no se proporciona, la marca se establece de forma predeterminada en una hora. El valor mínimo permitido es 600 (10 minutos) y el valor máximo permitido es 43,200 (12 horas). Si necesitas una vida útil de más de una hora, debes agregar la cuenta de servicio como un valor permitido en un servicio de políticas de la organización que aplique la restricción constraints/iam.allowServiceAccountCredentialLifetimeExtension.

Configurar un ciclo de vida corto (por ejemplo, 10 minutos) hace que la biblioteca inicie todo el flujo de intercambio de tokens cada 10 minutos. Esto llama al proveedor de tokens externo incluso si el token externo no venció.

Usa credenciales de personal autorizado de una cuenta externa

Las credenciales de usuario autorizado de la cuenta externa te permiten acceder con un navegador web a una cuenta de proveedor de identidad externo con gcloud CLI y crear una configuración para que la biblioteca de autenticación la use.

Para generar una configuración de identidad de personal del usuario autorizado de una cuenta externa, ejecuta el siguiente comando:

gcloud auth application-default login --login-config=LOGIN_CONFIG

En el que se debe sustituir la siguiente variable:

Se abrirá un flujo del navegador para que accedas con el proveedor de identidad externo configurado. Luego, almacena la configuración del usuario autorizado de la cuenta externa en la ubicación conocida de ADC.

Luego, la biblioteca de Auth usará el token de actualización proporcionado en la configuración para generar y actualizar un token de acceso para llamar a los servicios de Google Cloud .

La vida útil predeterminada del token de actualización es de una hora. Después de esto, debes generar una nueva configuración desde gcloud CLI. Puedes modificar la vida útil cambiando la duración de la sesión del grupo de trabajadores y establecerla en hasta 12 horas.

Usa identidades externas

Puedes usar identidades externas con Application Default Credentials. Para usar identidades externas con las credenciales predeterminadas de la aplicación, genera el archivo de configuración de credenciales JSON para tu identidad externa como se describe en la sección Federación de identidades para cargas de trabajo. Una vez que se genere, almacena la ruta de acceso a este archivo en la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json

Ahora la biblioteca puede elegir el tipo correcto de cliente y, luego, inicializar las credenciales desde el contexto que proporciona el archivo de configuración.

GoogleCredentials googleCredentials = GoogleCredentials.getApplicationDefault();

String projectId = "your-project-id";
String url = "https://storage.googleapis.com/storage/v1/b?project=" + projectId;

HttpCredentialsAdapter credentialsAdapter = new HttpCredentialsAdapter(googleCredentials);
HttpRequestFactory requestFactory = new NetHttpTransport().createRequestFactory(credentialsAdapter);
HttpRequest request = requestFactory.buildGetRequest(new GenericUrl(url));

JsonObjectParser parser = new JsonObjectParser(GsonFactory.getDefaultInstance());
request.setParser(parser);

HttpResponse response = request.execute();
System.out.println(response.parseAsString());

También puedes inicializar de forma explícita los clientes de cuentas externas con el archivo de configuración generado.

ExternalAccountCredentials credentials =
    ExternalAccountCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));

Consideraciones de seguridad

Esta biblioteca no realiza ninguna validación en los campos token_url, token_info_url o service_account_impersonation_url de la configuración de credenciales. No te recomendamos que uses una configuración de credenciales que no hayas generado con gcloud CLI, a menos que verifiques que los campos de URL apunten a un dominio de googleapis.com.

Restringe el alcance con límites de acceso a las credenciales

La reducción del alcance con límites de acceso a credenciales permite restringir los permisos de Identity and Access Management (IAM) que puede usar una credencial de corta duración para Cloud Storage. Esto implica crear un objeto CredentialAccessBoundary que defina las restricciones que se aplican al token con permisos reducidos. El uso de credenciales con alcance reducido garantiza que los tokens en tránsito siempre tengan los privilegios mínimos. Consulta Principio de privilegio mínimo.

Crear una CredentialAccessBoundary

El límite de acceso a credenciales especifica a qué recursos puede acceder la credencial recién creada. También especifica un límite superior en los permisos disponibles para cada recurso. Incluye uno o más objetos AccessBoundaryRule.

En el siguiente fragmento, se muestra cómo inicializar un CredentialAccessBoundary con un AccessBoundaryRule. Esta regla especifica que el token con alcance reducido tendrá acceso de solo lectura a los objetos que comiencen con customer-a en el bucket bucket-123.

// Create the AccessBoundaryRule.
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
        CredentialAccessBoundary.AccessBoundaryRule.AvailabilityCondition.newBuilder().setExpression(expression).build())
        .build();

// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
        CredentialAccessBoundary.newBuilder().addRule(rule).build();

Patrón de uso común

El patrón de uso común implica un agente de tokens con acceso elevado. Este agente genera credenciales de alcance reducido a partir de credenciales de origen con mayor acceso. Luego, pasa los tokens de acceso de corta duración y alcance reducido a un consumidor de tokens a través de un canal autenticado seguro para el acceso limitado a los recursos de Google CloudStorage.

Genera tokens con permisos reducidos

Existen dos formas de generar tokens con permisos reducidos usando un CredentialAccessBoundary:

  • Del servidor (con DownscopedCredentials): El cliente llama al servicio de token de seguridad (STS) cada vez que se necesita un token con permisos reducidos. Esto es adecuado para aplicaciones en las que las reglas del límite de acceso para credenciales cambian con poca frecuencia o en las que se reutiliza una sola credencial con alcance reducido muchas veces. Una consideración clave es que cada cambio de regla requiere que realices una nueva llamada al STS. Este enfoque está disponible en la biblioteca google-auth-library-oauth2-http y no requiere dependencias adicionales. Esto facilita la integración. Es una buena opción si tu caso de uso no requiere los beneficios específicos del enfoque del cliente.

  • Del cliente (con ClientSideCredentialAccessBoundaryFactory): El cliente recupera material criptográfico una vez y, luego, genera varios tokens con alcance reducido de forma local. Esto minimiza las llamadas al STS y es más eficiente cuando las reglas del límite de acceso a credenciales cambian con frecuencia, ya que el cliente no necesita comunicarse con el STS para cada cambio de regla. Esto también es más eficiente para las aplicaciones que necesitan generar muchos tokens únicos con alcance reducido. Este enfoque está disponible en el módulo google-auth-library-cab-token-generator. Sin embargo, este módulo tiene su propio conjunto de dependencias. Estas dependencias pueden agregar complejidad a tu proyecto. Considera este enfoque si minimizar las llamadas a STS y generar numerosos tokens únicos son las principales preocupaciones. También deberás administrar las dependencias adicionales.

CAB del servidor

La clase DownscopedCredentials se puede usar para generar un token de acceso con permisos reducidos a partir de una credencial de origen y el objeto CredentialAccessBoundary.

// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
        .createScoped("https://www.googleapis.com/auth/cloud-platform");

// Create an Access Boundary Rule which will restrict the downscoped token to having read-only
// access to objects starting with "customer-a" in bucket "bucket-123".
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
            new AvailabilityCondition(expression, /* title= */ null, /* description= */ null))
        .build();

// Initialize the DownscopedCredentials class.
DownscopedCredentials downscopedCredentials =
    DownscopedCredentials.newBuilder()
        .setSourceCredential(sourceCredentials)
        .setCredentialAccessBoundary(CredentialAccessBoundary.newBuilder().addRule(rule).build())
        .build();

// Retrieve the downscoped access token.
// You will need to pass this to the Token Consumer.
AccessToken downscopedAccessToken = downscopedCredentials.refreshAccessToken();

CAB del cliente

En el caso de la CAB del cliente, se usa ClientSideCredentialAccessBoundaryFactory con una credencial de origen. Después de inicializar la fábrica, se puede llamar al método generateToken() varias veces con diferentes objetos CredentialAccessBoundary para crear varios tokens con permisos reducidos.

// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
        .createScoped("https://www.googleapis.com/auth/cloud-platform");

// Create an Access Boundary Rule which will restrict the downscoped token to having read-only
// access to objects starting with "customer-a" in bucket "bucket-123".
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
            new AvailabilityCondition(expression, /* title= */ null, /* description= */ null))
        .build();

// Initialize the ClientSideCredentialAccessBoundaryFactory.
ClientSideCredentialAccessBoundaryFactory factory =
    ClientSideCredentialAccessBoundaryFactory.newBuilder()
        .setSourceCredential(sourceCredentials)
        .build();

// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
        CredentialAccessBoundary.newBuilder().addRule(rule).build();

// Generate the downscoped access token.
// You will need to pass this to the Token Consumer.
AccessToken downscopedAccessToken = factory.generateToken(credentialAccessBoundary);

Usa tokens de acceso con permisos reducidos

Puedes configurar un agente de tokens en un servidor de una red privada. Varias cargas de trabajo (consumidores de tokens) en la misma red envían solicitudes autenticadas a ese agente para obtener tokens de alcance reducido. Estos tokens les permiten acceder a buckets de Google Cloud Storage específicos o modificarlos.

El agente crea instancias de credenciales de alcance reducido que pueden generar tokens de acceso de alcance reducido y de corta duración. Luego, pasa estos tokens al consumidor de tokens.

El consumidor de tokens puede usar estos tokens de acceso de alcance reducido con OAuth2Credentials o OAuth2CredentialsWithRefresh. Luego, puedes usar esta credencial para inicializar una instancia del cliente de almacenamiento y acceder a los recursos de Storage Google Cloudcon acceso restringido.

// You can pass an `OAuth2RefreshHandler` to `OAuth2CredentialsWithRefresh` that will allow the
// library to seamlessly handle downscoped token refreshes on expiration.
OAuth2CredentialsWithRefresh.OAuth2RefreshHandler handler =
        new OAuth2CredentialsWithRefresh.OAuth2RefreshHandler() {
    @Override
    public AccessToken refreshAccessToken() {
      // Retrieve the token from your Token Broker.
      return accessToken;
    }
};

// The downscoped token is retrieved from the token broker.
AccessToken downscopedToken = handler.refreshAccessToken();

// Build the OAuth2CredentialsWithRefresh from the downscoped token and pass a refresh handler
// to handle token expiration. Passing the original downscoped token or the expiry here is optional,
// because the refresh_handler will generate the downscoped token on demand.
OAuth2CredentialsWithRefresh credentials =
    OAuth2CredentialsWithRefresh.newBuilder()
        .setAccessToken(downscopedToken)
        .setRefreshHandler(handler)
        .build();

// Use the credentials with the Cloud Storage SDK.
StorageOptions options = StorageOptions.newBuilder().setCredentials(credentials).build();
Storage storage = options.getService();

// Call Cloud Storage APIs.
// Because we passed the downscoped credential, we will have limited read-only access to objects
// starting with "customer-a" in bucket "bucket-123".
storage.get(...)

Solo Cloud Storage admite límites de acceso a credenciales; otros servicios deGoogle Cloud no admiten esta función.

Usa credenciales con google-http-client

Las credenciales proporcionadas por com.google.auth:google-auth-library-oauth2-http se pueden usar con los clientes basados en HTTP de Google. Los clientes basados en HTTP de Google proporcionan un HttpCredentialsAdapter que se puede usar como un HttpRequestInitializer, el último argumento para sus compiladores.

import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.services.bigquery.Bigquery;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials);

Bigquery bq = new Bigquery.Builder(HTTP_TRANSPORT, JSON_FACTORY, requestInitializer)
    .setApplicationName(APPLICATION_NAME)
    .build();

Verifica tokens JWT (función beta)

Para verificar un token JWT, usa la clase TokenVerifier.

Cómo verificar una firma

Para verificar una firma, usa el TokenVerifier predeterminado:

import com.google.api.client.json.webtoken.JsonWebSignature;
import com.google.auth.oauth2.TokenVerifier;

TokenVerifier tokenVerifier = TokenVerifier.newBuilder().build();
try {
  JsonWebSignature jsonWebSignature = tokenVerifier.verify(tokenString);
  // Optionally, verify additional claims.
  if (!"expected-value".equals(jsonWebSignature.getPayload().get("additional-claim"))) {
    // Handle custom verification error.
  }
} catch (TokenVerifier.VerificationException e) {
  // The token is invalid.
}

Personaliza el TokenVerifier

Para personalizar un TokenVerifier, crea una instancia con su compilador:

import com.google.api.client.json.webtoken.JsonWebSignature;
import com.google.auth.oauth2.TokenVerifier;

TokenVerifier tokenVerifier = TokenVerifier.newBuilder()
  .setAudience("audience-to-verify")
  .setIssuer("issuer-to-verify")
  .build();
try {
  JsonWebSignature jsonWebSignature = tokenVerifier.verify(tokenString);
  // Optionally, verify additional claims.
  if (!"expected-value".equals(jsonWebSignature.getPayload().get("additional-claim"))) {
    // Handle custom verification error.
  }
} catch (TokenVerifier.VerificationException e) {
  // The token is invalid.
}

Para obtener más opciones, consulta la documentación de TokenVerifier.Builder.

google-auth-library-credentials

Este artefacto contiene clases base e interfaces para las credenciales de Google:

  • Credentials: Esta es la clase base para una identidad autorizada. Las implementaciones de esta clase pueden autorizar tu aplicación.
  • RequestMetadataCallback: Es la interfaz para la devolución de llamada que recibe el resultado de la Credentials.getRequestMetadata(URI, Executor, RequestMetadataCallback) asíncrona.
  • ServiceAccountSigner: Es la interfaz de un firmante de cuenta de servicio. Las implementaciones de esta clase pueden firmar arrays de bytes con las credenciales asociadas a una cuenta de servicio de Google.

google-auth-library-appengine

Este artefacto depende del SDK de App Engine (appengine-api-1.0-sdk). Úsalo solo para las aplicaciones que se ejecutan en entornos de App Engine que usan urlfetch. La clase AppEngineCredentials te permite autorizar tu aplicación de App Engine con una instancia de AppIdentityService.

Uso:

import com.google.appengine.api.appidentity.AppIdentityService;
import com.google.appengine.api.appidentity.AppIdentityServiceFactory;
import com.google.auth.Credentials;
import com.google.auth.appengine.AppEngineCredentials;

AppIdentityService appIdentityService = AppIdentityServiceFactory.getAppIdentityService();

Credentials credentials =
    AppEngineCredentials.newBuilder()
        .setScopes(...)
        .setAppIdentityService(appIdentityService)
        .build();

google-auth-library-cab-token-generator

Este módulo proporciona la clase ClientSideCredentialAccessBoundaryFactory, que permite la generación del cliente de tokens de alcance reducido para Cloud Storage con límites de acceso a las credenciales. Este enfoque es particularmente útil para las aplicaciones que requieren cambios frecuentes en las reglas del límite de acceso a credenciales o la generación de muchos tokens únicos con alcance reducido, ya que minimiza las llamadas al servicio de tokens de seguridad (STS). Para ver ejemplos de uso, consulta la sección CAB del cliente. Este módulo incluye su propio conjunto de dependencias. Evalúa si los beneficios de la reducción del alcance del cliente superan la complejidad adicional para tu caso de uso específico.