Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Menggunakan AWS Penyedia Kredensyal Beban Kerja
<a name="workload-credentials-provider"></a>

## Bagaimana AWS Workload Credentials Provider bekerja
<a name="provider-overview"></a>

Penyedia Kredensial AWS Beban Kerja (sebelumnya AWS Secrets Manager Agen) menyediakan layanan HTTP sisi klien yang membantu Anda menstandarisasi cara Anda menggunakan rahasia dari Secrets Manager di seluruh lingkungan komputasi Anda. Anda dapat menggunakannya dengan layanan berikut:
+ AWS Lambda
+ Amazon Elastic Container Service
+ Amazon Elastic Kubernetes Service
+ Amazon Elastic Compute Cloud

Penyedia Kredensial AWS Beban Kerja mengambil dan menyimpan rahasia di memori, memungkinkan aplikasi Anda mendapatkan rahasia dari localhost alih-alih melakukan panggilan langsung ke Secrets Manager. Penyedia Kredensial AWS Beban Kerja hanya dapat membaca rahasia—tidak dapat memodifikasinya.

Penyedia Kredensial AWS Beban Kerja adalah open source. Kode sumber, instruksi instalasi, dan informasi rilis terbaru tersedia di [GitHub](https://github.com/aws/aws-workload-credentials-provider).

**penting**  
Penyedia Kredensial AWS Beban Kerja menggunakan AWS kredensyal dari lingkungan Anda untuk memanggil Secrets Manager. Ini mencakup perlindungan terhadap Server Side Request Forgery (SSRF) untuk membantu meningkatkan keamanan rahasia. Penyedia Kredensial AWS Beban Kerja menggunakan pertukaran kunci pasca-kuantum sebagai pertukaran ML-KEM kunci prioritas tertinggi secara default.

## Memahami AWS Caching Penyedia Kredensyal Beban Kerja
<a name="provider-caching"></a>

Penyedia Kredensial AWS Beban Kerja menggunakan cache dalam memori yang disetel ulang saat Penyedia Kredensyal Beban Kerja dimulai ulang.AWS Ini secara berkala menyegarkan nilai rahasia yang di-cache berdasarkan hal berikut:
+ Frekuensi refresh default (TTL) adalah 300 detik
+ Anda dapat memodifikasi TTL menggunakan file konfigurasi
+ Penyegaran terjadi saat Anda meminta rahasia setelah TTL kedaluwarsa

**catatan**  
Penyedia Kredensial AWS Beban Kerja tidak menyertakan pembatalan cache. Jika rahasia berputar sebelum entri cache kedaluwarsa, Penyedia Kredensyal AWS Beban Kerja mungkin mengembalikan nilai rahasia basi.

Penyedia Kredensial AWS Beban Kerja mengembalikan nilai rahasia dalam format yang sama dengan respons. `GetSecretValue` Nilai rahasia tidak dienkripsi dalam cache.

**Topics**
+ [Bagaimana AWS Workload Credentials Provider bekerja](#provider-overview)
+ [Memahami AWS Caching Penyedia Kredensyal Beban Kerja](#provider-caching)
+ [Membangun AWS Penyedia Kredensyal Beban Kerja](#workload-credentials-provider-build)
+ [Instal AWS Penyedia Kredensyal Beban Kerja](#workload-credentials-provider-install)
+ [Ambil rahasia dengan AWS Penyedia Kredensyal Beban Kerja](#workload-credentials-provider-call)
+ [Memahami parameter `RefreshNow`](#workload-credentials-provider-refresh)
+ [Ambil rahasia di seluruh akun dengan rantai peran](#workload-credentials-provider-role-chaining)
+ [Pre-fetch rahasia saat startup](#workload-credentials-provider-prefetch)
+ [Konfigurasikan AWS Penyedia Kredensyal Beban Kerja](#workload-credentials-provider-config)
+ [Fitur opsional](#workload-credentials-provider-features)
+ [Pencatatan log](#workload-credentials-provider-log)
+ [Pertimbangan keamanan](#workload-credentials-provider-security)

## Membangun AWS Penyedia Kredensyal Beban Kerja
<a name="workload-credentials-provider-build"></a>

Sebelum Anda mulai, pastikan Anda memiliki alat pengembangan standar dan alat Rust yang diinstal untuk platform Anda.

**catatan**  
Membangun penyedia dengan `fips` fitur yang diaktifkan di macOS saat ini memerlukan solusi berikut:  
Buat variabel lingkungan `SDKROOT` yang disebut yang disetel ke hasil berjalan `xcrun --show-sdk-path`

------
#### [ RPM-based systems ]

**Untuk membangun RPM-based sistem**

1. Gunakan `install` skrip yang disediakan di repositori. 

   Skrip menghasilkan token SSRF acak saat startup dan menyimpannya dalam file. `/var/run/awssmatoken` Token dapat dibaca oleh `aws-wcp-token` grup yang dibuat oleh skrip penginstalan. 

1. Untuk memungkinkan aplikasi Anda membaca file token, Anda perlu menambahkan akun pengguna yang dijalankan aplikasi Anda ke `aws-wcp-token` grup. Misalnya, Anda dapat memberikan izin untuk aplikasi Anda untuk membaca file token dengan perintah usermod berikut, di mana {{<APP\_USER>}} ID pengguna tempat aplikasi Anda berjalan.

   ```
   sudo usermod -aG aws-wcp-token {{<APP_USER>}}
   ```

**Instal alat pengembangan**  
Pada RPM-based sistem seperti AL2023, instal grup Alat Pengembangan:

   ```
   sudo yum -y groupinstall "Development Tools"
   ```

1. 

**Instal Rust**  
Ikuti instruksi di [Install Rust](https://www.rust-lang.org/tools/install) dalam *dokumentasi Rust*:

   ```
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions
   . "$HOME/.cargo/env"
   ```

1. 

**Bangun penyedia**  
Buat Penyedia Kredensial AWS Beban Kerja menggunakan perintah cargo build:

   ```
   cargo build --release
   ```

   Anda akan menemukan executable di bawah. `target/release/aws-workload-credentials-provider`

------
#### [ Debian-based systems ]

**Untuk membangun Debian-based sistem**

1. 

**Instal alat pengembangan**  
Pada Debian-based sistem seperti Ubuntu, instal paket build-essential:

   ```
   sudo apt install build-essential
   ```

1. 

**Instal Rust**  
Ikuti instruksi di [Install Rust](https://www.rust-lang.org/tools/install) dalam *dokumentasi Rust*:

   ```
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions
   . "$HOME/.cargo/env"
   ```

1. 

**Bangun penyedia**  
Buat Penyedia Kredensial AWS Beban Kerja menggunakan perintah cargo build:

   ```
   cargo build --release
   ```

   Anda akan menemukan executable di bawah. `target/release/aws-workload-credentials-provider`

------
#### [ Windows ]

**Untuk membangun pada Windows**

1. 

**Menyiapkan lingkungan pengembangan**  
Ikuti petunjuk di [Siapkan lingkungan dev Anda di Windows for Rust](https://learn.microsoft.com/en-us/windows/dev-environment/rust/setup) dalam *dokumentasi Microsoft Windows*.

1. 

**Bangun penyedia**  
Buat Penyedia Kredensial AWS Beban Kerja menggunakan perintah cargo build:

   ```
   cargo build --release
   ```

   Anda akan menemukan executable di bawah. `target/release/aws-workload-credentials-provider.exe`

------
#### [ Cross-compile natively ]

**Untuk mengkompilasi silang secara asli**

1. 

**Instal alat kompilasi silang**  
Instal `cargo-xwin`:

   ```
   cargo install cargo-xwin
   ```

1. 

**Tambahkan target build Rust**  
Instal target build MSVC Windows:

   ```
   rustup target add x86_64-pc-windows-msvc
   ```

1. 

**Membangun untuk Windows**  
Cross-compile penyedia untuk Windows:

   ```
   cargo xwin build --release --target x86_64-pc-windows-msvc
   ```

   Anda akan menemukan executable di. `target/x86_64-pc-windows-msvc/release/aws-workload-credentials-provider.exe`

------

## Instal AWS Penyedia Kredensyal Beban Kerja
<a name="workload-credentials-provider-install"></a>

Pilih lingkungan komputasi Anda dari opsi penginstalan berikut.

------
#### [ Amazon EC2 ]

**Untuk menginstal AWS Penyedia Kredensyal Beban Kerja di Amazon EC2**

1. 

**Arahkan ke direktori konfigurasi**  
Ubah ke direktori konfigurasi:

   ```
   cd aws_workload_credentials_provider_common/configuration
   ```

1. 

**Jalankan skrip instalasi**  
Jalankan `install` skrip yang disediakan di repositori.

   Skrip menghasilkan token SSRF acak saat startup dan menyimpannya dalam file. `/var/run/awssmatoken` Token dapat dibaca oleh `aws-wcp-token` grup yang dibuat oleh skrip penginstalan.

1. 

**Konfigurasikan izin aplikasi**  
Tambahkan akun pengguna yang dijalankan aplikasi Anda ke `aws-wcp-token` grup:

   ```
   sudo usermod -aG aws-wcp-token {{APP_USER}}
   ```

   Ganti {{APP\_USER}} dengan ID pengguna tempat aplikasi Anda berjalan.

------
#### [ Container Sidecar ]

Anda dapat menjalankan AWS Workload Credentials Provider sebagai wadah sidecar bersama aplikasi Anda dengan menggunakan Docker. Kemudian aplikasi Anda dapat mengambil rahasia dari server HTTP lokal yang disediakan Penyedia Kredensial AWS Beban Kerja. Untuk informasi tentang Docker, lihat [dokumentasi Docker](https://docs.docker.com).

**Untuk membuat wadah sespan untuk AWS Penyedia Kredensyal Beban Kerja**

1. 

**Buat penyedia Dockerfile**  
Buat Dockerfile untuk wadah sespan Penyedia Kredensial AWS Beban Kerja:

   ```
   # Use the latest Debian image as the base
   FROM debian:latest
   
   # Set the working directory inside the container
   WORKDIR /app 
   
   # Copy the Workload Credentials Provider binary to the container
   COPY aws-workload-credentials-provider . 
   
   # Install any necessary dependencies
   RUN apt-get update && apt-get install -y ca-certificates 
   
   # Set the entry point to run the provider
   ENTRYPOINT ["./aws-workload-credentials-provider", "sm", "start"]
   ```

1. 

**Buat aplikasi Dockerfile**  
Buat Dockerfile untuk aplikasi klien Anda.

1. 

**Buat file Docker Compose**  
Buat file Docker Compose untuk menjalankan kedua kontainer dengan antarmuka jaringan bersama:
**penting**  
Anda harus memuat AWS kredensyal dan token SSRF agar aplikasi dapat menggunakan Penyedia Kredensial Beban Kerja.AWS Untuk Amazon EKS dan Amazon ECS, lihat yang berikut ini:  
[Mengelola akses](https://docs.aws.amazon.com/eks/latest/userguide/cluster-auth.html) di *Panduan Pengguna Amazon EKS*
[Peran IAM tugas Amazon ECS dalam Panduan](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) Pengembang *Amazon ECS*

   ```
   version: '3'
   services:
       client-application:
       container_name: client-application
       build:
           context: .
           dockerfile: Dockerfile.client
       command: tail -f /dev/null  # Keep the container running
       
   
       workload-credentials-provider:
       container_name: workload-credentials-provider
       build:
           context: .
           dockerfile: Dockerfile.provider
       network_mode: "container:client-application"  # Attach to the client-application container's network
       depends_on:
           - client-application
   ```

1. 

**Salin biner penyedia**  
Salin `aws-workload-credentials-provider` biner ke direktori yang sama yang berisi file Dockerfiles dan Docker Compose Anda.

1. 

**Membangun dan menjalankan kontainer**  
Buat dan jalankan container menggunakan Docker Compose:

   ```
   docker-compose up --build
   ```

1. 

**Langkah selanjutnya**  
Anda sekarang dapat menggunakan Penyedia Kredensial AWS Beban Kerja untuk mengambil rahasia dari wadah klien Anda. Untuk informasi selengkapnya, lihat [Ambil rahasia dengan AWS Penyedia Kredensyal Beban Kerja](#workload-credentials-provider-call).

------
#### [ Lambda ]

Anda dapat [mengemas Penyedia Kredensial AWS Beban Kerja sebagai ekstensi Lambda](https://docs.aws.amazon.com/lambda/latest/dg/packaging-layers.html). Kemudian Anda dapat [menambahkannya ke fungsi Lambda Anda sebagai lapisan](https://docs.aws.amazon.com/lambda/latest/dg/adding-layers.html) dan memanggil Penyedia Kredensial AWS Beban Kerja dari fungsi Lambda Anda untuk mendapatkan rahasia.

Petunjuk berikut menunjukkan cara mendapatkan nama rahasia *MyTest*dengan menggunakan skrip contoh `secrets-manager-provider-extension.sh` di GitHub repositori [aws-workload-credentials-provider untuk menginstal Penyedia Kredensial](https://github.com/aws/aws-workload-credentials-provider) Beban Kerja sebagai ekstensi Lambda.AWS

**Untuk membuat ekstensi Lambda untuk AWS Penyedia Kredensyal Beban Kerja**

1. 

**Package layer penyedia**  
Dari root paket kode Penyedia Kredensial AWS Beban Kerja, jalankan perintah berikut:

   ```
   AWS_ACCOUNT_ID={{AWS_ACCOUNT_ID}}
   LAMBDA_ARN={{LAMBDA_ARN}}
   
   # Build the release binary 
   cargo build --release --target=x86_64-unknown-linux-gnu
   
   # Copy the release binary into the `bin` folder
   mkdir -p ./bin
   cp ./target/x86_64-unknown-linux-gnu/release/aws-workload-credentials-provider ./bin/aws-workload-credentials-provider
   
   # Copy the `secrets-manager-provider-extension.sh` example script into the `extensions` folder.
   mkdir -p ./extensions
   cp aws_secretsmanager_provider/examples/example-lambda-extension/secrets-manager-provider-extension.sh ./extensions
   
   # Zip the extension shell script and the binary 
   zip secrets-manager-provider-extension.zip bin/* extensions/*
   
   # Publish the layer version
   LAYER_VERSION_ARN=$(aws lambda publish-layer-version \
       --layer-name secrets-manager-provider-extension \
       --zip-file "fileb://secrets-manager-provider-extension.zip" | jq -r '.LayerVersionArn')
   ```

1. 

**Konfigurasikan token SSRF**  
Konfigurasi default penyedia akan secara otomatis mengatur token SSRF ke nilai yang ditetapkan dalam variabel pra-set `AWS_SESSION_TOKEN` atau `AWS_CONTAINER_AUTHORIZATION_TOKEN` lingkungan (variabel terakhir untuk fungsi Lambda dengan diaktifkan). SnapStart Atau, Anda dapat menentukan variabel `AWS_TOKEN` lingkungan dengan nilai arbitrer untuk fungsi Lambda Anda sebagai gantinya karena variabel ini lebih diutamakan daripada dua lainnya. Jika Anda memilih untuk menggunakan variabel `AWS_TOKEN` lingkungan, Anda harus mengatur variabel lingkungan dengan `lambda:UpdateFunctionConfiguration` panggilan.

1. 

**Pasang lapisan ke fungsi**  
Lampirkan versi layer ke fungsi Lambda Anda:

   ```
   # Attach the layer version to the Lambda function
   aws lambda update-function-configuration \
       --function-name $LAMBDA_ARN \
       --layers "$LAYER_VERSION_ARN"
   ```

1. 

**Perbarui kode fungsi**  
Perbarui fungsi Lambda Anda untuk melakukan kueri `http://localhost:2773/secretsmanager/get?secretId=MyTest` dengan nilai `X-Aws-codes-Secrets-Token` header yang disetel ke nilai token SSRF yang bersumber dari salah satu variabel lingkungan yang disebutkan di atas untuk mengambil rahasia. Pastikan untuk menerapkan logika coba lagi dalam kode aplikasi Anda untuk mengakomodasi penundaan inisialisasi dan pendaftaran ekstensi Lambda.

1. 

**Uji fungsi**  
Memanggil fungsi Lambda untuk memverifikasi bahwa rahasia sedang diambil dengan benar.

------

## Ambil rahasia dengan AWS Penyedia Kredensyal Beban Kerja
<a name="workload-credentials-provider-call"></a>

Untuk mengambil rahasia, panggil titik akhir Penyedia Kredensial AWS Beban Kerja lokal dengan nama rahasia atau ARN sebagai parameter kueri. Secara default, Penyedia Kredensial AWS Beban Kerja mengambil `AWSCURRENT` versi rahasia. Untuk mengambil versi yang berbeda, gunakan parameter versionStage atau VersionId.

**penting**  
Untuk membantu melindungi Penyedia Kredensyal AWS Beban Kerja, Anda harus menyertakan header token SSRF sebagai bagian dari setiap permintaan:. `X-Aws-Parameters-Secrets-Token` Penyedia Kredensial AWS Beban Kerja menolak permintaan yang tidak memiliki header ini atau yang memiliki token SSRF tidak valid. Anda dapat menyesuaikan nama header SSRF di file. [Konfigurasikan AWS Penyedia Kredensyal Beban Kerja](#workload-credentials-provider-config)

### Izin yang diperlukan
<a name="provider-call-permissions"></a>

[Penyedia Kredensial AWS Beban Kerja menggunakan AWS SDK for Rust, yang menggunakan rantai penyedia kredensyal.AWS](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html) Identitas kredensyal IAM ini menentukan izin yang dimiliki Penyedia Kredensyal AWS Beban Kerja untuk mengambil rahasia.
+ `secretsmanager:DescribeSecret`
+ `secretsmanager:GetSecretValue`

Untuk informasi selengkapnya tentang izin, lihat [Referensi izin untuk AWS Secrets Manager](auth-and-access.md#reference_iam-permissions).

**penting**  
Setelah nilai rahasia ditarik ke Penyedia Kredensial AWS Beban Kerja, setiap pengguna yang memiliki akses ke lingkungan komputasi dan token SSRF dapat mengakses rahasia dari cache Penyedia Kredensyal Beban Kerja.AWS Untuk informasi selengkapnya, lihat [Pertimbangan keamanan](#workload-credentials-provider-security).

### Permintaan contoh
<a name="provider-call-examples"></a>

------
#### [ curl ]

**Example Contoh - Dapatkan rahasia menggunakan curl**  
Contoh curl berikut menunjukkan cara mendapatkan rahasia dari Penyedia Kredensial AWS Beban Kerja. Contohnya bergantung pada SSRF yang ada dalam file, yang mana ia disimpan oleh skrip instalasi.  

```
curl -v -H \
    "X-Aws-Parameters-Secrets-Token: $(</var/run/awssmatoken)" \
    'http://localhost:2773/secretsmanager/get?secretId={{YOUR_SECRET_ID}}'
```

------
#### [ Python ]

**Example Contoh - Dapatkan rahasia menggunakan Python**  
Contoh Python berikut menunjukkan bagaimana untuk mendapatkan rahasia dari AWS Workload Credentials Provider. Contohnya bergantung pada SSRF yang ada dalam file, yang mana ia disimpan oleh skrip instalasi.  

```
import requests
import json

# Function that fetches the secret from AWS Workload Credentials Provider for the provided secret id. 
def get_secret():
    # Construct the URL for the GET request
    url = f"http://localhost:2773/secretsmanager/get?secretId={{YOUR_SECRET_ID}}"

    # Get the SSRF token from the token file
    with open('/var/run/awssmatoken') as fp:
        token = fp.read() 

    headers = {
        "X-Aws-Parameters-Secrets-Token": token.strip()
    }

    try:
        # Send the GET request with headers
        response = requests.get(url, headers=headers)

        # Check if the request was successful
        if response.status_code == 200:
            # Return the secret value
            return response.text
        else:
            # Handle error cases
            raise Exception(f"Status code {response.status_code} - {response.text}")

    except Exception as e:
        # Handle network errors
        raise Exception(f"Error: {e}")
```

------

## Memahami parameter `RefreshNow`
<a name="workload-credentials-provider-refresh"></a>

Penyedia Kredensial AWS Beban Kerja menggunakan cache dalam memori untuk menyimpan nilai rahasia, yang disegarkan secara berkala. Secara default, penyegaran ini terjadi ketika Anda meminta rahasia setelah Time to Live (TTL) kedaluwarsa, biasanya setiap 300 detik. Namun, pendekatan ini terkadang dapat menghasilkan nilai rahasia basi, terutama jika rahasia berputar sebelum entri cache kedaluwarsa.

Untuk mengatasi batasan ini, Penyedia Kredensial AWS Beban Kerja mendukung parameter yang disebut `refreshNow` di URL. Anda dapat menggunakan parameter ini untuk memaksa penyegaran langsung nilai rahasia, melewati cache dan memastikan Anda memiliki informasi terbaru.

**Perilaku default (tanpa`refreshNow`)**  
+ Menggunakan nilai cache sampai TTL kedaluwarsa
+ Menyegarkan rahasia hanya setelah TTL (default 300 detik)
+ Dapat mengembalikan nilai basi jika rahasia berputar sebelum cache kedaluwarsa

**Perilaku dengan `refreshNow=true`**  
+ Melewati cache sepenuhnya
+ Mengambil nilai rahasia terbaru langsung dari Secrets Manager
+ Memperbarui cache dengan nilai segar dan mengatur ulang TTL
+ Memastikan Anda selalu mendapatkan nilai rahasia terbaru

### Force-refresh nilai rahasia
<a name="refreshnow-examples"></a>

**penting**  
Nilai default `refreshNow` adalah `false`. Ketika disetel ke`true`, itu akan mengganti TTL yang ditentukan dalam file konfigurasi Penyedia Kredensial AWS Beban Kerja dan membuat panggilan API ke Secrets Manager.

------
#### [ curl ]

**Example Contoh - Force-refresh rahasia menggunakan curl**  
Contoh curl berikut menunjukkan cara memaksa Penyedia Kredensial AWS Beban Kerja untuk menyegarkan rahasia. Contohnya bergantung pada SSRF yang ada dalam file, yang mana ia disimpan oleh skrip instalasi.  

```
curl -v -H \
"X-Aws-Parameters-Secrets-Token: $(</var/run/awssmatoken)" \
'http://localhost:2773/secretsmanager/get?secretId={{YOUR_SECRET_ID}}&refreshNow=true'
```

------
#### [ Python ]

**Example Contoh - Force-refresh rahasia menggunakan Python**  
Contoh Python berikut menunjukkan bagaimana untuk mendapatkan rahasia dari AWS Workload Credentials Provider. Contohnya bergantung pada SSRF yang ada dalam file, yang mana ia disimpan oleh skrip instalasi.  

```
import requests
import json

# Function that fetches the secret from AWS Workload Credentials Provider for the provided secret id. 
def get_secret():
    # Construct the URL for the GET request
    url = f"http://localhost:2773/secretsmanager/get?secretId={{YOUR_SECRET_ID}}&refreshNow=true"

    # Get the SSRF token from the token file
    with open('/var/run/awssmatoken') as fp:
        token = fp.read() 

    headers = {
        "X-Aws-Parameters-Secrets-Token": token.strip()
    }

    try:
        # Send the GET request with headers
        response = requests.get(url, headers=headers)

        # Check if the request was successful
        if response.status_code == 200:
            # Return the secret value
            return response.text
        else:
            # Handle error cases
            raise Exception(f"Status code {response.status_code} - {response.text}")

    except Exception as e:
        # Handle network errors
        raise Exception(f"Error: {e}")
```

------

## Ambil rahasia di seluruh akun dengan rantai peran
<a name="workload-credentials-provider-role-chaining"></a>

Role chaining memungkinkan Penyedia Kredensial AWS Beban Kerja untuk mengambil rahasia dari AWS akun lain dengan mengasumsikan peran IAM menggunakan.AWS STS`AssumeRole` Penyedia Kredensial AWS Beban Kerja membuat dan menyimpan klien caching terpisah untuk setiap peran unik ARN. Setiap klien peran mempertahankan cache independennya sendiri, sehingga rahasia yang sama diambil dengan peran yang berbeda memiliki entri cache terpisah.

### Izin yang diperlukan
<a name="provider-role-chaining-permissions"></a>

Untuk menggunakan rantai peran, Anda memerlukan yang berikut ini:
+ Kredensyal lingkungan Penyedia Kredensial AWS Beban Kerja harus memiliki `sts:AssumeRole` izin pada ARN peran target.
+ Peran target harus memiliki `secretsmanager:GetSecretValue` dan `secretsmanager:DescribeSecret` izin untuk rahasia yang ingin Anda akses.
+ Kebijakan kepercayaan peran target harus memungkinkan identitas Penyedia Kredensial AWS Beban Kerja untuk mengasumsikannya.

### Ambil rahasia lintas akun
<a name="provider-role-chaining-usage"></a>

Sertakan parameter `roleArn` kueri dalam permintaan Anda ke Penyedia Kredensial AWS Beban Kerja untuk menentukan peran mana yang akan diambil untuk pengambilan rahasia.

------
#### [ curl ]

**Example Contoh - Cross-account rahasia menggunakan curl**  

```
curl -v -H \
    "X-Aws-Parameters-Secrets-Token: $(</var/run/awssmatoken)" \
    'http://localhost:2773/secretsmanager/get?secretId={{YOUR_SECRET_ID}}&roleArn=arn:aws:iam::{{ACCOUNT_ID}}:role/{{ROLE_NAME}}'
```

------
#### [ Python ]

**Example Contoh - Cross-account rahasia menggunakan Python**  

```
import requests

def get_secret_cross_account():
    secret_id = "{{YOUR_SECRET_ID}}"
    role_arn = "arn:aws:iam::{{ACCOUNT_ID}}:role/{{ROLE_NAME}}"
    url = f"http://localhost:2773/secretsmanager/get?secretId={secret_id}&roleArn={role_arn}"

    with open('/var/run/awssmatoken') as fp:
        token = fp.read()

    headers = {
        "X-Aws-Parameters-Secrets-Token": token.strip()
    }

    try:
        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.text
        else:
            raise Exception(f"Status code {response.status_code} - {response.text}")

    except Exception as e:
        raise Exception(f"Error: {e}")
```

------

### Konfigurasi dan batasan rantai peran
<a name="provider-role-chaining-config"></a>

Konfigurasikan rantai peran dengan `max_roles` opsi di file konfigurasi TOMB Anda. Ini menetapkan jumlah maksimum peran yang diasumsikan secara simultan, dalam kisaran 1 hingga 20. Defaultnya adalah 20.

**penting**  
Peran yang diasumsikan tidak dikeluarkan dari cache peran Penyedia Kredensyal AWS Beban Kerja. Setelah jumlah maksimum peran tercapai, permintaan dengan ARN peran baru ditolak dengan `400` kesalahan hingga Penyedia Kredensyal AWS Beban Kerja dimulai ulang.Tanggapan kesalahan untuk rantai peran

**`400`**  
`roleArn`Formatnya tidak valid atau jumlah maksimum peran yang diasumsikan telah tercapai.

**`403`**  
AWS STS`AssumeRole`Panggilan gagal. Verifikasi bahwa kebijakan kepercayaan peran target memungkinkan identitas Penyedia Kredensyal AWS Beban Kerja untuk mengasumsikannya.

## Pre-fetch rahasia saat startup
<a name="workload-credentials-provider-prefetch"></a>

Secara default, Penyedia Kredensial AWS Beban Kerja mengambil rahasia sesuai permintaan saat aplikasi Anda memintanya. Dengan pra-pengambilan, Penyedia Kredensial AWS Beban Kerja memuat rahasia tertentu ke dalam cache saat dijalankan, sehingga aplikasi Anda dapat segera mengaksesnya tanpa menunggu panggilan API pertama. Pre-fetching berjalan sebagai tugas latar belakang—Penyedia Kredensyal AWS Beban Kerja mulai menerima permintaan dengan segera dan tidak memblokir penyelesaian pra-pengambilan.

Anda dapat menentukan rahasia untuk diambil sebelumnya dengan dua cara:
+ **Rahasia eksplisit** — Daftar ID rahasia atau ARN tertentu.
+ **Tag-based penemuan** — Temukan rahasia dengan kunci tag. Penyedia Kredensial AWS Beban Kerja mengambil semua rahasia yang memiliki tag yang ditentukan.

### Izin yang diperlukan
<a name="provider-prefetch-permissions"></a>

Selain izin standar untuk mengambil rahasia, pra-pengambilan membutuhkan yang berikut:
+ `secretsmanager:BatchGetSecretValue`— Diperlukan untuk semua operasi pra-pengambilan.
+ `secretsmanager:ListSecrets`— Diperlukan hanya saat menggunakan penemuan berbasis tag.

### Konfigurasikan pra-pengambilan
<a name="provider-prefetch-config"></a>

Tambahkan `[capabilities.secrets_manager.prefetch]` bagian ke file konfigurasi TOMB Anda. Pilihan berikut tersedia:

**`cache_buffer_ratio`**  
Fraksi maksimum cache yang harus diisi per klien selama pra-pengambilan, dalam kisaran 0,1 hingga 1,0. Defaultnya adalah 0,8. Ketika batas buffer tercapai, Penyedia Kredensial AWS Beban Kerja berhenti mengambil rahasia yang tersisa—itu tidak mengusir entri cache yang ada. Rahasia yang tidak dimuat selama pra-pengambilan masih tersedia sesuai permintaan.

**`max_jitter_seconds`**  
Penundaan acak dalam hitungan detik sebelum pra-pengambilan dimulai, dalam kisaran 0 hingga 10. Default-nya adalah 0. Gunakan ini untuk mencegah panggilan API di seluruh armada yang disinkronkan saat beberapa penyedia memulai pada waktu yang bersamaan.

**Example Pre-fetch konfigurasi dengan rahasia eksplisit**  

```
[capabilities.secrets_manager.prefetch]
cache_buffer_ratio = 0.6
max_jitter_seconds = 5
secrets = [
    { secret_id = "arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-AbCdEf" },
    { secret_id = "MyOtherSecret" },
]
```

**Example Pre-fetch konfigurasi dengan penemuan berbasis tag**  

```
[capabilities.secrets_manager.prefetch]
cache_buffer_ratio = 0.8
filter_tags = [
    { key = "Environment" },
    { key = "Team" },
]
```

Anda juga dapat menggabungkan rahasia eksplisit dan penemuan berbasis tag dalam konfigurasi yang sama. Untuk pra-pengambilan lintas akun, tambahkan bidang. `role_arn` Untuk informasi selengkapnya, lihat [Ambil rahasia di seluruh akun dengan rantai peran](#workload-credentials-provider-role-chaining).

**Example Pre-fetch konfigurasi dengan akses lintas akun**  

```
[capabilities.secrets_manager.prefetch]
cache_buffer_ratio = 0.6
max_jitter_seconds = 5
secrets = [
    { secret_id = "arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-AbCdEf" },
    { secret_id = "cross-account-secret", role_arn = "arn:aws:iam::987654321098:role/SecretAccessRole" },
]
filter_tags = [
    { key = "Environment" },
    { key = "Team", role_arn = "arn:aws:iam::987654321098:role/SecretAccessRole" },
]
```

## Konfigurasikan AWS Penyedia Kredensyal Beban Kerja
<a name="workload-credentials-provider-config"></a>

Untuk mengubah konfigurasi Penyedia Kredensial AWS Beban Kerja, buat file konfigurasi [TOMB](https://toml.io/en/), lalu panggil. `./aws-workload-credentials-provider sm start --config config.toml`

File konfigurasi mendukung format bersarang. Opsi Secrets Manager ditempatkan di bawah`[capabilities.secrets_manager]`, dengan sub-bagian untuk pengaturan cache dan keamanan. Opsi logging ditempatkan di bawah`[logging]`.

**Example Contoh file konfigurasi bersarang**  

```
[logging]
log_level = "INFO"
log_to_file = true

[capabilities.secrets_manager]
enabled = true
http_port = 2773
region = "us-east-1"
path_prefix = "/v1/"
max_conn = 800
max_roles = 20

[capabilities.secrets_manager.cache]
ttl_seconds = 300
cache_size = 1000

[capabilities.secrets_manager.security]
ssrf_headers = ["X-Aws-Parameters-Secrets-Token", "X-Vault-Token"]
ssrf_env_variables = ["AWS_TOKEN", "AWS_SESSION_TOKEN", "AWS_CONTAINER_AUTHORIZATION_TOKEN"]
```

**catatan**  
Tombol datar di tingkat root (misalnya,`http_port = 2773`) masih didukung untuk kompatibilitas mundur dengan file konfigurasi yang ada.Opsi konfigurasi Secrets Manager

**`enabled`**  
Apakah kemampuan Secrets Manager aktif: `true` atau`false`. Nilai default-nya `true`.

**`http_port`**  
Port untuk server HTTP lokal, dalam kisaran 1024 hingga 65535. Defaultnya adalah 2773.

**`region`**  
AWS Wilayah yang akan digunakan untuk permintaan. Jika tidak ada Wilayah yang ditentukan, Penyedia Kredensial AWS Beban Kerja menentukan Wilayah dari SDK. Untuk informasi selengkapnya, lihat [Menentukan kredensyal dan Wilayah default Anda](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html) di *AWS SDK for Rust* Developer Guide.

**`path_prefix`**  
Awalan URI digunakan untuk menentukan apakah permintaan adalah permintaan berbasis jalur. Defaultnya adalah “/v1/”.

**`max_conn`**  
Jumlah maksimum koneksi dari klien HTTP yang diizinkan oleh Penyedia Kredensial AWS Beban Kerja, dalam kisaran 1 hingga 1000. Defaultnya adalah 800.

**`max_roles`**  
Jumlah maksimum peran IAM simultan untuk akses lintas akun, dalam kisaran 1 hingga 20. Defaultnya adalah 20. Untuk informasi selengkapnya, lihat [Ambil rahasia di seluruh akun dengan rantai peran](#workload-credentials-provider-role-chaining).Opsi cache (`[capabilities.secrets_manager.cache`])

**`ttl_seconds`**  
TTL dalam hitungan detik untuk item yang di-cache, dalam kisaran 0 hingga 3600. Defaultnya adalah 300. 0 menunjukkan bahwa tidak ada caching.

**`cache_size`**  
Jumlah maksimum rahasia yang dapat disimpan dalam cache, dalam kisaran 1 hingga 1000. Defaultnya adalah 1000.Opsi keamanan (`[capabilities.secrets_manager.security`])

**`ssrf_headers`**  
Daftar nama header yang diperiksa oleh Penyedia Kredensial AWS Beban Kerja untuk token SSRF. Defaultnya adalah "X-Aws-Parameters-Secrets-Token, X-Vault-Token”.

**`ssrf_env_variables`**  
Daftar variabel lingkungan menamai Penyedia Kredensial AWS Beban Kerja yang diperiksa secara berurutan untuk token SSRF. Variabel lingkungan dapat berisi token atau referensi ke file token seperti pada:`AWS_TOKEN=file:///var/run/awssmatoken`. Defaultnya adalah "AWS\_TOKEN, AWS\_SESSION\_TOKEN, AWS\_CONTAINER\_AUTHORIZATION\_TOKEN”.Opsi pencatatan (`[logging]`)

**`log_level`**  
Tingkat detail yang dilaporkan dalam log untuk Penyedia Kredensial AWS Beban Kerja: DEBUG, INFO, WARN, ERROR, atau NONE. Defaultnya adalah INFO.

**`log_to_file`**  
Apakah akan masuk ke file atau stdout/stderr: `true` atau`false`. Nilai default-nya `true`.

## Fitur opsional
<a name="workload-credentials-provider-features"></a>

Penyedia Kredensial AWS Beban Kerja dapat dibuat dengan fitur opsional dengan meneruskan tanda ke. `--features` `cargo build` Fitur yang tersedia adalah:Membangun fitur

**`prefer-post-quantum`**  
Membuat `X25519MLKEM768` algoritma pertukaran kunci prioritas tertinggi. Jika tidak, itu tersedia tetapi tidak prioritas tertinggi. `X25519MLKEM768`adalah algoritma pertukaran kunci hybrid, pasca-kuantum aman.

**`fips`**  
Membatasi cipher suite yang digunakan oleh penyedia hanya untuk cipher. FIPS-approved

## Pencatatan log
<a name="workload-credentials-provider-log"></a>

**Penebangan lokal**  
Penyedia Kredensial AWS Beban Kerja mencatat kesalahan secara lokal ke file `logs/secrets_manager_provider.log` atau stdout/stderr bergantung pada variabel konfigurasi. `log_to_file` Saat aplikasi Anda memanggil Penyedia Kredensial AWS Beban Kerja untuk mendapatkan rahasia, panggilan tersebut akan muncul di log lokal. Mereka tidak muncul di CloudTrail log.

**Rotasi log**  
Penyedia Kredensial AWS Beban Kerja membuat file log baru ketika file mencapai 10 MB, dan menyimpan hingga lima file log total.

**AWS pencatatan layanan**  
Log tidak masuk ke Secrets Manager, CloudTrail, atau CloudWatch. Permintaan untuk mendapatkan rahasia dari Penyedia Kredensyal AWS Beban Kerja tidak muncul di log tersebut. Ketika Penyedia Kredensial AWS Beban Kerja melakukan panggilan ke Secrets Manager untuk mendapatkan rahasia, panggilan tersebut direkam CloudTrail dengan string agen pengguna yang berisi. `aws-workload-credentials-provider`

Anda dapat mengonfigurasi opsi logging di file[Konfigurasikan AWS Penyedia Kredensyal Beban Kerja](#workload-credentials-provider-config).

## Pertimbangan keamanan
<a name="workload-credentials-provider-security"></a>

**Domain kepercayaan**  
Untuk arsitektur penyedia lokal, domain kepercayaan adalah tempat titik akhir penyedia dan token SSRF dapat diakses, yang biasanya merupakan seluruh host. Domain kepercayaan untuk Penyedia Kredensyal AWS Beban Kerja harus sesuai dengan domain tempat kredensyal Secrets Manager tersedia untuk mempertahankan postur keamanan yang sama. Misalnya, di Amazon EC2 domain kepercayaan untuk Penyedia Kredensyal AWS Beban Kerja akan sama dengan domain kredensyal saat menggunakan peran untuk Amazon EC2.

**penting**  
Aplikasi sadar keamanan yang belum menggunakan solusi berbasis penyedia dengan kredensyal Secrets Manager yang dikunci ke aplikasi harus mempertimbangkan untuk menggunakan SDK atau solusi caching khusus bahasa AWS. Untuk informasi selengkapnya, lihat [Mendapatkan rahasia](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html).