Panggil operasi OpenAPI secara aman dengan mengonfigurasi Kredensial (Java SDK) - Alibaba Cloud SDK

Saat menggunakan Alibaba Cloud SDK, informasi kredensial seperti Pasangan Kunci Akses dan token Layanan Token Keamanan (STS) dikelola oleh alat Credentials. Topik ini menjelaskan jenis kredensial yang didukung oleh alat Credentials serta cara mengonfigurasinya.

Prasyarat

Alat Credentials memerlukan Java 8 atau versi yang lebih baru. Untuk informasi selengkapnya, lihat Kebijakan Dukungan Alibaba Cloud SDK.
Untuk menggunakan Alibaba Cloud SDK V2.0, lihat SDK V2.0 dan SDK V1.0.

Instal alat Credentials

Gunakan versi terbaru paket dependensi Credentials untuk memastikan semua fitur didukung.

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>credentials-java</artifactId>
  <version>latest-version</version>
</dependency>
<!-- Jika Anda hanya menggunakan credentials-java, Anda harus menambahkan paket tea. -->
<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>tea</artifactId>
  <version>latest-version</version>
</dependency>

Untuk informasi tentang versi terbaru paket Credentials, lihat GitHub atau Repositori Maven. Untuk informasi tentang versi terbaru paket Tea, lihat GitHub atau Repositori Maven.

Jenis kredensial yang didukung oleh alat Credentials dan parameter konfigurasinya

Jenis kredensial yang didukung oleh alat Credentials dan parameter konfigurasinya didefinisikan dalam kelas com.aliyun.credentials.models.Config. Jenis kredensial ditentukan oleh parameter type, dan parameter konfigurasi yang diperlukan berbeda-beda untuk setiap jenis kredensial. Tabel berikut menjelaskan nilai valid dari parameter type dan parameter konfigurasi yang didukung oleh masing-masing jenis kredensial. Dalam tabel tersebut, Supported menunjukkan parameter yang diperlukan, - menunjukkan parameter opsional, dan Not supported menunjukkan parameter yang tidak didukung.

Catatan

Kami menyarankan agar Anda tidak menggunakan jenis kredensial atau parameter yang tidak tercantum dalam tabel berikut.

type	access_key	sts	ram_role_arn	ecs_ram_role	oidc_role_arn	credentials_uri	bearer
accessKeyId: ID AccessKey.	Supported	Supported	Supported	Not supported	Not supported	Not supported	Not supported
accessKeySecret: Rahasia AccessKey.	✓	Supported	Supported	Not supported	Not supported	Not supported	Not supported
securityToken: Token STS.	Not supported	Supported	-	Not supported	Not supported	×	Not supported
roleArn: Nama Sumber Daya Alibaba Cloud (ARN) dari peran RAM.	Not supported	Not supported	✓	Not supported	Supported	Not supported	Not supported
roleSessionName: Nama sesi kustom. Format default adalah `credentials-java-current-timestamp`.	Not supported	Not supported	-	Not supported	-	Not supported	Not supported
roleName: Nama peran RAM.	Not supported	Not supported	Not supported	-	×	Not supported	Not supported
disableIMDSv1: Menentukan apakah akan menerapkan mode penguatan keamanan (IMDSv2). Nilai default adalah `false`.	Not supported	Not supported	Not supported	-	Not supported	Not supported	Not supported
bearerToken: Token bearer.	Not supported	Not supported	Not supported	Not supported	Not supported	Not supported	✓
policy: Kebijakan kustom.	Not supported	Not supported	-	Not supported	-	×	Not supported
roleSessionExpiration: Periode validitas sesi. Nilai default: 3600. Satuan: detik. Nilai minimum adalah 900 detik. Nilai maksimum adalah durasi sesi maksimum yang didukung oleh peran RAM.	Not supported	Not supported	-	Not supported	-	Not supported	Not supported
oidcProviderArn: ARN dari Penyedia Identitas OIDC.	Not supported	Not supported	Not supported	Not supported	Supported	Not supported	Not supported
oidcTokenFilePath: Jalur file token OIDC.	Not supported	Not supported	Not supported	Not supported	Supported	Not supported	Not supported
externalId: ID eksternal dari peran, yang digunakan untuk mencegah masalah deputy yang bingung. Untuk informasi lebih lanjut, lihat Gunakan ID eksternal untuk mencegah masalah deputy yang bingung.	Not supported	Not supported	-	Not supported	Not supported	Not supported	Not supported
credentialsURI: URI dari kredensial eksternal.	Not supported	Not supported	Not supported	Not supported	Not supported	Supported	Not supported
STSEndpoint: Titik akhir layanan untuk Layanan Token Keamanan (STS), yang mendukung titik akhir layanan VPC dan titik akhir layanan Internet. Untuk daftar nilai valid, lihat Titik Akhir. Nilai default adalah `sts.aliyuncs.com`.	Not supported	Not supported	-	×	-	Not supported	Not supported
timeout: Periode waktu tunggu baca untuk permintaan. Nilai default: 5000 milidetik.	Not supported	Not supported	-	-	-	-	Not supported
connectTimeout: Periode waktu tunggu koneksi untuk permintaan. Nilai default: 10000 milidetik.	Not supported	Not supported	-	-	-	-	Not supported

