Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

# Uso de AWS Proveedor de credenciales de carga de trabajo
<a name="workload-credentials-provider"></a>

## Cómo el AWS Funciona el proveedor de credenciales de carga de trabajo
<a name="provider-overview"></a>

El proveedor de credenciales de AWS carga de trabajo (anteriormente denominado AWS Secrets Manager Agente) proporciona un servicio HTTP del lado del cliente que le ayuda a estandarizar la forma en que consume los secretos de Secrets Manager en sus entornos informáticos. Puede utilizarlo con los siguientes servicios:
+ AWS Lambda
+ Amazon Elastic Container Service
+ Amazon Elastic Kubernetes Service
+ Amazon Elastic Compute Cloud

El proveedor AWS de credenciales de carga de trabajo recupera y almacena en caché los secretos en la memoria, lo que permite a sus aplicaciones obtener los secretos de localhost en lugar de realizar llamadas directas a Secrets Manager. El proveedor AWS de credenciales de Workload solo puede leer los secretos, no puede modificarlos.

El proveedor de credenciales AWS de carga de trabajo es de código abierto. El código fuente, las instrucciones de instalación y la información sobre la versión más reciente están disponibles en [GitHub](https://github.com/aws/aws-workload-credentials-provider).

**importante**  
El proveedor AWS de credenciales de carga de trabajo utiliza las AWS credenciales de su entorno para llamar a Secrets Manager. Incluye protección contra la falsificación de solicitudes del lado del servidor (SSRF) para ayudar a mejorar la seguridad del secreto. De forma predeterminada, el proveedor de credenciales de AWS Workload utiliza el intercambio de ML-KEM claves poscuántico como el intercambio de claves de mayor prioridad.

## Descripción AWS Almacenamiento en caché del proveedor de credenciales de carga de trabajo
<a name="provider-caching"></a>

El proveedor AWS de credenciales de carga de trabajo utiliza una caché en memoria que se restablece cuando se reinicia el proveedor de credenciales de AWS carga de trabajo. Regularmente, actualiza los valores de secretos almacenados en caché según lo siguiente:
+ La frecuencia de actualización predeterminada (TTL) es de 300 segundos
+ Se puede modificar TTL mediante un archivo de configuración
+ La actualización se produce cuando se solicita un secreto después de que TTL caduque

**nota**  
El proveedor de credenciales AWS de carga de trabajo no incluye la invalidación de la caché. Si un secreto rota antes de que caduque la entrada de la caché, el proveedor de credenciales de AWS carga de trabajo podría devolver un valor secreto obsoleto.

El proveedor AWS de credenciales de carga de trabajo devuelve valores secretos en el mismo formato que la respuesta de. `GetSecretValue` Los valores de secretos no se cifran en caché.

**Topics**
+ [Cómo el AWS Funciona el proveedor de credenciales de carga de trabajo](#provider-overview)
+ [Descripción AWS Almacenamiento en caché del proveedor de credenciales de carga de trabajo](#provider-caching)
+ [Cree el AWS Proveedor de credenciales de carga de trabajo](#workload-credentials-provider-build)
+ [Instala la AWS Proveedor de credenciales de carga de trabajo](#workload-credentials-provider-install)
+ [Recupera los secretos con AWS Proveedor de credenciales de carga de trabajo](#workload-credentials-provider-call)
+ [Descripción del parámetro `RefreshNow`](#workload-credentials-provider-refresh)
+ [Recupera los secretos de las cuentas mediante el encadenamiento de roles](#workload-credentials-provider-role-chaining)
+ [Pre-fetch secretos al inicio](#workload-credentials-provider-prefetch)
+ [Configure el AWS Proveedor de credenciales de carga de trabajo](#workload-credentials-provider-config)
+ [Características opcionales](#workload-credentials-provider-features)
+ [Registro](#workload-credentials-provider-log)
+ [Consideraciones de seguridad](#workload-credentials-provider-security)

## Cree el AWS Proveedor de credenciales de carga de trabajo
<a name="workload-credentials-provider-build"></a>

Antes de comenzar, asegúrese de tener instaladas las herramientas de desarrollo estándar y las herramientas de Rust en la plataforma.

**nota**  
La creación del proveedor con la `fips` función habilitada en macOS requiere actualmente la siguiente solución alternativa:  
Cree una variable de entorno llamada `SDKROOT` que se establezca según el resultado de la ejecución de `xcrun --show-sdk-path`

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

**Para construir sobre sistemas RPM-based**

1. Use el script de `install` que se proporciona en el repositorio. 

   El script genera un token SSRF aleatorio al inicio y lo almacena en el archivo`/var/run/awssmatoken`. El grupo `aws-wcp-token` que crea el script de instalación puede leer el token. 

1. Para permitir que la aplicación lea el archivo de token, debe añadir, al grupo `aws-wcp-token`, la cuenta de usuario con la que se ejecuta la aplicación. Por ejemplo, puedes conceder permisos para que tu aplicación lea el archivo token con el siguiente comando usermod, que {{<APP\_USER>}} es el ID de usuario con el que se ejecuta la aplicación.

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

**Instale las herramientas de desarrollo**  
En RPM-based sistemas como el AL2023, instale el grupo de herramientas de desarrollo:

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

1. 

**Instale Rust**  
Siga las instrucciones de [Instalar Rust](https://www.rust-lang.org/tools/install) en la *documentación de Rust*.

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

1. 

**Cree el proveedor**  
Cree el proveedor AWS de credenciales de carga de trabajo mediante el comando cargo build:

   ```
   cargo build --release
   ```

   Encontrará el ejecutable en `target/release/aws-workload-credentials-provider`.

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

**Para construir sobre Debian-based sistemas**

1. 

**Instale las herramientas de desarrollo**  
En Debian-based sistemas como Ubuntu, instale el paquete build-essential:

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

1. 

**Instale Rust**  
Siga las instrucciones de [Instalar Rust](https://www.rust-lang.org/tools/install) en la *documentación de Rust*.

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

1. 

**Cree el proveedor**  
Cree el proveedor AWS de credenciales de carga de trabajo mediante el comando cargo build:

   ```
   cargo build --release
   ```

   Encontrará el ejecutable en `target/release/aws-workload-credentials-provider`.

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

**Cómo compilar en Windows**

1. 

**Establezca un entorno de desarrollo**  
Siga las instrucciones de [Configurar el entorno de desarrollo en Windows para Rust](https://learn.microsoft.com/en-us/windows/dev-environment/rust/setup) en la *documentación de Microsoft Windows*.

1. 

**Cree el proveedor**  
Cree el proveedor AWS de credenciales de carga de trabajo mediante el comando cargo build:

   ```
   cargo build --release
   ```

   Encontrará el ejecutable en `target/release/aws-workload-credentials-provider.exe`.

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

**Cómo compilar de forma cruzada de forma nativa**

1. 

**Instale las herramientas de compilación cruzada**  
Instale `cargo-xwin`:

   ```
   cargo install cargo-xwin
   ```

1. 

**Agregue los destinos de compilación de Rust**  
Instale el objetivo de compilación de MSVC para Windows:

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

1. 

**Compile para Windows**  
Cross-compile el proveedor de Windows:

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

   Encontrará el ejecutable en `target/x86_64-pc-windows-msvc/release/aws-workload-credentials-provider.exe`.

------

## Instala la AWS Proveedor de credenciales de carga de trabajo
<a name="workload-credentials-provider-install"></a>

Elija su entorno informático entre las siguientes opciones de instalación.

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

**Para instalar la de AWS Proveedor de credenciales de carga de trabajo en Amazon EC2**

1. 

**Diríjase hasta el directorio de configuración**  
Cambie al directorio de configuración:

   ```
   cd aws_workload_credentials_provider_common/configuration
   ```

1. 

**Ejecute el script de instalación**  
Utilice el script de `install` que se proporciona en el repositorio.

   El script genera un token SSRF aleatorio al inicio y lo almacena en el archivo`/var/run/awssmatoken`. El grupo `aws-wcp-token` que crea el script de instalación puede leer el token.

1. 

**Configuración de permisos de aplicación**  
Agregue al grupo `aws-wcp-token` la cuenta de usuario con la que se ejecuta la aplicación:

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

   {{APP\_USER}}Sustitúyalo por el ID de usuario con el que se ejecuta la aplicación.

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

Puede ejecutar el proveedor de credenciales de AWS carga de trabajo como un contenedor auxiliar junto con su aplicación mediante Docker. A continuación, la aplicación podrá recuperar los datos secretos del servidor HTTP local que proporciona el proveedor de credenciales AWS de carga de trabajo. Para obtener más información sobre Docker, consulte la[ documentación de Docker](https://docs.docker.com).

**Para crear un contenedor lateral para el AWS Proveedor de credenciales de carga de trabajo**

1. 

**Cree el Dockerfile del proveedor**  
Cree un Dockerfile para el contenedor lateral del proveedor de credenciales de AWS carga de trabajo:

   ```
   # 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. 

**Cree Dockerfile de aplicación**  
Cree un Dockerfile para su aplicación cliente.

1. 

**Cree el archivo Docker Compose**  
Cree un archivo Docker Compose para ejecutar ambos contenedores con una interfaz de red compartida:
**importante**  
Debe cargar AWS las credenciales y el token SSRF para que la aplicación pueda utilizar el proveedor de credenciales de carga de AWS trabajo. Para Amazon EKS y Amazon ECS, consulte lo siguiente:  
[Administrar el acceso](https://docs.aws.amazon.com/eks/latest/userguide/cluster-auth.html) en la *Guía del usuario de Amazon EKS*
[Rol de IAM en las tareas de Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) en la *Guía para desarrolladores de 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. 

**Copie el binario del proveedor**  
Copie el binario `aws-workload-credentials-provider` en el mismo directorio que contiene sus archivos Dockerfiles y Docker Compose.

1. 

**Compile y ejecute contenedores**  
Compile y ejecute los contenedores mediante Docker Compose:

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

1. 

**Siguientes pasos**  
Ahora puede usar el proveedor de credenciales AWS de carga de trabajo para recuperar los secretos del contenedor de su cliente. Para obtener más información, consulte [Recupera los secretos con AWS Proveedor de credenciales de carga de trabajo](#workload-credentials-provider-call).

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

Puede [empaquetar el proveedor de credenciales AWS de carga de trabajo como una extensión de Lambda](https://docs.aws.amazon.com/lambda/latest/dg/packaging-layers.html). A continuación, puede [añadirla a la función Lambda como una capa](https://docs.aws.amazon.com/lambda/latest/dg/adding-layers.html) y llamar al proveedor de credenciales de AWS carga de trabajo desde la función Lambda para obtener los secretos.

Las siguientes instrucciones muestran cómo obtener un nombre secreto *MyTest*mediante el script `secrets-manager-provider-extension.sh` de ejemplo del GitHub repositorio [aws-workload-credentials-provider para instalar el proveedor](https://github.com/aws/aws-workload-credentials-provider) de credenciales de carga de trabajo AWS como una extensión de Lambda.

**Para crear una extensión Lambda para el AWS Proveedor de credenciales de carga de trabajo**

1. 

**Package la capa proveedora**  
Desde la raíz del paquete de códigos del proveedor de credenciales de AWS carga de trabajo, ejecute los siguientes comandos:

   ```
   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. 

**Configure el token SSRF**  
La configuración predeterminada del proveedor establecerá automáticamente el token SSRF en el valor establecido en las variables preestablecidas `AWS_SESSION_TOKEN` o de `AWS_CONTAINER_AUTHORIZATION_TOKEN` entorno (esta última variable para las funciones de Lambda si está habilitada). SnapStart Como alternativa, puede definir la variable de entorno `AWS_TOKEN` con un valor arbitrario para la función de Lambda, ya que esta variable tiene prioridad sobre las otras dos. Si decide utilizar la variable de entorno `AWS_TOKEN`, debe establecer esa variable de entorno con una llamada `lambda:UpdateFunctionConfiguration`.

1. 

**Adjunte la capa a la función.**  
Adjunte la versión de la capa a la función de Lambda:

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

1. 

**Actualizar el código de la función**  
Actualice la función de Lambda para realizar consultas a `http://localhost:2773/secretsmanager/get?secretId=MyTest` con el valor del encabezado `X-Aws-codes-Secrets-Token` establecido en el valor del token SSRF procedente de una de las variables de entorno mencionadas anteriormente para recuperar el secreto. Asegúrese de implementar la lógica de reintento en el código de la aplicación para adaptarse a los retrasos en la inicialización y el registro de la extensión de Lambda.

1. 

**Prueba de la función**  
Invoque la función de Lambda para comprobar que el secreto se está recuperando correctamente.

------

## Recupera los secretos con AWS Proveedor de credenciales de carga de trabajo
<a name="workload-credentials-provider-call"></a>

Para recuperar un secreto, llame al punto final local del proveedor de credenciales de AWS carga de trabajo con el nombre del secreto o el ARN como parámetro de consulta. De forma predeterminada, el proveedor AWS de credenciales de carga de trabajo recupera la `AWSCURRENT` versión del secreto. Para recuperar una versión diferente, utilice el parámetro versionStage o versionId.

**importante**  
Para ayudar a proteger al proveedor de credenciales de AWS carga de trabajo, debe incluir un encabezado de token SSRF como parte de cada solicitud:. `X-Aws-Parameters-Secrets-Token` El proveedor AWS de credenciales de carga de trabajo rechaza las solicitudes que no tienen este encabezado o que tienen un token SSRF no válido. Puede personalizar el nombre del encabezado de SSRF en [Configure el AWS Proveedor de credenciales de carga de trabajo](#workload-credentials-provider-config).

### Permisos necesarios
<a name="provider-call-permissions"></a>

El proveedor AWS de credenciales de carga de trabajo usa el AWS SDK para Rust, que usa la cadena de [proveedores de AWS credenciales](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html). La identidad de estas credenciales de IAM determina los permisos que tiene el proveedor de credenciales AWS de carga de trabajo para recuperar los secretos.
+ `secretsmanager:DescribeSecret`
+ `secretsmanager:GetSecretValue`

Para obtener más información sobre los permisos, consulte [Referencia de permisos para AWS Secrets Manager](auth-and-access.md#reference_iam-permissions).

**importante**  
Una vez introducido el valor secreto en el proveedor de credenciales de AWS carga de trabajo, cualquier usuario con acceso al entorno informático y al token SSRF podrá acceder al secreto desde la memoria caché del proveedor de credenciales de AWS carga de trabajo. Para obtener más información, consulte [Consideraciones de seguridad](#workload-credentials-provider-security).

### Solicitudes de ejemplo
<a name="provider-call-examples"></a>

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

**Example Ejemplo: obtener un secreto con curl**  
En el siguiente ejemplo de curl, se muestra cómo obtener un secreto del proveedor de credenciales de AWS carga de trabajo. El ejemplo se basa en la presencia de la SSRF en un archivo, que es donde se almacena mediante el script de instalación.  

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

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

**Example Ejemplo: obtener un secreto con Python**  
El siguiente ejemplo de Python muestra cómo obtener un secreto del proveedor de credenciales de AWS carga de trabajo. El ejemplo se basa en la presencia de la SSRF en un archivo, que es donde se almacena mediante el script de instalación.  

```
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}")
```

------

## Descripción del parámetro `RefreshNow`
<a name="workload-credentials-provider-refresh"></a>

El proveedor AWS de credenciales de carga de trabajo utiliza una caché en memoria para almacenar valores secretos, que actualiza periódicamente. Por defecto, esta actualización se produce cuando se solicita un secreto una vez transcurrido el tiempo de vida (TTL), normalmente cada 300 segundos. Sin embargo, este enfoque a veces puede dar como resultado valores de secretos obsoletos, especialmente si un secreto rota antes de que caduque la entrada del caché.

Para solucionar esta limitación, el proveedor de credenciales AWS de carga de trabajo admite un parámetro llamado `refreshNow` en la URL. Puede utilizar este parámetro para forzar una actualización inmediata del valor de un secreto, al omitir el caché y asegurándose de disponer de la información más actualizada.

**Comportamiento predeterminado (sin `refreshNow`)**  
+ Utiliza valores en caché hasta que caduque el TTL
+ Actualiza los secretos solo después del TTL (por defecto, 300 segundos)
+ Puede devolver valores obsoletos si los secretos rotan antes de que caduque la caché

**Comportamientos de `refreshNow=true`**  
+ Omite la memoria caché por completo
+ Recupera el último valor secreto directamente de Secrets Manager
+ Actualiza la caché con el valor nuevo y restablece el TTL
+ Garantiza que siempre se obtendrá el valor secreto más actualizado

### Force-refresh un valor secreto
<a name="refreshnow-examples"></a>

**importante**  
El valor predeterminado de `refreshNow` es `false`. Cuando se establece en`true`, anula el TTL especificado en el archivo de configuración del proveedor de credenciales de AWS carga de trabajo y realiza una llamada de API a Secrets Manager.

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

**Example Ejemplo: Force-refresh un secreto que usa curl**  
El siguiente ejemplo de curl muestra cómo forzar al proveedor de credenciales de AWS carga de trabajo a actualizar el secreto. El ejemplo se basa en la presencia de la SSRF en un archivo, que es donde se almacena mediante el script de instalación.  

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

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

**Example Ejemplo: Force-refresh un secreto usando Python**  
El siguiente ejemplo de Python muestra cómo obtener un secreto del proveedor de credenciales de AWS carga de trabajo. El ejemplo se basa en la presencia de la SSRF en un archivo, que es donde se almacena mediante el script de instalación.  

```
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}")
```

------

## Recupera los secretos de las cuentas mediante el encadenamiento de roles
<a name="workload-credentials-provider-role-chaining"></a>

El encadenamiento de roles permite al proveedor de credenciales AWS de carga de trabajo recuperar datos secretos de otras AWS cuentas asumiendo que los roles de IAM los utilizan.AWS STS`AssumeRole` El proveedor AWS de credenciales de carga de trabajo crea y almacena en caché un cliente de almacenamiento en caché independiente para cada ARN de rol único. Cada cliente de rol mantiene su propia caché independiente, por lo que el mismo secreto obtenido con diferentes roles tiene entradas de caché independientes.

### Permisos necesarios
<a name="provider-role-chaining-permissions"></a>

Para utilizar el encadenamiento de roles, necesita lo siguiente:
+ Las credenciales AWS de entorno del proveedor de credenciales de carga de trabajo deben tener `sts:AssumeRole` permiso en el ARN del rol de destino.
+ El rol de destino debe tener los secretos a los que desea acceder `secretsmanager:GetSecretValue` y los `secretsmanager:DescribeSecret` permisos correspondientes.
+ La política de confianza del rol de destino debe permitir que la identidad del proveedor de credenciales de AWS carga de trabajo la asuma.

### Recupera los secretos de varias cuentas
<a name="provider-role-chaining-usage"></a>

Incluya el parámetro de `roleArn` consulta en su solicitud al proveedor de credenciales de AWS carga de trabajo para especificar qué función debe asumir para la recuperación del secreto.

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

**Example Ejemplo: Cross-account secreto mediante 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 Ejemplo: Cross-account secreto usando 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}")
```

------

### Configuración y límites del encadenamiento de roles
<a name="provider-role-chaining-config"></a>

Configure el encadenamiento de roles con la `max_roles` opción del archivo de configuración de TOML. Esto establece el número máximo de roles asumidos simultáneamente, en el rango de 1 a 20. El valor predeterminado es 20.

**importante**  
Los roles asumidos no se eliminan de la caché de roles del proveedor de credenciales de AWS carga de trabajo. Una vez alcanzado el número máximo de funciones, las solicitudes con nuevos ARN de función se rechazan con un `400` error hasta que se reinicia el proveedor de credenciales de AWS carga de trabajo.Respuestas de error relacionadas con el encadenamiento de roles

**`400`**  
El `roleArn` formato no es válido o se ha alcanzado el número máximo de roles asumidos.

**`403`**  
La llamada a AWS STS`AssumeRole` no se realizó correctamente. Compruebe que la política de confianza del rol de destino permita que la identidad del proveedor de credenciales de AWS carga de trabajo lo asuma.

## Pre-fetch secretos al inicio
<a name="workload-credentials-provider-prefetch"></a>

De forma predeterminada, el proveedor AWS de credenciales de carga de trabajo obtiene los secretos a pedido cuando la aplicación los solicita. Con la recuperación previa, el proveedor de credenciales de AWS carga de trabajo carga los secretos específicos en la memoria caché cuando se inicia, de modo que la aplicación pueda acceder a ellos inmediatamente sin tener que esperar a la primera llamada a la API. Pre-fetching se ejecuta como una tarea en segundo plano: el proveedor de credenciales AWS de carga de trabajo comienza a aceptar solicitudes de forma inmediata y no las bloquea una vez finalizada la recuperación previa.

Puede especificar los secretos que desea recuperar previamente de dos maneras:
+ **Secretos explícitos**: enumere los ARN o ID secretos específicos.
+ **Tag-based descubrimiento**: descubra los secretos mediante una clave de etiqueta. El proveedor AWS de credenciales de carga de trabajo busca todos los secretos que tienen la etiqueta especificada.

### Permisos necesarios
<a name="provider-prefetch-permissions"></a>

Además de los permisos estándar para recuperar datos secretos, la recuperación previa requiere lo siguiente:
+ `secretsmanager:BatchGetSecretValue`— Necesario para todas las operaciones de captura previa.
+ `secretsmanager:ListSecrets`— Necesario solo cuando se utiliza la detección basada en etiquetas.

### Configurar la captura previa
<a name="provider-prefetch-config"></a>

Añada una `[capabilities.secrets_manager.prefetch]` sección al archivo de configuración de TOML. Están disponibles las siguientes opciones:

**`cache_buffer_ratio`**  
La fracción máxima de la memoria caché que se debe llenar por cliente durante la captura previa, en el rango de 0,1 a 1,0. El valor predeterminado es 0.8. Cuando se alcanza el límite de búfer, el proveedor de credenciales de AWS carga de trabajo deja de recuperar previamente los secretos restantes; no desaloja las entradas de caché existentes. Los secretos que no se cargaron durante la captura previa siguen estando disponibles bajo demanda.

**`max_jitter_seconds`**  
Un retraso aleatorio de segundos antes de que comience la captura previa, en el rango de 0 a 10. El valor predeterminado es 0. Úselo para evitar que se sincronicen las llamadas a la API de toda la flota cuando se inician varios proveedores al mismo tiempo.

**Example Pre-fetch configuración con secretos explícitos**  

```
[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 configuración con detección basada en etiquetas**  

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

También puede combinar secretos explícitos y detección basada en etiquetas en la misma configuración. Para la búsqueda previa entre cuentas, añada el campo. `role_arn` Para obtener más información, consulte [Recupera los secretos de las cuentas mediante el encadenamiento de roles](#workload-credentials-provider-role-chaining).

**Example Pre-fetch configuración con acceso multicuenta**  

```
[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" },
]
```

## Configure el AWS Proveedor de credenciales de carga de trabajo
<a name="workload-credentials-provider-config"></a>

Para cambiar la configuración del proveedor de credenciales de AWS carga de trabajo, cree un archivo de configuración [TOML](https://toml.io/en/) y, a continuación, llame`./aws-workload-credentials-provider sm start --config config.toml`.

El archivo de configuración admite un formato anidado. Las opciones de Secrets Manager se encuentran debajo`[capabilities.secrets_manager]`, con subsecciones para la configuración de caché y seguridad. Las opciones de registro se encuentran debajo`[logging]`.

**Example Ejemplo de archivo de configuración anidado**  

```
[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"]
```

**nota**  
Las teclas planas en el nivel raíz (por ejemplo`http_port = 2773`) siguen siendo compatibles con versiones anteriores de los archivos de configuración existentes.Opciones de configuración de Secrets Manager

**`enabled`**  
Si la función Secrets Manager está activa: `true` o`false`. El valor predeterminado es `true`.

**`http_port`**  
El puerto del servidor HTTP local, en el rango de 1024 a 65 535. El valor predeterminado es 2773.

**`region`**  
La AWS región que se utilizará para las solicitudes. Si no se especifica ninguna región, el proveedor de credenciales de AWS carga de trabajo determina la región a partir del SDK. Para obtener más información, consulte [Especifique las credenciales y regiones predeterminadas](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html) en la *Guía para desarrolladores del SDK de AWS para Rust*.

**`path_prefix`**  
El prefijo URI que se utiliza para determinar si la solicitud es una solicitud basada en una ruta. El valor predeterminado es “/v1/”.

**`max_conn`**  
El número máximo de conexiones desde clientes HTTP que permite el proveedor de credenciales de AWS carga de trabajo, entre 1 y 1000. El valor predeterminado es 800.

**`max_roles`**  
El número máximo de funciones de IAM simultáneas para el acceso entre cuentas, en el intervalo de 1 a 20. El valor predeterminado es 20. Para obtener más información, consulte [Recupera los secretos de las cuentas mediante el encadenamiento de roles](#workload-credentials-provider-role-chaining).Opciones de caché (`[capabilities.secrets_manager.cache]`)

**`ttl_seconds`**  
El TTL en segundos de los elementos almacenados en caché, en el rango de 0 a 3600. El valor predeterminado es 300, donde 0 indica que no hay almacenamiento en caché.

**`cache_size`**  
El número máximo de secretos que se pueden almacenar en caché está en el rango de 1 a 1000. El valor predeterminado es 1000.Opciones de seguridad (`[capabilities.secrets_manager.security])`

**`ssrf_headers`**  
Una lista de nombres de encabezados que el proveedor de credenciales de carga de trabajo comprueba para el token de la SSRF AWS. El valor predeterminado es "X-Aws-Parameters-Secrets-Token, X-Vault-Token».

**`ssrf_env_variables`**  
Una lista de nombres de variables de entorno que el proveedor AWS de credenciales de carga de trabajo comprueba en orden secuencial para encontrar el token SSRF. La variable de entorno puede contener el token o una referencia al archivo del token, como en: `AWS_TOKEN=file:///var/run/awssmatoken`. El valor predeterminado es "AWS\_TOKEN, AWS\_SESSION\_TOKEN, AWS\_CONTAINER\_AUTHORIZATION\_TOKEN».Opciones de registro (`[registro]`)

**`log_level`**  
El nivel de detalle indicado en los registros del proveedor de credenciales de AWS carga de trabajo: DEBUG, INFO, WARN, ERROR o NONE. El valor predeterminado es INFO.

**`log_to_file`**  
Si desea iniciar sesión en un archivo o stdout/stderr: `true` o`false`. El valor predeterminado es `true`.

## Características opcionales
<a name="workload-credentials-provider-features"></a>

El proveedor AWS de credenciales de carga de trabajo se puede crear con funciones opcionales pasando la `--features` bandera a`cargo build`. Las características disponibles son las siguientes:Características de compilación

**`prefer-post-quantum`**  
Crea `X25519MLKEM768` como el algoritmo de intercambio de claves de mayor prioridad. De lo contrario, está disponible, pero no es de máxima prioridad. `X25519MLKEM768` es un algoritmo híbrido de intercambio de claves con seguridad poscuántica.

**`fips`**  
Limita los conjuntos de cifrado utilizados por el proveedor únicamente FIPS-approved a cifrados.

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

**Registro local**  
El proveedor AWS de credenciales de carga de trabajo registra los errores de forma local en el archivo `logs/secrets_manager_provider.log` o en stdout/stderr función de la variable de `log_to_file` configuración. Cuando la aplicación llama al proveedor de credenciales de AWS carga de trabajo para obtener un secreto, esas llamadas aparecen en el registro local. No aparecen en los CloudTrail registros.

**Rotación de registros**  
El proveedor de credenciales de AWS carga de trabajo crea un nuevo archivo de registro cuando el archivo alcanza los 10 MB y almacena hasta cinco archivos de registro en total.

**AWS registro de servicios**  
El registro no va a Secrets Manager, CloudTrail, o CloudWatch. Las solicitudes para obtener datos secretos del proveedor de credenciales de AWS carga de trabajo no aparecen en esos registros. Cuando el proveedor de credenciales de AWS carga de trabajo llama a Secrets Manager para obtener un secreto, esa llamada se graba CloudTrail con una cadena de agente de usuario que contiene`aws-workload-credentials-provider`.

Puede configurar las opciones del registro en [Configure el AWS Proveedor de credenciales de carga de trabajo](#workload-credentials-provider-config).

## Consideraciones de seguridad
<a name="workload-credentials-provider-security"></a>

**Dominio de confianza**  
En el caso de una arquitectura de proveedor local, el dominio de confianza es el lugar donde se puede acceder al punto final del proveedor y al token SSRF, que suele ser todo el host. El dominio de confianza del proveedor de credenciales de AWS carga de trabajo debe coincidir con el dominio en el que están disponibles las credenciales de Secrets Manager para mantener la misma postura de seguridad. Por ejemplo, en Amazon EC2, el dominio de confianza del proveedor de credenciales de AWS carga de trabajo sería el mismo que el dominio de las credenciales cuando se utilizan funciones para Amazon EC2.

**importante**  
Las aplicaciones preocupadas por la seguridad que aún no utilizan una solución basada en un proveedor con las credenciales de Secrets Manager bloqueadas en la aplicación deberían considerar la posibilidad de utilizar los AWS SDK o las soluciones de almacenamiento en caché específicos del idioma. Para obtener más información, consulte [Obtener secretos](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html).