How to configure authentication for the Alibaba Cloud SDK for Java V1.0 - Alibaba Cloud SDK

El Alibaba Cloud SDK for Java V1.0 requiere una credencial de acceso válida para llamar a las operaciones de openapi. El SDK admite varios métodos de credenciales para un desarrollo seguro.

Requisitos previos

La versión del paquete aliyun-java-sdk-core debe ser 4.7.3 o posterior.

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>4.7.3</version>
</dependency>

Método 1: AccessKey

Importante

Si se filtra el AccessKey de una cuenta de Alibaba Cloud, todos los recursos asociados a dicha cuenta quedan comprometidos. Utilice el AccessKey de un usuario de Resource Access Management (RAM) en su lugar. Create an AccessKey.
Establezca las variables de entorno ALIBABA_CLOUD_ACCESS_KEY_ID y ALIBABA_CLOUD_ACCESS_KEY_SECRET en su entorno de ejecución. Configure environment variables on Linux, macOS, and Windows.

Inicialice el cliente mediante la configuración de un AccessKey con DefaultProfile.

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.profile.DefaultProfile;

public class Sample {
    public static void main(String[] args) {
        DefaultProfile profile = DefaultProfile.getProfile(
                "<REGION_ID>",
                // Retrieve the AccessKey ID of the RAM user from an environment variable.
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // Retrieve the AccessKey secret of the RAM user from an environment variable.
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        IAcsClient client = new DefaultAcsClient(profile);
        // The API call logic is omitted.
    }
}

Inicialice el cliente mediante la configuración de un AccessKey con BasicCredentials.

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.auth.BasicCredentials;
import com.aliyuncs.profile.DefaultProfile;

public class Sample {
    public static void main(String[] args) {
        BasicCredentials basicCredentials = new BasicCredentials(
                // Retrieve the AccessKey ID of the RAM user from an environment variable.
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // Retrieve the AccessKey secret of the RAM user from an environment variable.
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")
        );
        DefaultProfile profile = DefaultProfile.getProfile("<REGION_ID>");
        IAcsClient client = new DefaultAcsClient(profile, basicCredentials);
        // The API call logic is omitted.
    }
}

Método 2: token de STS

Inicialice el cliente con una credencial de acceso temporal (token de STS).

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.profile.DefaultProfile;

public class Test {
    public static void main(String[] args) {
        DefaultProfile profile = DefaultProfile.getProfile(
                "<REGION_ID>",
                // Retrieve the AccessKey ID of the RAM user from an environment variable.
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // Retrieve the AccessKey secret of the RAM user from an environment variable.
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
                // The STS token.
                System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN"));
        IAcsClient client = new DefaultAcsClient(profile);
        // The API call logic is omitted.
    }
}

Método 3: ARN de rol de RAM

Llame a la operación AssumeRole de Security Token Service (STS) para obtener un token de STS.

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.auth.STSAssumeRoleSessionCredentialsProvider;
import com.aliyuncs.profile.DefaultProfile;

public class Sample {
    public static void main(String[] args) {
        DefaultProfile profile = DefaultProfile.getProfile("<REGION_ID>");
        // Use a RAM role ARN.
        STSAssumeRoleSessionCredentialsProvider stsProvider = STSAssumeRoleSessionCredentialsProvider
                .builder()
                // Required. Retrieve the AccessKey ID of the RAM user from an environment variable.
                .accessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // Required. Retrieve the AccessKey secret of the RAM user from an environment variable.
                .accessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                // The Alibaba Cloud Resource Name (ARN) of the RAM role. Required unless the ALIBABA_CLOUD_ROLE_ARN environment variable is set.
                .roleArn("<ROLE_ARN>")
                // A custom session name. Optional. Can also be set by using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
                .roleSessionName("<ROLE_SESSION_NAME>")
                // A custom policy. Optional. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
                .policy("<POLICY>")
                // An external ID to prevent the confused deputy problem. Optional.
                .externalId("<<EXTERNAL_ID>>")
                // The duration of the access credential in seconds. Optional. Defaults to 3600 and must not exceed 43200 (12 hours).
                .durationSeconds(3600)
                // The region ID for the AssumeRole API call. Optional.
                .stsRegionId("<STS_REGION_ID>") 
                .build();
        DefaultAcsClient client = new DefaultAcsClient(profile, stsProvider);
        // The API call logic is omitted.
    }
}

Método 4: Rol de RAM de instancia

El SDK obtiene las credenciales desde un instance RAM role asociado a una instancia de Elastic Compute Service (ECS) o de Elastic Container Instance (ECI). De esta forma, no es necesario usar AccessKeys estáticos. El SDK detecta automáticamente el rol de RAM adjunto y obtiene un token de STS del servidor de metadatos.

La herramienta Credentials utiliza IMDSv2 (modo de refuerzo de seguridad) de forma predeterminada. Si IMDSv2 falla, la configuración disableIMDSv1 controla el comportamiento alternativo:

false (valor predeterminado): recurre al modo normal (IMDSv1) para obtener las credenciales.
true: genera una excepción en lugar de recurrir a IMDSv1.

La compatibilidad con IMDSv2 depende de la configuración de su instancia.

Nota

Importante

Asegúrese de que la instancia de ECS tenga configurado un rol de RAM.

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.auth.InstanceProfileCredentialsProvider;
import com.aliyuncs.profile.DefaultProfile;

public class Sample {
    public static void main(String[] args) {
        DefaultProfile profile = DefaultProfile.getProfile("<REGION_ID>");
        // Use an instance RAM role.
        InstanceProfileCredentialsProvider provider = InstanceProfileCredentialsProvider
                .builder()
                // The name of the RAM role attached to the instance.
                .roleName("<ROLE_NAME>")
                //.disableIMDSv1(false)
                .build();
        DefaultAcsClient client = new DefaultAcsClient(profile, provider);
        // The API call logic is omitted.
    }
}

Método 5: Rol de RAM de OIDC

En Container Service for Kubernetes (ACK), la función RAM Roles for Service Accounts (RRSA) asocia roles de RAM con pods individuales. Cada aplicación asume un rol de RAM distinto y utiliza credenciales temporales para acceder a los recursos de Alibaba Cloud, lo que elimina la necesidad de AccessKeys permanentes.

ACK monta un archivo de token de OIDC para cada pod e inyecta la configuración como variables de entorno. El SDK llama a la operación AssumeRoleWithOIDC de STS para intercambiar el token de OIDC por un token de STS. Isolate pod permissions by using RRSA.

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.auth.OIDCCredentialsProvider;
import com.aliyuncs.profile.DefaultProfile;

public class Sample {
    public static void main(String[] args) {
        // Use an OIDC-based RAM role.
        OIDCCredentialsProvider provider = OIDCCredentialsProvider
                .builder()
                // The ARN of the OIDC provider. Required unless the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable is set.
                .oidcProviderArn(System.getenv("ALIBABA_CLOUD_OIDC_PROVIDER_ARN"))
                // The path of the OIDC token file. Required unless the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable is set.
                .oidcTokenFilePath(System.getenv("ALIBABA_CLOUD_OIDC_TOKEN_FILE"))
                // The ARN of the RAM role. Required unless the ALIBABA_CLOUD_ROLE_ARN environment variable is set.
                .roleArn(System.getenv("ALIBABA_CLOUD_ROLE_ARN"))
                // A custom session name. Optional.
                .roleSessionName("<ROLE_SESSION_NAME>")
                // A custom policy. Optional. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
                .policy("<POLICY>")
                // The duration of the access credential in seconds. Optional. Defaults to 3600 and must not exceed 43200 (12 hours).
                .durationSeconds(3600)
                // The region ID of STS. Optional.
                .stsRegionId("<REGION_ID>")
                .build();
        DefaultProfile profile = DefaultProfile.getProfile(
                // Specify the region ID of the client.
                "<REGION_ID>");
        IAcsClient client = new DefaultAcsClient(profile, provider);
        // The API call logic is omitted.
    }
}

Método 6: Cadena predeterminada de proveedores de credenciales

Si no se proporciona ninguna credencial de forma explícita, el SDK utiliza la cadena predeterminada de proveedores de credenciales.

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;

public class Test {
    public static void main(String[] args) throws ClientException {
        // Use the default credential provider chain.
        IAcsClient client = new DefaultAcsClient("<REGION_ID>");
        // The API call logic is omitted.
    }
}

La cadena predeterminada de proveedores de credenciales busca las credenciales disponibles en el siguiente orden:

1. Propiedades del sistema

Si las propiedades del sistema alibabacloud.accessKeyId y alibabacloud.accessKeyIdSecret están definidas y no están vacías, el SDK las utiliza para crear las credenciales predeterminadas.

2. Variables de entorno

Si las variables de entorno ALIBABA_CLOUD_ACCESS_KEY_ID y ALIBABA_CLOUD_ACCESS_KEY_SECRET están definidas y no están vacías, el SDK las utiliza como credenciales predeterminadas.

3. Rol de RAM de OIDC

El SDK comprueba las siguientes variables de entorno:

ALIBABA_CLOUD_ROLE_ARN: el ARN del rol de RAM.

ALIBABA_CLOUD_OIDC_PROVIDER_ARN: el ARN del proveedor de OIDC.

ALIBABA_CLOUD_OIDC_TOKEN_FILE: la ruta del archivo de token de OIDC.

Si las tres variables de entorno están configuradas, el SDK llama a la operación AssumeRoleWithOIDC de STS para obtener un token de STS, que luego se usa como credencial predeterminada.

4. Archivo de configuración

Si no se encuentra ninguna credencial, la cadena de proveedores intenta cargar el archivo de credenciales compartidas, config.json, desde su ubicación predeterminada y utiliza la credencial especificada en dicho archivo.

Linux/macOS: ~/.aliyun/config.json
Windows: C:\Users\USER_NAME\.aliyun\config.json

Para configurar una credencial de esta manera, utilice Alibaba Cloud CLI o cree manualmente un archivo config.json en la ruta correspondiente. A continuación se muestra el formato del contenido:

{
  "current": "<PROFILE_NAME>",
  "profiles": [
    {
      "name": "<PROFILE_NAME>",
      "mode": "AK",
      "access_key_id": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
      "access_key_secret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>"
    },
    {
      "name": "<PROFILE_NAME1>",
      "mode": "StsToken",
      "access_key_id": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
      "access_key_secret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>",
      "sts_token": "<SECURITY_TOKEN>"
    },
    {
      "name":"<PROFILE_NAME2>",
      "mode":"RamRoleArn",
      "access_key_id":"<ALIBABA_CLOUD_ACCESS_KEY_ID>",
      "access_key_secret":"<ALIBABA_CLOUD_ACCESS_KEY_SECRET>",
      "ram_role_arn":"<ROLE_ARN>",
      "ram_session_name":"<ROLE_SESSION_NAME>",
      "expired_seconds":3600
    },
    {
      "name":"<PROFILE_NAME3>",
      "mode":"EcsRamRole",
      "ram_role_name":"<RAM_ROLE_ARN>"
    },
    {
      "name":"<PROFILE_NAME4>",
      "mode":"OIDC",
      "oidc_provider_arn":"<OIDC_PROVIDER_ARN>",
      "oidc_token_file":"<OIDC_TOKEN_FILE>",
      "ram_role_arn":"<ROLE_ARN>",
      "ram_session_name":"<ROLE_SESSION_NAME>",
      "expired_seconds":3600
    },
    {
      "name":"<PROFILE_NAME5>",
      "mode":"ChainableRamRoleArn",
      "source_profile":"<PROFILE_NAME>",
      "ram_role_arn":"<ROLE_ARN>",
      "ram_session_name":"<ROLE_SESSION_NAME>",
      "expired_seconds":3600
    }
  ]
}

Parámetro

Descripción

current

Especifique el nombre de la credencial para recuperar la configuración correspondiente. Este nombre corresponde al valor del parámetro name dentro de profiles. De forma predeterminada, el sistema prioriza el nombre indicado por la variable de entorno ALIBABA_CLOUD_PROFILE . Si dicha variable no está configurada, el sistema utiliza el nombre definido en current.

profiles

Contiene un conjunto de configuraciones de credenciales. El parámetro mode indica el tipo de credencial:

AK: utiliza el AccessKey de un usuario de RAM como credencial.
StsToken: emplea un token de STS como credencial.
RamRoleArn: asume un rol de RAM mediante las credenciales de un usuario de RAM para obtener una credencial temporal.
EcsRamRole: obtiene una credencial a partir de los metadatos de la instancia.
OIDC: recupera una credencial mediante un ARN de proveedor de OIDC, un token de OIDC y un ARN de rol de RAM.
ChainableRamRoleArn: aplica el encadenamiento de roles para obtener una nueva credencial. Para ello, parte de una credencial inicial definida en profiles y señalada por el parámetro source_profile.

5. Rol de RAM de instancia de ECS

El SDK comprueba la variable de entorno ALIBABA_CLOUD_ECS_METADATA, donde se especifica el nombre de un rol de RAM de instancia. Si está configurada, el SDK recupera un token de STS del servidor de metadatos de ECS.

6. URI de credenciales

El SDK verifica la variable de entorno ALIBABA_CLOUD_CREDENTIALS_URI. Si está configurada, solicita una credencial temporal en el URI especificado.