Gunakan alat Credentials

Bagian berikut menyediakan contoh kode untuk menunjukkan cara menggunakan alat Credentials. Anda dapat memilih metode berdasarkan kebutuhan Anda.

Penting

Kami menyarankan agar Anda menyimpan Pasangan Kunci Akses di variabel lingkungan atau file konfigurasi.
Kami menyarankan agar Anda menggunakan pola singleton saat menggunakan alat Credentials. Praktik ini mengaktifkan fitur caching kredensial bawaan, mencegah masalah throttling akibat banyak panggilan API, serta menghindari pemborosan sumber daya karena pembuatan banyak instans. Untuk informasi selengkapnya, lihat Mekanisme penyegaran otomatis untuk kredensial sesi.

Metode 1: Rantai penyedia kredensial default

Catatan

Ini adalah metode default yang digunakan dalam kode contoh di Portal OpenAPI.

Jika Anda menggunakan alat Credentials tanpa meneruskan parameter konfigurasi apa pun, alat ini memperoleh kredensial dari rantai penyedia kredensial default dan menggunakannya sebagai kredensial akses. Saat menggunakan metode ini, pastikan bahwa metode perolehan kredensial yang didukung oleh rantai penyedia kredensial default telah dikonfigurasi di lingkungan runtime aplikasi.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.CredentialModel;

public class DemoTest {
    public static void main(String[] args) throws Exception {
        // Jangan tentukan parameter konfigurasi. Kredensial akan diperoleh dari rantai penyedia kredensial default.
        Client credentialClient = new Client();
        
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();


        // Jika Anda menggunakan SDK V2.0 dari layanan Alibaba Cloud, gunakan com.aliyun.teaopenapi.models.Config untuk meneruskan kredensial.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // Kode untuk menginisialisasi klien layanan cloud menggunakan config dihilangkan.
    }
}

Metode 2: Pasangan Kunci Akses

Alat Credentials menggunakan AccessKey Anda sebagai kredensial akses.

Peringatan

Akun Alibaba Cloud memiliki izin penuh atas semua sumber daya. Jika Pasangan Kunci Akses akun Alibaba Cloud bocor, hal ini menimbulkan ancaman keamanan serius bagi sistem Anda. Kami tidak merekomendasikan penggunaan Pasangan Kunci Akses akun Alibaba Cloud.

Kami menyarankan agar Anda menggunakan Pasangan Kunci Akses Pengguna RAM yang diberikan izin minimum yang diperlukan.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;
import com.aliyun.credentials.models.CredentialModel;

public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("access_key");
        // Wajib. Contoh ini menunjukkan cara memperoleh ID AccessKey dari variabel lingkungan.
        credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        // Wajib. Contoh ini menunjukkan cara memperoleh rahasia AccessKey dari variabel lingkungan.
        credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        Client credentialClient = new Client(credentialConfig);
                
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();

        // Jika Anda menggunakan SDK V2.0 dari layanan Alibaba Cloud, gunakan com.aliyun.teaopenapi.models.Config untuk meneruskan kredensial.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // Kode untuk menginisialisasi klien layanan cloud menggunakan config dihilangkan.
    }
}

Metode 3: Token STS

Alat Credentials menggunakan token STS statis yang Anda berikan sebagai kredensial akses.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;
import com.aliyun.credentials.models.CredentialModel;

