As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Usar o AWS Provedor de credenciais de carga de trabalho
<a name="workload-credentials-provider"></a>

## Como o AWS O Workload Credentials Provider funciona
<a name="provider-overview"></a>

O AWS Workload Credentials Provider (antigo AWS Secrets Manager Agent) fornece um serviço HTTP do lado do cliente que ajuda a padronizar a forma como você consome segredos do Secrets Manager em seus ambientes computacionais. É possível usá-lo com serviços a seguir:
+ AWS Lambda
+ Amazon Elastic Container Service
+ Amazon Elastic Kubernetes Service
+ Amazon Elastic Compute Cloud

O AWS Workload Credentials Provider recupera e armazena segredos na memória, permitindo que seus aplicativos obtenham segredos do localhost em vez de fazer chamadas diretas para o Secrets Manager. O provedor de credenciais de AWS carga de trabalho só pode ler segredos, não pode modificá-los.

O AWS Workload Credentials Provider é de código aberto. O código-fonte, as instruções de instalação e as informações da versão mais recente estão disponíveis em [GitHub](https://github.com/aws/aws-workload-credentials-provider).

**Importante**  
O AWS Workload Credentials Provider usa as AWS credenciais do seu ambiente para chamar o Secrets Manager. Isso inclui proteção contra falsificação de solicitações do lado do servidor (SSRF) para ajudar a melhorar a segurança dos segredos. O AWS Workload Credentials Provider usa a troca de ML-KEM chaves pós-quântica como a troca de chaves de maior prioridade por padrão.

## Noções básicas AWS Cache do provedor de credenciais de carga de trabalho
<a name="provider-caching"></a>

O AWS Workload Credentials Provider usa um cache na memória que é redefinido quando o AWS Workload Credentials Provider é reiniciado. Ele atualiza periodicamente os valores de segredos em cache com base no seguinte:
+ A frequência de atualização padrão (TTL) é de 300 segundos
+ É possível modificar o TTL usando um arquivo de configuração
+ A atualização ocorre quando você solicita um segredo após a expiração do TTL

**nota**  
O provedor de credenciais AWS de carga de trabalho não inclui a invalidação do cache. Se um segredo girar antes que a entrada do cache expire, o AWS Workload Credentials Provider poderá retornar um valor secreto obsoleto.

O AWS Workload Credentials Provider retorna valores secretos no mesmo formato da resposta de. `GetSecretValue` Os valores de segredos não são criptografados no cache.

**Topics**
+ [Como o AWS O Workload Credentials Provider funciona](#provider-overview)
+ [Noções básicas AWS Cache do provedor de credenciais de carga de trabalho](#provider-caching)
+ [Construa o AWS Provedor de credenciais de carga de trabalho](#workload-credentials-provider-build)
+ [Instale o  AWS Provedor de credenciais de carga de trabalho](#workload-credentials-provider-install)
+ [Recupere segredos com o AWS Provedor de credenciais de carga de trabalho](#workload-credentials-provider-call)
+ [Entendendo o parâmetro `RefreshNow`](#workload-credentials-provider-refresh)
+ [Recupere segredos em todas as contas com o encadeamento de funções](#workload-credentials-provider-role-chaining)
+ [Pre-fetch segredos na startup](#workload-credentials-provider-prefetch)
+ [Configurar o AWS Provedor de credenciais de carga de trabalho](#workload-credentials-provider-config)
+ [Recursos opcionais](#workload-credentials-provider-features)
+ [Registro em log](#workload-credentials-provider-log)
+ [Considerações sobre segurança](#workload-credentials-provider-security)

## Construa o AWS Provedor de credenciais de carga de trabalho
<a name="workload-credentials-provider-build"></a>

Antes de começar, verifique se você tem as ferramentas de desenvolvimento padrão e as ferramentas do Rust instaladas em sua plataforma.

**nota**  
Atualmente, criar o provedor com o `fips` recurso ativado no macOS requer a seguinte solução alternativa:  
Crie uma variável de ambiente chamada `SDKROOT` que é definida como o resultado da execução de `xcrun --show-sdk-path`

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

**Para desenvolver RPM-based sistemas**

1. Use o script `install` fornecido no repositório. 

   O script gera um token SSRF aleatório no startup e o armazena no arquivo `/var/run/awssmatoken`. O token pode ser lido pelo grupo `aws-wcp-token` criado pelo script de instalação. 

1. Para permitir que sua aplicação leia o arquivo de token, você precisa adicionar ao grupo `aws-wcp-token` a conta de usuário na qual sua aplicação é executada. Por exemplo, você pode conceder permissões para que seu aplicativo leia o arquivo de token com o seguinte comando usermod, onde {{<APP\_USER>}} está o ID do usuário sob o qual seu aplicativo é executado.

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

**Instalação das ferramentas de desenvolvimento**  
Em RPM-based sistemas como o AL2023, instale o grupo Ferramentas de Desenvolvimento:

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

1. 

**Instalação do Rust**  
Siga as instruções em [Instalação do Rust](https://www.rust-lang.org/tools/install) na *documentação do Rust*.

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

1. 

**Crie o provedor**  
Crie o provedor de credenciais de AWS carga de trabalho usando o comando cargo build:

   ```
   cargo build --release
   ```

   Você encontrará o executável em `target/release/aws-workload-credentials-provider`.

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

**Para desenvolver Debian-based sistemas**

1. 

**Instalação das ferramentas de desenvolvimento**  
Em Debian-based sistemas como o Ubuntu, instale o pacote build-essential:

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

1. 

**Instalação do Rust**  
Siga as instruções em [Instalação do Rust](https://www.rust-lang.org/tools/install) na *documentação do Rust*.

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

1. 

**Crie o provedor**  
Crie o provedor de credenciais de AWS carga de trabalho usando o comando cargo build:

   ```
   cargo build --release
   ```

   Você encontrará o executável em `target/release/aws-workload-credentials-provider`.

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

**Para criar no Windows**

1. 

**Configuração do ambiente de desenvolvimento**  
Siga as instruções em [Configuração do seu ambiente de desenvolvimento no Windows para Rust](https://learn.microsoft.com/en-us/windows/dev-environment/rust/setup) na *documentação do Microsoft Windows*.

1. 

**Crie o provedor**  
Crie o provedor de credenciais de AWS carga de trabalho usando o comando cargo build:

   ```
   cargo build --release
   ```

   Você encontrará o executável em `target/release/aws-workload-credentials-provider.exe`.

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

**Para compilar de forma cruzada**

1. 

**Instalação das ferramentas de compilação cruzada**  
Instale o `cargo-xwin`:

   ```
   cargo install cargo-xwin
   ```

1. 

**Adição de destinos de criação do Rust**  
Instale o destino de compilação do Windows MSVC:

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

1. 

**Criação no Windows**  
Cross-compile o provedor para Windows:

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

   Você encontrará o executável em `target/x86_64-pc-windows-msvc/release/aws-workload-credentials-provider.exe`.

------

## Instale o  AWS Provedor de credenciais de carga de trabalho
<a name="workload-credentials-provider-install"></a>

Escolha seu ambiente de computação entre as opções de instalação a seguir.

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

**Para instalar o  AWS Provedor de credenciais de carga de trabalho no Amazon EC2**

1. 

**Navegação até o diretório de configurações**  
Mude para o diretório de configurações:

   ```
   cd aws_workload_credentials_provider_common/configuration
   ```

1. 

**Execução do script de instalação**  
Execute o script `install` fornecido no repositório.

   O script gera um token SSRF aleatório no startup e o armazena no arquivo `/var/run/awssmatoken`. O token pode ser lido pelo grupo `aws-wcp-token` criado pelo script de instalação.

1. 

**Configuração de permissões de aplicações**  
Adicione a conta de usuário na qual sua aplicação é executada ao grupo `aws-wcp-token`:

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

   Substitua pelo ID de usuário {{APP\_USER}} com o qual seu aplicativo é executado.

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

Você pode executar o AWS Workload Credentials Provider como um contêiner auxiliar junto com seu aplicativo usando o Docker. Então, seu aplicativo pode recuperar segredos do servidor HTTP local fornecido pelo AWS Workload Credentials Provider. Para obter informações sobre o Docker, consulte a [documentação do Docker](https://docs.docker.com).

**Para criar um contêiner auxiliar para o AWS Provedor de credenciais de carga de trabalho**

1. 

**Criar provedor Dockerfile**  
Crie um Dockerfile para o contêiner auxiliar do AWS Workload Credentials Provider:

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

**Criação do Dockerfile da aplicação**  
Crie um Dockerfile para sua aplicação cliente.

1. 

**Criação do arquivo Docker Compose**  
Crie um arquivo Docker Compose para executar ambos os contêineres com uma interface de rede compartilhada:
**Importante**  
Você deve carregar AWS as credenciais e o token SSRF para que o aplicativo possa usar o AWS Workload Credentials Provider. Para o Amazon EKS e o Amazon ECS, consulte:  
[Gerenciamento de acesso](https://docs.aws.amazon.com/eks/latest/userguide/cluster-auth.html) no *Guia do usuário do Amazon EKS*
[Perfil do IAM da tarefa do Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) no *Guia do desenvolvedor do 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. 

**Binário do provedor de cópia**  
Copie o binário do `aws-workload-credentials-provider` para o mesmo diretório que contém seus arquivos Dockerfile e Docker Compose.

1. 

**Criação e execução dos contêineres**  
Crie e execute os contêineres usando o Docker Compose:

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

1. 

**Próximas etapas**  
Agora você pode usar o AWS Workload Credentials Provider para recuperar segredos do contêiner do seu cliente. Para obter mais informações, consulte [Recupere segredos com o AWS Provedor de credenciais de carga de trabalho](#workload-credentials-provider-call).

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

Você pode [empacotar o AWS Workload Credentials Provider como uma extensão Lambda](https://docs.aws.amazon.com/lambda/latest/dg/packaging-layers.html). Em seguida, você pode [adicioná-la à sua função Lambda como uma camada](https://docs.aws.amazon.com/lambda/latest/dg/adding-layers.html) e chamar o AWS Workload Credentials Provider a partir da sua função Lambda para obter segredos.

As instruções a seguir mostram como obter um nome secreto *MyTest*usando o script de exemplo `secrets-manager-provider-extension.sh` no GitHub repositório [aws-workload-credentials-provider para instalar o Workload](https://github.com/aws/aws-workload-credentials-provider) Credentials Provider como uma extensão Lambda.AWS

**Para criar uma extensão Lambda para o AWS Provedor de credenciais de carga de trabalho**

1. 

**Package a camada do provedor**  
Na raiz do pacote de códigos do AWS Workload Credentials Provider, execute os seguintes 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. 

**Configurar o token de SSRF**  
A configuração padrão do provedor definirá automaticamente o token SSRF com o valor definido nas variáveis predefinidas `AWS_SESSION_TOKEN` ou de `AWS_CONTAINER_AUTHORIZATION_TOKEN` ambiente (a última variável para funções Lambda com habilitada). SnapStart Como alternativa, é possível definir a variável de ambiente `AWS_TOKEN` com um valor arbitrário para sua função do Lambda, pois essa variável tem precedência sobre as outras duas. Se você optar por usar a variável de ambiente `AWS_TOKEN`, deverá definir essa variável de ambiente com uma chamada a `lambda:UpdateFunctionConfiguration`.

1. 

**Vinculação da camada à função**  
Vincule a versão da camada à sua função do Lambda.

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

1. 

**Atualizar um código de função**  
Atualize sua função do Lambda para fazer uma consulta a `http://localhost:2773/secretsmanager/get?secretId=MyTest` com o valor de cabeçalho `X-Aws-codes-Secrets-Token` definido como o valor do token de SSRF proveniente de uma das variáveis de ambiente mencionadas acima para recuperar o segredo. Certifique-se de implementar a lógica de repetição no código da aplicação para acomodar atrasos na inicialização e no registro da extensão do Lambda.

1. 

**Testar a função**  
Invoque a função do Lambda para verificar se o segredo está sendo buscado corretamente.

------

## Recupere segredos com o AWS Provedor de credenciais de carga de trabalho
<a name="workload-credentials-provider-call"></a>

Para recuperar um segredo, chame o endpoint local do AWS Workload Credentials Provider com o nome secreto ou ARN como parâmetro de consulta. Por padrão, o AWS Workload Credentials Provider recupera a `AWSCURRENT` versão do segredo. Para recuperar uma versão diferente, use o parâmetro versionStage ou versionId.

**Importante**  
Para ajudar a proteger o provedor de credenciais de AWS carga de trabalho, você deve incluir um cabeçalho de token SSRF como parte de cada solicitação:. `X-Aws-Parameters-Secrets-Token` O AWS Workload Credentials Provider nega solicitações que não tenham esse cabeçalho ou que tenham um token SSRF inválido. É possível personalizar o nome do cabeçalho SSRF em [Configurar o AWS Provedor de credenciais de carga de trabalho](#workload-credentials-provider-config).

### Permissões obrigatórias
<a name="provider-call-permissions"></a>

[O AWS Workload Credentials Provider usa o AWS SDK for Rust, que usa a cadeia de fornecedores de credenciais.AWS](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html) A identidade dessas credenciais do IAM determina as permissões que o provedor de credenciais AWS de carga de trabalho tem para recuperar segredos.
+ `secretsmanager:DescribeSecret`
+ `secretsmanager:GetSecretValue`

Para obter mais informações sobre permissões, consulte [Referência de permissões para AWS Secrets Manager](auth-and-access.md#reference_iam-permissions).

**Importante**  
Depois que o valor secreto é inserido no AWS Workload Credentials Provider, qualquer usuário com acesso ao ambiente computacional e ao token SSRF pode acessar o segredo do cache do Workload Credentials Provider.AWS Para obter mais informações, consulte [Considerações sobre segurança](#workload-credentials-provider-security).

### Exemplo de solicitações
<a name="provider-call-examples"></a>

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

**Example Exemplo: obtenção de um segredo usando curl**  
O exemplo de curl a seguir mostra como obter um segredo do AWS Workload Credentials Provider. O exemplo depende da presença do SSRF em um arquivo, que é onde ele é armazenado pelo script de instalação.  

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

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

**Example Exemplo: obtenção de um segredo usando Python**  
O exemplo de Python a seguir mostra como obter um segredo do AWS Workload Credentials Provider. O exemplo depende da presença do SSRF em um arquivo, que é onde ele é armazenado pelo script de instalação.  

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

------

## Entendendo o parâmetro `RefreshNow`
<a name="workload-credentials-provider-refresh"></a>

O AWS Workload Credentials Provider usa um cache na memória para armazenar valores secretos, que são atualizados periodicamente. Por padrão, essa atualização ocorre quando você solicita um segredo após a expiração da vida útil (TTL), normalmente a cada 300 segundos. No entanto, essa abordagem às vezes pode resultar em valores de segredo obsoletos, especialmente se um segredo for alternado antes que a entrada do cache expire.

Para resolver essa limitação, o AWS Workload Credentials Provider oferece suporte a um parâmetro chamado `refreshNow` na URL. É possível usar esse parâmetro para forçar uma atualização imediata do valor de um segredo, ignorando o cache e garantindo que você tenha as informações mais atualizadas.

**Comportamento padrão (sem `refreshNow`)**  
+ Usa valores em cache até que o TTL expire
+ Atualiza segredos somente após o TTL (padrão de 300 segundos)
+ Pode retornar valores obsoletos se os segredos forem alternados antes que o cache expire

**Comportamento com `refreshNow=true`**  
+ Ignora completamente o cache
+ Recupera o valor do segredo mais recente diretamente do Secrets Manager
+ Atualiza o cache com o novo valor e redefine o TTL
+ Garante que você sempre obtenha o valor secreto mais atual

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

**Importante**  
O valor padrão de `refreshNow` é `false`. Quando definido como`true`, ele substitui o TTL especificado no arquivo de configuração do AWS Workload Credentials Provider e faz uma chamada de API para o Secrets Manager.

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

**Example Exemplo — Force-refresh um segredo usando curl**  
O exemplo de curl a seguir mostra como forçar o provedor de credenciais AWS de carga de trabalho a atualizar o segredo. O exemplo depende da presença do SSRF em um arquivo, que é onde ele é armazenado pelo script de instalação.  

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

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

**Example Exemplo — Force-refresh um segredo usando Python**  
O exemplo de Python a seguir mostra como obter um segredo do AWS Workload Credentials Provider. O exemplo depende da presença do SSRF em um arquivo, que é onde ele é armazenado pelo script de instalação.  

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

------

## Recupere segredos em todas as contas com o encadeamento de funções
<a name="workload-credentials-provider-role-chaining"></a>

O encadeamento de funções permite que o provedor de credenciais de AWS carga de trabalho recupere segredos de outras AWS contas assumindo funções do IAM usando.AWS STS`AssumeRole` O AWS Workload Credentials Provider cria e armazena em cache um cliente de cache separado para cada ARN de função exclusiva. Cada cliente de função mantém seu próprio cache independente, portanto, o mesmo segredo obtido com funções diferentes tem entradas de cache separadas.

### Permissões obrigatórias
<a name="provider-role-chaining-permissions"></a>

Para usar o encadeamento de funções, você precisa do seguinte:
+ As credenciais do ambiente do AWS Workload Credentials Provider devem ter `sts:AssumeRole` permissão no ARN da função de destino.
+ A função de destino deve ter `secretsmanager:DescribeSecret` permissões `secretsmanager:GetSecretValue` e permissões para os segredos que você deseja acessar.
+ A política de confiança da função de destino deve permitir que a identidade do provedor de credenciais de AWS carga de trabalho a assuma.

### Recupere segredos de várias contas
<a name="provider-role-chaining-usage"></a>

Inclua o parâmetro de `roleArn` consulta em sua solicitação ao AWS Workload Credentials Provider para especificar qual função assumir para a recuperação secreta.

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

**Example Exemplo — Cross-account segredo usando 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 Exemplo — Cross-account segredo 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}")
```

------

### Configuração e limites do encadeamento de funções
<a name="provider-role-chaining-config"></a>

Configure o encadeamento de funções com a `max_roles` opção em seu arquivo de configuração TOML. Isso define o número máximo de funções assumidas simultaneamente, no intervalo de 1 a 20. O padrão é 20.

**Importante**  
As funções assumidas não são removidas do cache de funções do provedor de credenciais AWS de carga de trabalho. Quando o número máximo de funções é atingido, as solicitações com novos ARNs de função são rejeitadas com um `400` erro até que o AWS Workload Credentials Provider seja reiniciado.Respostas de erro para encadeamento de funções

**`400`**  
O `roleArn` formato é inválido ou o número máximo de funções assumidas foi atingido.

**`403`**  
Falha na chamada AWS STS`AssumeRole`. Verifique se a política de confiança da função de destino permite que a identidade do provedor de credenciais de AWS carga de trabalho a assuma.

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

Por padrão, o AWS Workload Credentials Provider busca segredos sob demanda quando seu aplicativo os solicita. Com a pré-busca, o AWS Workload Credentials Provider carrega segredos específicos no cache quando ele é inicializado, para que seu aplicativo possa acessá-los imediatamente sem esperar pela primeira chamada de API. Pre-fetching é executado como uma tarefa em segundo plano — o AWS Workload Credentials Provider começa a aceitar solicitações imediatamente e não bloqueia a conclusão da pré-busca.

Você pode especificar segredos para pré-busca de duas maneiras:
+ **Segredos explícitos** — Liste IDs secretos ou ARNs específicos.
+ **Tag-based descoberta** — Descubra segredos por chave de tag. O AWS Workload Credentials Provider busca todos os segredos que têm a tag especificada.

### Permissões obrigatórias
<a name="provider-prefetch-permissions"></a>

Além das permissões padrão para recuperar segredos, a pré-busca exige o seguinte:
+ `secretsmanager:BatchGetSecretValue`— Obrigatório para todas as operações de pré-busca.
+ `secretsmanager:ListSecrets`— Exigido somente ao usar a descoberta baseada em tags.

### Configurar pré-busca
<a name="provider-prefetch-config"></a>

Adicione uma `[capabilities.secrets_manager.prefetch]` seção ao seu arquivo de configuração TOML. As seguintes opções estão disponíveis:

**`cache_buffer_ratio`**  
A fração máxima do cache a ser preenchida por cliente durante a pré-busca, na faixa de 0,1 a 1,0. O padrão é 0,8. Quando o limite do buffer é atingido, o AWS Workload Credentials Provider para de pré-buscar os segredos restantes — ele não despeja as entradas de cache existentes. Segredos não carregados durante a pré-busca ainda estão disponíveis sob demanda.

**`max_jitter_seconds`**  
Um atraso aleatório em segundos antes do início da pré-busca, no intervalo de 0 a 10. O padrão é 0. Use isso para evitar chamadas de API sincronizadas em toda a frota quando vários provedores iniciam ao mesmo tempo.

**Example Pre-fetch configuração com segredos 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 configuração com descoberta baseada em tags**  

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

Você também pode combinar segredos explícitos e descoberta baseada em tags na mesma configuração. Para pré-busca entre contas, adicione o campo. `role_arn` Para obter mais informações, consulte [Recupere segredos em todas as contas com o encadeamento de funções](#workload-credentials-provider-role-chaining).

**Example Pre-fetch configuração com acesso entre contas**  

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

## Configurar o AWS Provedor de credenciais de carga de trabalho
<a name="workload-credentials-provider-config"></a>

Para alterar a configuração do AWS Workload Credentials Provider, crie um arquivo de configuração [TOML](https://toml.io/en/) e, em seguida, chame. `./aws-workload-credentials-provider sm start --config config.toml`

O arquivo de configuração oferece suporte a um formato aninhado. As opções do Secrets Manager são colocadas abaixo`[capabilities.secrets_manager]`, com subseções para configurações de cache e segurança. As opções de registro são colocadas em`[logging]`.

**Example Exemplo de arquivo de configuração aninhado**  

```
[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**  
As teclas simples no nível raiz (por exemplo,`http_port = 2773`) ainda são suportadas para compatibilidade com versões anteriores dos arquivos de configuração existentes.Opções de configuração do Secrets Manager

**`enabled`**  
Se o recurso Secrets Manager está ativo: `true` ou`false`. O padrão é `true`.

**`http_port`**  
A porta do servidor de HTTP local, no intervalo de 1024 a 65535. O padrão é 2773.

**`region`**  
A AWS região a ser usada para solicitações. Se nenhuma região for especificada, o provedor de credenciais AWS de carga de trabalho determinará a região a partir do SDK. Para obter mais informações, consulte [Especificação das suas credenciais e região padrão](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html) no *Guia do desenvolvedor do SDK da AWS para Rust*.

**`path_prefix`**  
O prefixo do URI usado para determinar se a solicitação é baseada em caminho. O padrão é "/v1/".

**`max_conn`**  
O número máximo de conexões de clientes HTTP que o AWS Workload Credentials Provider permite, na faixa de 1 a 1000. O padrão é 800.

**`max_roles`**  
O número máximo de funções simultâneas do IAM para acesso entre contas, na faixa de 1 a 20. O padrão é 20. Para obter mais informações, consulte [Recupere segredos em todas as contas com o encadeamento de funções](#workload-credentials-provider-role-chaining).Opções de cache (`[capabilities.secrets_manager.cache`])

**`ttl_seconds`**  
O TTL, em segundos, para os itens em cache, no intervalo de 0 a 3600. O padrão é de 300. 0 indica que não há armazenamento em cache.

**`cache_size`**  
O número máximo de segredos que podem ser armazenados no cache, no intervalo de 1 a 1000. O padrão é 1000.Opções de segurança (`[capabilities.secrets_manager.security`])

**`ssrf_headers`**  
Uma lista de nomes de cabeçalhos que o AWS Workload Credentials Provider verifica o token SSRF. O padrão é "X-Aws-Parameters-Secrets-Token, X-Vault-Token”.

**`ssrf_env_variables`**  
Uma lista de nomes de variáveis de ambiente que o AWS Workload Credentials Provider verifica em ordem sequencial para o token SSRF. A variável de ambiente pode conter o token ou uma referência ao arquivo de token, como em: `AWS_TOKEN=file:///var/run/awssmatoken`. O padrão é "AWS\_TOKEN, AWS\_SESSION\_TOKEN, AWS\_CONTAINER\_AUTHORIZATION\_TOKEN”.Opções de registro (`[registro]`)

**`log_level`**  
O nível de detalhe relatado nos registros do AWS Workload Credentials Provider: DEBUG, INFO, WARN, ERROR ou NONE. O padrão é INFO.

**`log_to_file`**  
Se deve fazer login em um arquivo ou stdout/stderr: `true` ou`false`. O padrão é `true`.

## Recursos opcionais
<a name="workload-credentials-provider-features"></a>

O AWS Workload Credentials Provider pode ser criado com recursos opcionais passando a `--features` bandeira para. `cargo build` Os recursos disponíveis são:Recursos de compilação

**`prefer-post-quantum`**  
Torna `X25519MLKEM768` o algoritmo de troca de chaves de maior prioridade. Caso contrário, ele estará disponível, mas não será de maior prioridade. `X25519MLKEM768` é um algoritmo de troca de chaves híbrido e pós-quântico seguro.

**`fips`**  
Restringe os conjuntos de cifras usados pelo provedor somente a cifras. FIPS-approved

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

**Log local**  
O AWS Workload Credentials Provider registra os erros localmente no arquivo `logs/secrets_manager_provider.log` ou, stdout/stderr dependendo da variável de `log_to_file` configuração. Quando seu aplicativo chama o AWS Workload Credentials Provider para obter um segredo, essas chamadas aparecem no registro local. Eles não aparecem nos CloudTrail registros.

**Alternância de logs**  
O AWS Workload Credentials Provider cria um novo arquivo de log quando o arquivo atinge 10 MB e armazena até cinco arquivos de log no total.

**AWS registro de serviços**  
O registro não vai para o Secrets Manager, CloudTrail, ou CloudWatch. As solicitações para obter segredos do AWS Workload Credentials Provider não aparecem nesses registros. Quando o AWS Workload Credentials Provider faz uma chamada para o Secrets Manager para obter um segredo, essa chamada é gravada CloudTrail com uma string de agente de usuário contendo. `aws-workload-credentials-provider`

É possível configurar as opções de log em [Configurar o AWS Provedor de credenciais de carga de trabalho](#workload-credentials-provider-config).

## Considerações sobre segurança
<a name="workload-credentials-provider-security"></a>

**Domínio de confiança**  
Para uma arquitetura de provedor local, o domínio de confiança é onde o endpoint do provedor e o token SSRF estão acessíveis, o que geralmente é o host inteiro. O domínio de confiança do AWS Workload Credentials Provider deve corresponder ao domínio em que as credenciais do Secrets Manager estão disponíveis para manter a mesma postura de segurança. Por exemplo, no Amazon EC2, o domínio de confiança do AWS Workload Credentials Provider seria o mesmo que o domínio das credenciais ao usar funções para o Amazon EC2.

**Importante**  
Aplicativos preocupados com a segurança que ainda não estão usando uma solução baseada em um provedor com as credenciais do Secrets Manager bloqueadas no aplicativo devem considerar o uso de SDKs ou soluções de cache específicos do idioma AWS. Para obter mais informações, consulte [Obtenção de segredos](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html).