public class DemoTest {
    public static void main(String[] args) {
        Config credentialConfig = new Config();
        credentialConfig.setType("sts");
        // Wajib. Contoh ini menunjukkan cara memperoleh ID AccessKey dari variabel lingkungan.
        credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        // Wajib. Contoh ini menunjukkan cara memperoleh rahasia AccessKey dari variabel lingkungan.
        credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // Wajib. Contoh ini menunjukkan cara memperoleh token keamanan sementara dari variabel lingkungan.
        credentialConfig.setSecurityToken(System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN"));
        Client credentialClient = new Client(credentialConfig);
        
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();

        // Jika Anda menggunakan SDK V2.0 dari layanan Alibaba Cloud, gunakan com.aliyun.teaopenapi.models.Config untuk meneruskan kredensial.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // Kode untuk menginisialisasi klien layanan cloud menggunakan config dihilangkan.
    }
}

Metode 4: Pasangan Kunci Akses dan RamRoleArn

Alat Credentials menggunakan Pasangan Kunci Akses dan ARN peran RAM yang Anda berikan untuk memanggil operasi AssumeRole guna memperoleh token STS. Token ini kemudian digunakan sebagai kredensial akses. Kredensial yang diperoleh dengan cara ini mendukung penyegaran otomatis. Untuk informasi selengkapnya, lihat Mekanisme penyegaran otomatis untuk kredensial sesi.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;
import com.aliyun.credentials.models.CredentialModel;

public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("ram_role_arn");
        // Wajib. Contoh ini menunjukkan cara memperoleh ID AccessKey dari variabel lingkungan.
        credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        // Wajib. Contoh ini menunjukkan cara memperoleh rahasia AccessKey dari variabel lingkungan.
        credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // Opsional. Anda dapat menggunakan kredensial sementara untuk mengasumsikan peran RAM lain.
        credentialConfig.setSecurityToken(System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN"));
        // Wajib. ARN dari peran RAM yang akan diasumsikan. Contoh: acs:ram::123456789012****:role/adminrole. Anda dapat menyetel parameter ini menggunakan variabel lingkungan ALIBABA_CLOUD_ROLE_ARN.
        credentialConfig.setRoleArn("<RoleArn>");
        // Opsional. Nama sesi peran. Format default adalah credentials-java-current timestamp. Anda dapat menyetel parameter ini menggunakan variabel lingkungan ALIBABA_CLOUD_ROLE_SESSION_NAME.
        credentialConfig.setRoleSessionName("<RoleSessionName>");
        // Opsional. Tentukan kebijakan yang lebih ketat. Contoh: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}.
        credentialConfig.setPolicy("<Policy>");
        // Opsional. ID eksternal peran. Parameter ini digunakan untuk mencegah masalah confused deputy.
        credentialConfig.setExternalId("<ExternalId>");
        // Opsional. Periode validitas sesi. Nilai default: 3600 detik.
        credentialConfig.setRoleSessionExpiration(3600);
        Client credentialClient = new Client(credentialConfig);
        
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();

        // Jika Anda menggunakan SDK V2.0 dari layanan Alibaba Cloud, gunakan com.aliyun.teaopenapi.models.Config untuk meneruskan kredensial.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // Kode untuk menginisialisasi klien layanan cloud menggunakan config dihilangkan.
    }
}

Metode 5: Peran RAM Instans

Jika aplikasi Anda berjalan pada instans ECS atau ECI yang diberikan peran RAM, alat Credentials dapat memperoleh token STS untuk peran RAM dari metadata instans dan menggunakannya sebagai kredensial akses. Saat mengakses metadata instans, aplikasi pertama-tama mengambil nama peran RAM yang diberikan ke instans saat ini, lalu memperoleh token STS yang sesuai berdasarkan peran tersebut. Anda dapat menentukan nama peran RAM menggunakan parameter roleName atau variabel lingkungan ALIBABA_CLOUD_ECS_METADATA untuk mengurangi waktu yang diperlukan untuk memperoleh kredensial dan meningkatkan efisiensi. Kredensial yang diperoleh dengan cara ini mendukung penyegaran otomatis. Untuk informasi selengkapnya, lihat Mekanisme penyegaran otomatis untuk kredensial sesi.

Secara default, alat Credentials menggunakan mode penguatan keamanan (IMDSv2) untuk mengakses metadata instans. Jika terjadi pengecualian dalam mode penguatan keamanan, Anda dapat menggunakan parameter disableIMDSv1 atau variabel lingkungan ALIBABA_CLOUD_IMDSV1_DISABLED untuk mengontrol logika penanganan pengecualian:

Jika nilainya false (default), sistem mencoba beralih ke mode NAT untuk melanjutkan memperoleh kredensial.
Jika nilainya true, hanya mode penguatan keamanan yang dapat digunakan untuk memperoleh kredensial. Pengecualian dilemparkan jika akses dalam mode ini gagal.

Dukungan server terhadap IMDSv2 bergantung pada konfigurasi server Anda.

Selain itu, Anda dapat menonaktifkan akses kredensial dari metadata instans dengan menyetel variabel lingkungan ALIBABA_CLOUD_ECS_METADATA_DISABLED=true.

Catatan

Untuk informasi selengkapnya tentang metadata instans, lihat Metadata instans.
Untuk informasi selengkapnya tentang cara memberikan peran RAM ke instans ECS atau ECI, lihat Buat peran RAM dan berikan ke instans ECS dan Berikan peran RAM instans ke instans ECI.
Untuk memperoleh kredensial sementara dalam mode penguatan keamanan, Anda harus menggunakan credentials-java 0.3.10 atau yang lebih baru.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;
import com.aliyun.credentials.models.CredentialModel;

public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("ecs_ram_role");
        // Opsional. Nama peran RAM yang diberikan ke instans ECS. Jika Anda tidak menyetel parameter ini, nama akan diperoleh secara otomatis. Kami menyarankan agar Anda menyetel parameter ini untuk mengurangi jumlah permintaan. Anda dapat menyetel parameter ini menggunakan variabel lingkungan ALIBABA_CLOUD_ECS_METADATA.
        credentialConfig.setRoleName("<RoleName>");
        // Opsional. Nilai true menunjukkan bahwa mode penguatan keamanan dipaksakan. Nilai default: false. Sistem pertama-tama mencoba memperoleh kredensial dalam mode penguatan keamanan. Jika upaya gagal, sistem beralih ke mode normal.
        credentialConfig.setDisableIMDSv1(false);
        Client credentialClient = new Client(credentialConfig);
        
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();
        
        // Jika Anda menggunakan SDK V2.0 dari layanan Alibaba Cloud, gunakan com.aliyun.teaopenapi.models.Config untuk meneruskan kredensial.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // Kode untuk menginisialisasi klien layanan cloud menggunakan config dihilangkan.
    }
}

Metode 6: OIDCRoleArn

Jika Anda menggunakan protokol autentikasi OIDC dan telah membuat peran RAM untuk Penyedia Identitas OIDC, Anda dapat meneruskan ARN Penyedia Identitas OIDC, token OIDC, dan ARN peran RAM ke alat Credentials. Sistem kemudian secara otomatis memanggil operasi AssumeRoleWithOIDC untuk memperoleh token STS untuk peran RAM dan menggunakan token ini sebagai kredensial akses. Kredensial yang diperoleh dengan cara ini mendukung penyegaran otomatis. Untuk informasi selengkapnya, lihat Mekanisme penyegaran otomatis untuk kredensial sesi. Sebagai contoh, jika aplikasi Anda berjalan di kluster ACK tempat fitur RRSA diaktifkan, alat Credentials membaca informasi konfigurasi OIDC dari variabel lingkungan pod, memanggil operasi AssumeRoleWithOIDC untuk memperoleh token STS untuk peran layanan, dan menggunakan token ini untuk mengakses layanan Alibaba Cloud terkait.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;
import com.aliyun.credentials.models.CredentialModel;

public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("oidc_role_arn");
        // Wajib. ARN dari peran RAM. Anda dapat menyetel parameter ini menggunakan variabel lingkungan ALIBABA_CLOUD_ROLE_ARN.
        credentialConfig.setRoleArn("<RoleArn>");
        // Wajib. ARN dari Penyedia Identitas OIDC. Anda dapat menyetel parameter ini menggunakan variabel lingkungan ALIBABA_CLOUD_OIDC_PROVIDER_ARN.
        credentialConfig.setOidcProviderArn("<OidcProviderArn>");
        // Wajib. Jalur file token OIDC. Anda dapat menyetel parameter ini menggunakan variabel lingkungan ALIBABA_CLOUD_OIDC_TOKEN_FILE.
        credentialConfig.setOidcTokenFilePath("<OidcTokenFilePath>");
        // Opsional. Nama sesi peran. Anda dapat menyetel parameter ini menggunakan variabel lingkungan ALIBABA_CLOUD_ROLE_SESSION_NAME.
        credentialConfig.setRoleSessionName("<RoleSessionName>");
        // Opsional. Tentukan kebijakan yang lebih ketat. Contoh: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
        credentialConfig.setPolicy("<Policy>");
        // Opsional. Periode validitas sesi. Nilai default: 3600 detik.
        credentialConfig.setRoleSessionExpiration(3600);
        Client credentialClient = new Client(credentialConfig);
        
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();
        
        // Jika Anda menggunakan SDK V2.0 dari layanan Alibaba Cloud, gunakan com.aliyun.teaopenapi.models.Config untuk meneruskan kredensial.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // Kode untuk menginisialisasi klien layanan cloud menggunakan config dihilangkan.
    }
}

Metode 7: Kredensial URI

Dengan mengenkapsulasi layanan STS dan mengekspos URI-nya, layanan eksternal dapat memperoleh token STS melalui URI tersebut. Hal ini mengurangi risiko mengekspos informasi sensitif, seperti Pasangan Kunci Akses. Alat Credentials memperoleh token STS dengan mengakses URI yang Anda berikan dan menggunakannya sebagai kredensial akses. Kredensial yang diperoleh dengan cara ini mendukung penyegaran otomatis. Untuk informasi selengkapnya, lihat Mekanisme penyegaran otomatis untuk kredensial sesi.

URI harus memenuhi kondisi berikut:

Harus mendukung permintaan GET.
Kode status respons harus 2xx.

Badan respons harus memiliki struktur berikut:

{
  "Code": "Success",
  "AccessKeySecret": "yourAccessKeySecret",
  "AccessKeyId": "STS.****************",
  "Expiration": "2021-09-26T03:46:38Z",
  "SecurityToken": "yourSecurityToken"
}

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;
import com.aliyun.credentials.models.CredentialModel;

public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("credentials_uri");
        // Wajib. URI untuk memperoleh kredensial eksternal. Formatnya adalah http://local_or_remote_uri/. Anda dapat menyetel parameter ini menggunakan variabel lingkungan ALIBABA_CLOUD_CREDENTIALS_URI.
        credentialConfig.setCredentialsUri("<CredentialsUri>");
        Client credentialClient = new Client(credentialConfig);
        
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();
        
        // Jika Anda menggunakan SDK V2.0 dari layanan Alibaba Cloud, gunakan com.aliyun.teaopenapi.models.Config untuk meneruskan kredensial.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // Kode untuk menginisialisasi klien layanan cloud menggunakan config dihilangkan.
    }
}

Metode 8: Token Bearer

Saat ini, hanya Cloud Call Center (CCC) yang mendukung token bearer.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;
import com.aliyun.credentials.models.CredentialModel;

public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("bearer");
        // Wajib. Masukkan token bearer Anda.
        credentialConfig.setBearerToken("<BearerToken>");
        Client credentialClient = new Client(credentialConfig);
        
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();
        
        // Jika Anda menggunakan SDK V2.0 untuk CCC, gunakan com.aliyun.teaopenapi.models.Config untuk meneruskan kredensial.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // Kode untuk menginisialisasi klien layanan cloud menggunakan config dihilangkan.
    }
}

Rantai penyedia kredensial default

Rantai penyedia kredensial default adalah strategi fallback yang mencari kredensial dalam urutan yang telah ditentukan. Alat ini melewati rantai hingga menemukan informasi kredensial. Jika informasi kredensial tidak dapat diperoleh dari penyedia mana pun dalam rantai, `CredentialException` dilemparkan. Urutan pencarian adalah sebagai berikut:

1. Properti sistem

Alat Credentials pertama-tama mencoba memperoleh informasi kredensial dari properti sistem.

Jika `alibabacloud.accessKeyId` dan `alibabacloud.accessKeySecret` didefinisikan dalam properti sistem, Pasangan Kunci Akses digunakan sebagai kredensial default.
Jika `alibabacloud.accessKeyId`, `alibabacloud.accessKeySecret`, dan `alibabacloud.sessionToken` didefinisikan dalam properti sistem, token STS digunakan sebagai kredensial default.

Anda dapat menambahkan parameter JVM berikut saat menjalankan program Java untuk menentukan nilai-nilai ini:

-Dalibabacloud.accessKeyId=your-access-key-id -Dalibabacloud.accessKeySecret=your-access-key-secret

2. Variabel lingkungan

Jika tidak ditemukan informasi kredensial dalam properti sistem, alat Credentials memeriksa variabel lingkungan.

Jika variabel lingkungan ALIBABA_CLOUD_ACCESS_KEY_ID dan ALIBABA_CLOUD_ACCESS_KEY_SECRET ada dan tidak kosong, Pasangan Kunci Akses digunakan sebagai kredensial default.
Jika variabel lingkungan ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET, dan ALIBABA_CLOUD_SECURITY_TOKEN semuanya disetel, token STS digunakan sebagai kredensial default.

3. Peran RAM OIDC

Jika tidak ditemukan informasi kredensial, alat Credentials memeriksa variabel lingkungan berikut yang terkait dengan peran RAM OIDC:

ALIBABA_CLOUD_ROLE_ARN: ARN dari peran RAM.
ALIBABA_CLOUD_OIDC_PROVIDER_ARN: ARN dari Penyedia Identitas OIDC.
ALIBABA_CLOUD_OIDC_TOKEN_FILE: Jalur file token OIDC.

Jika ketiga variabel lingkungan tersebut ada dan tidak kosong, alat Credentials menggunakan nilai variabel lingkungan ini untuk memanggil operasi AssumeRoleWithOIDC dari STS dan memperoleh token STS sebagai kredensial default.

4. File konfigurasi config.json

Catatan

Fitur ini memerlukan credentials-java 0.3.8 atau yang lebih baru.

Jika kredensial masih belum ditemukan, alat Credentials mencoba memuat file config.json dari jalur default dan menggunakan kredensial yang ditentukan sebagai kredensial default. Jalur file default adalah:

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

Untuk mengonfigurasi kredensial menggunakan metode ini, Anda dapat menggunakan Cloud Assistant CLI atau membuat file konfigurasi config.json secara manual di jalur yang sesuai. Blok kode berikut menunjukkan contoh format kontennya:

{
  "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
    }
  ]
}

Parameter

Deskripsi

current

Menentukan nama kredensial yang akan digunakan, yang sesuai dengan nilai parameter profiles yaitu nilai name. Secara default, sistem memprioritaskan nama kredensial yang ditentukan oleh variabel lingkungan ALIBABA_CLOUD_PROFILE . Jika variabel lingkungan ini tidak disetel, sistem menggunakan nama kredensial yang ditentukan oleh current.

profiles

Kumpulan informasi kredensial. Gunakan parameter mode untuk menentukan jenis kredensial:

AK: Menggunakan Pasangan Kunci Akses pengguna sebagai kredensial.
StsToken: Menggunakan token STS sebagai kredensial.
RamRoleArn: Memperoleh kredensial dengan meminta Pengguna RAM mengasumsikan peran RAM.
EcsRamRole: Memperoleh kredensial dari metadata instans.
OIDC: Memperoleh kredensial menggunakan ARN Penyedia Identitas OIDC, token OIDC, dan ARN peran RAM.
ChainableRamRoleArn: Menggunakan metode perantai peran untuk memperoleh informasi kredensial baru dengan menggunakan source_profile untuk menentukan nama kredensial lain dalam profiles.

5. Peran RAM Instans

Jika tidak ditemukan informasi kredensial, alat Credentials mencoba memperoleh token STS dari peran RAM yang diberikan ke instans dari metadata instans dan menggunakannya sebagai kredensial default. Saat mengakses metadata instans, program pertama-tama memperoleh nama peran RAM yang dilampirkan ke instans saat ini, lalu memperoleh token STS yang sesuai berdasarkan peran tersebut. Anda juga dapat menentukan nama peran RAM menggunakan variabel lingkungan ALIBABA_CLOUD_ECS_METADATA untuk mengurangi waktu yang diperlukan untuk memperoleh kredensial dan meningkatkan efisiensi.

Secara default, alat Credentials mengakses metadata dalam mode penguatan keamanan (IMDSv2). Jika terjadi pengecualian dalam mode penguatan keamanan, Anda dapat menggunakan variabel lingkungan ALIBABA_CLOUD_IMDSV1_DISABLED untuk mengontrol logika penanganan pengecualian:

Jika nilainya false (default), sistem mencoba beralih ke mode NAT untuk melanjutkan memperoleh kredensial.
Jika nilainya true, hanya mode penguatan keamanan yang diizinkan untuk memperoleh kredensial. Jika akses dalam mode penguatan keamanan gagal, pengecualian dilemparkan.

Selain itu, Anda dapat menonaktifkan akses kredensial dari metadata instans dengan menyetel variabel lingkungan ALIBABA_CLOUD_ECS_METADATA_DISABLED=true.

Catatan

Untuk informasi selengkapnya tentang metadata instans, lihat Memperoleh metadata instans.
Untuk informasi selengkapnya tentang cara memberikan peran RAM ke instans ECS atau ECI, lihat Buat peran RAM dan lampirkan ke instans ECS dan Lampirkan peran RAM instans ke instans ECI.
Untuk memperoleh kredensial sementara dalam mode penguatan keamanan, Anda harus menggunakan credentials-java 0.3.10 atau yang lebih baru.

6. CredentialsURI

Jika tidak ditemukan informasi kredensial, alat Credentials memeriksa variabel lingkungan ALIBABA_CLOUD_CREDENTIALS_URI. Jika variabel ini ada dan mengarah ke URI yang valid, alat Credentials mengakses URI ini untuk memperoleh token STS sebagai kredensial default.

Mekanisme penyegaran otomatis untuk kredensial sesi

Kredensial sesi mencakup ram_role_arn, ecs_ram_role, oidc_role_arn, dan credentials_uri. Jenis kredensial ini memiliki mekanisme penyegaran otomatis bawaan di alat Credentials. Setelah klien kredensial memperoleh kredensial untuk pertama kalinya, alat Credentials menyimpan informasi kredensial ke cache. Dalam permintaan selanjutnya, instans klien kredensial yang sama secara otomatis mengambil kredensial dari cache. Jika kredensial dalam cache kedaluwarsa, instans klien kredensial memperoleh kembali kredensial dan memperbarui cache.

Catatan

Untuk kredensial `ecs_ram_role`, alat Credentials menyegarkan cache 15 menit sebelum kredensial kedaluwarsa.

Contoh berikut membuat klien kredensial dalam pola singleton. Klien memperoleh kredensial pada titik waktu yang berbeda untuk memverifikasi mekanisme penyegaran otomatis dan memanggil operasi OpenAPI untuk memastikan bahwa kredensial yang diperoleh valid.

import com.aliyun.credentials.models.CredentialModel;
import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

import java.util.Date;
import java.util.concurrent.*;

public class Sample {

    /**
     * Kelas Credential digunakan untuk mengelola instans kredensial Alibaba Cloud dalam pola singleton.
     */
    private static class Credential {
        private static volatile com.aliyun.credentials.Client instance;

        private Credential() {
        }

        public static com.aliyun.credentials.Client getInstance() {
            if (instance == null) {
                synchronized (Credential.class) {
                    if (instance == null) {
                        try {
                            com.aliyun.credentials.models.Config config = new com.aliyun.credentials.models.Config();
                            config.setType("ram_role_arn");
                            config.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
                            config.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
                            config.setRoleArn(System.getenv("ALIBABA_CLOUD_ROLE_ARN"));
                            config.setRoleSessionName("RamRoleArnTest");
                            config.setRoleSessionExpiration(3600);
                            instance = new com.aliyun.credentials.Client(config);
                        } catch (Exception e) {
                            throw new RuntimeException("Inisialisasi kredensial gagal: " + e.getMessage(), e);
                        }
                    }
                }
            }
            return instance;
        }
    }

    /**
     * Kelas EcsClient digunakan untuk mengelola klien ECS dalam pola singleton.
     */
    private static class EcsClient {
        private static volatile Client instance;

        private EcsClient() {
        }

        public static Client getInstance(com.aliyun.credentials.Client credentialClient) {
            if (instance == null) {
                synchronized (EcsClient.class) {
                    if (instance == null) {
                        try {
                            Config ecsConfig = new Config();
                            ecsConfig.setEndpoint("ecs.cn-hangzhou.aliyuncs.com");
                            ecsConfig.setCredential(credentialClient);
                            instance = new Client(ecsConfig);
                        } catch (Exception e) {
                            throw new RuntimeException("Inisialisasi klien ECS gagal: " + e.getMessage(), e);
                        }
                    }
                }
            }
            return instance;
        }
    }

    public static void main(String[] args) {
        // Gunakan ThreadPoolExecutor untuk membuat pool thread terjadwal.
        ScheduledThreadPoolExecutor scheduler = new ScheduledThreadPoolExecutor(
                1,
                Executors.defaultThreadFactory(),
                new ThreadPoolExecutor.AbortPolicy()
        );
        scheduler.setKeepAliveTime(0L, TimeUnit.SECONDS);
        scheduler.allowCoreThreadTimeOut(false); // Jangan izinkan thread inti timeout.

        // Definisikan tugas Runnable untuk menjalankan logika pemanggilan.
        Runnable task = () -> {
            try {
                com.aliyun.credentials.Client credentialClient = Credential.getInstance();
                CredentialModel credential = credentialClient.getCredential();
                System.out.println(new Date());
                System.out.printf("ID AK:%s, Rahasia AK:%s, Token STS:%s%n", credential.accessKeyId, credential.accessKeySecret, credential.securityToken);

                // Contoh ini memanggil operasi API ECS untuk memverifikasi apakah kredensial tersedia. Anda dapat memodifikasinya sesuai kebutuhan.
                Client ecsClient = EcsClient.getInstance(credentialClient);
                DescribeRegionsRequest request = new DescribeRegionsRequest();
                RuntimeOptions runtime = new RuntimeOptions();
                DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(request, runtime);
                System.out.printf("Hasil pemanggilan:%s%n", response.statusCode);
            } catch (Exception e) {
                throw new RuntimeException("Eksekusi klien ECS gagal: " + e.getMessage(), e);
            }
        };

        try {
            // Jalankan tugas untuk pertama kali (segera).
            scheduler.execute(task);
            // Jalankan tugas untuk kedua kalinya setelah penundaan 600 detik.
            scheduler.schedule(task, 600, TimeUnit.SECONDS);
            // Jalankan tugas untuk ketiga kalinya, 4200 detik setelah dimulai.
            scheduler.schedule(task, 4200, TimeUnit.SECONDS);
            // Jalankan tugas untuk keempat kalinya, 4300 detik setelah dimulai.
            scheduler.schedule(task, 4300, TimeUnit.SECONDS);
        } finally {
            // Matikan pool thread untuk memastikan ditutup setelah semua tugas selesai.
            scheduler.shutdown();
            try {
                if (!scheduler.awaitTermination(4500, TimeUnit.SECONDS)) {
                    scheduler.shutdownNow();
                }
            } catch (InterruptedException e) {
                scheduler.shutdownNow();
                Thread.currentThread().interrupt();
            }
        }
    }
}

Bagian berikut menganalisis hasil log:

Pada pemanggilan pertama, tidak ada informasi kredensial yang di-cache. Oleh karena itu, sistem memperoleh kredensial berdasarkan konfigurasi. Setelah kredensial diperoleh, kredensial tersebut disimpan dalam cache.
Kredensial yang digunakan dalam pemanggilan kedua sama dengan yang pertama. Ini menunjukkan bahwa kredensial untuk pemanggilan kedua diambil dari cache.
Pada pemanggilan ketiga, kredensial dalam cache telah kedaluwarsa. Hal ini karena periode validitas kredensial (`RoleSessionExpiration`) diatur menjadi 3.600 detik, dan pemanggilan ketiga terjadi 4.200 detik setelah pemanggilan pertama. Oleh karena itu, SDK memperoleh kembali kredensial baru berdasarkan mekanisme penyegaran otomatis dan menyimpan kredensial baru ke cache.
Kredensial yang digunakan dalam pemanggilan keempat sama dengan kredensial baru yang diperoleh dalam pemanggilan ketiga. Ini menunjukkan bahwa kredensial dalam cache telah diperbarui setelah kedaluwarsa.

Referensi

Untuk informasi lebih lanjut tentang RAM, lihat Istilah.
Untuk informasi lebih lanjut tentang cara membuat pasangan AccessKey, lihat Buat pasangan AccessKey.
Untuk informasi selengkapnya tentang cara membuat Pengguna RAM, Pasangan Kunci Akses, peran RAM, dan kebijakan akses secara terprogram serta memberikan izin, lihat Ikhtisar SDK RAM.
Untuk informasi selengkapnya tentang cara mengasumsikan peran secara terprogram, lihat Ikhtisar SDK STS.
Untuk informasi selengkapnya tentang operasi API yang terkait dengan RAM dan STS, lihat Referensi API.
Praktik terbaik untuk menggunakan kredensial akses untuk memanggil operasi API
Solusi untuk kebocoran pasangan AccessKey