Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.crewai.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Visão Geral

Este guia configura o AWS Secrets Manager como provedor de segredos usando Workload Identity Federation: a CrewAI Platform emite tokens OIDC de curta duração, os troca por credenciais AWS via STS e lê seus segredos — sem que uma chave de acesso AWS de longa duração seja armazenada em lugar algum.
Por que este caminho: os segredos são resolvidos no momento de execução da automação, então valores rotacionados se propagam para o próximo kickoff sem novo deploy. Se você só precisa de credenciais estáticas e não se importa com a propagação de rotação, veja o guia mais simples AWS — chaves estáticas / AssumeRole.

​
Como funciona em runtime

  1. O worker do deployment solicita um JWT OIDC fresco à CrewAI Platform.
  2. O worker chama sts:AssumeRoleWithWebIdentity no role IAM que você configurou abaixo, apresentando o JWT.
  3. O AWS STS valida o JWT contra o issuer OIDC público da CrewAI Platform (então sua instalação da plataforma deve ser acessível a partir da AWS), depois retorna credenciais AWS de curta duração.
  4. O worker usa essas credenciais para chamar secretsmanager:GetSecretValue.
  5. O valor obtido é injetado como valor da variável de ambiente para aquele kickoff de automação.
Tokens OIDC subject são cacheados por ~1 hora para evitar reemissão a cada kickoff. Valores de segredos são buscados frescos a cada kickoff independentemente do estado do cache OIDC, e é isso que torna este caminho consciente de rotação.

​
Pré-requisitos

Antes de começar, certifique-se de que você tem:
  • A imagem do pod de automação deve incluir o runtime da CrewAI versão 1.14.5 ou superior.
  • Uma conta AWS com permissão para criar provedores IAM OIDC, roles IAM e políticas IAM.
  • A região AWS onde seus segredos vivem (ou viverão), ex. us-east-1.
  • Uma organização na CrewAI Platform onde seu usuário tem as permissões workload_identity_configs: manage e secret_providers: manage. Veja Permissões (RBAC).
  • O UUID da sua organização CrewAI. Encontre-o na página de configurações da organização na CrewAI Platform — a trust policy no Passo 3 vincula o role IAM a esta organização específica.
  • Sua instalação da CrewAI Platform deve ser acessível a partir da AWS via HTTPS para que o AWS STS possa buscar o documento de discovery OIDC e o JWKS durante a validação do token. Confirme com o administrador da sua plataforma que o host é acessível pela internet (ou que a AWS tem alcance de rede até ele via VPC peering / equivalente).

​
Passo 1 — Encontre a URL do Issuer OIDC da Sua CrewAI Platform

Sua instalação da CrewAI Platform publica um documento de discovery OpenID Connect em https://<your-platform-host>/.well-known/openid-configuration. O campo issuer nesse documento é a URL que a AWS registrará como provedor OIDC confiável. Abra a URL em um navegador (substituindo <your-platform-host> pelo seu hostname real, ex. app.crewai.com): 
https://<your-platform-host>/.well-known/openid-configuration
Você deverá ver um JSON contendo: 
{
  "issuer": "https://<your-platform-host>",
  "jwks_uri": "https://<your-platform-host>/oauth2/jwks",
  ...
}
Anote o valor exato de issuer — você o usará no Passo 3.
Se a URL retornar 404 ou 503, contate o administrador da sua plataforma. O issuer OIDC requer uma chave de assinatura privada configurada no momento da instalação. Veja o guia de instalação da plataforma para as configurações OIDC_PRIVATE_KEY e OIDC_ISSUER.

​
Passo 2 — Registrar a CrewAI Platform como um IAM OIDC Identity Provider

Abra o console IAM → Identity providers e clique em Add provider.
  • Provider type: OpenID Connect.
  • Provider URL: o valor de issuer do Passo 1 (ex. https://app.crewai.com).
  • Audience: sts.amazonaws.com
Clique em Add provider. Ou via CLI: 
aws iam create-open-id-connect-provider \
  --url "https://<your-platform-host>" \
  --client-id-list "sts.amazonaws.com" \
  --thumbprint-list "$(echo | openssl s_client -servername <your-platform-host> -connect <your-platform-host>:443 2>/dev/null | openssl x509 -fingerprint -noout -sha1 | cut -d= -f2 | tr -d ':')"
Copie o OpenIDConnectProviderArn da saída (ou o ARN do provedor no console). Você o usará no Passo 3.
A AWS não valida de fato o thumbprint para chamadas STS WebIdentity — ela sempre re-busca o JWKS no momento da validação — mas a API requer que o campo esteja presente.

​
Passo 3 — Criar o Role IAM

Salve como trust-policy.json, substituindo <YOUR_ACCOUNT_ID>, <your-platform-host> (o host do issuer sem https:// ou http://, ex. app.crewai.com) e <YOUR_CREWAI_ORG_UUID> (dos Pré-requisitos): 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<YOUR_ACCOUNT_ID>:oidc-provider/<your-platform-host>"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "<your-platform-host>:aud": "sts.amazonaws.com",
          "<your-platform-host>:sub": "organization:<YOUR_CREWAI_ORG_UUID>"
        }
      }
    }
  ]
}
Crie o role: 
aws iam create-role \
  --role-name crewai-secrets-reader \
  --assume-role-policy-document file://trust-policy.json
Copie o Role Arn da saída — esse é seu aws_role_arn. Você o colará na CrewAI Platform no Passo 6.
As duas condições escopam a confiança com precisão: aud restringe a assunção a tokens com a audience do AWS STS, e sub escopa a federação a uma organização CrewAI específica — apenas tokens emitidos para as automações dessa org são aceitos. A CrewAI Platform sempre define ambas as claims nos tokens de workload identity da AWS.

​
Passo 4 — Criar e anexar a política IAM para acesso ao Secrets Manager + KMS

Salve como secrets-policy.json, substituindo os placeholders pelo ID da sua conta, região, prefixo do nome do segredo e o(s) ARN(s) da chave KMS que criptografa(m) esses segredos: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "SecretsManagerListForUI",
      "Effect": "Allow",
      "Action": "secretsmanager:ListSecrets",
      "Resource": "*"
    },
    {
      "Sid": "SecretsManagerRead",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue"
      ],
      "Resource": "arn:aws:secretsmanager:<REGION>:<YOUR_ACCOUNT_ID>:secret:<SECRET_NAME_PREFIX>-*"
    },
    {
      "Sid": "KMSDecrypt",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt"
      ],
      "Resource": "arn:aws:kms:<REGION>:<YOUR_ACCOUNT_ID>:key/<KMS_KEY_ID>"
    }
  ]
}
SecretsManagerListForUI alimenta o autocomplete de Secret Name no formulário de Environment Variables e o botão Test Connection na credencial. secretsmanager:ListSecrets só aceita Resource: "*" — é escopado por conta na camada IAM. Anexe a política ao role usando a CLI (política inline, mais simples) ou a UI do console; para ambientes que reutilizam as mesmas permissões em vários roles, use a aba Managed policy para uma política nomeada e reutilizável. 
aws iam put-role-policy \
  --role-name crewai-secrets-reader \
  --policy-name SecretsManagerRead \
  --policy-document file://secrets-policy.json
Isso anexa a política inline ao role. Políticas inline são vinculadas ao role e não podem ser reutilizadas em outros roles.

​
Passo 5 — Criar Pelo Menos Um Segredo na AWS

Se você ainda não tem um segredo para testar, crie um agora: 
aws secretsmanager create-secret \
  --region <REGION> \
  --name crewai-test-keyword \
  --secret-string "hello from aws"
Ou pelo console do AWS Secrets Manager → Store a new secret.

​
Passo 6 — Adicionar uma Configuração de Workload Identity na CrewAI Platform

Na CrewAI Platform, navegue até Settings → Workload Identity e clique em Add Workload Identity Config. Preencha o formulário:
  • Name: Um nome descritivo, ex. aws-prod.
  • Cloud Provider: AWS.
  • AWS Role ARN: o Role Arn do Passo 3.
  • AWS Region: a região onde seus segredos vivem, ex. us-east-1.
  • (Opcional) Marque Set as default for AWS se você quiser que esta config WI seja a padrão selecionada ao criar uma credencial de segredo baseada em AWS.
Clique em Create.

​
Passo 7 — Adicionar uma Credencial de Provedor de Segredos Vinculada à Config WI

Navegue até Settings → Secret Provider Credentials e clique em Add Credential. Preencha o formulário:
  • Name: Um nome descritivo, ex. aws-prod-wi.
  • Provider: AWS Secrets Manager.
  • Authentication Method: Workload Identity (em vez de chaves estáticas / AssumeRole).
  • Workload Identity Configuration: selecione a config que você criou no Passo 6 (ex. aws-prod).
  • (Opcional) Marque Set as default credential for this provider.
O formulário pedirá apenas a AWS Region sob Workload Identity — os campos de credencial estática (Access Key ID, Secret Access Key, Role ARN, External ID) estão intencionalmente ocultos porque não se aplicam a este caminho; o ARN do role vem da config WI vinculada. Clique em Create.

​
Passo 8 — Testar a Conexão

Depois de salvar a credencial, clique em Test Connection. Para credenciais workload-identity isso verifica o handshake OIDC: a CrewAI Platform emite um JWT, troca-o com o AWS STS via sts:AssumeRoleWithWebIdentity e confirma que as credenciais resultantes podem chamar sts:GetCallerIdentity contra o role assumido. Um resultado verde significa que o vínculo de federação está saudável. Um Test Connection bem-sucedido prova que a trust policy, o registro do provedor OIDC e a condição de audience estão todos conectados corretamente. Ele não prova que o IAM por segredo está correto — secretsmanager:GetSecretValue em um ARN de segredo específico é exercitado separadamente quando uma variável de ambiente é resolvida no kickoff. Veja Solução de Problemas para modos de falha de handshake.

​
Passo 9 — Referenciar o Segredo em uma Variável de Ambiente

Agora referencie o segredo em uma automação, exatamente como você faria para qualquer outra env var apoiada pelo Secrets Manager. Veja Usando o Secrets Manager para os campos do formulário e o comportamento. A única diferença entre env vars apoiadas por WI e por chaves estáticas é quando o segredo é lido:
  • Apoiado por WI: o valor do segredo é lido de forma fresca a cada kickoff de automação.
  • Apoiado por chaves estáticas: o valor do segredo é lido no momento do deploy e incorporado à imagem do deployment.

​
Passo 10 — Verificar a Rotação

Após o deployment estar rodando, rotacione o segredo na AWS: 
aws secretsmanager update-secret \
  --region <REGION> \
  --secret-id crewai-test-keyword \
  --secret-string "rotated value"
Dispare um novo kickoff de automação. O ambiente do kickoff verá "rotated value" — sem novo deploy, sem reinício de worker, sem esperar TTL. Para confirmar nos logs (se você tiver acesso ao worker), procure por: 
Workload identity config '<id>' (aws): N secret(s) resolved
Esta linha aparece para cada kickoff e indica uma chamada GetSecretValue fresca contra a AWS.

​
Solução de Problemas

SintomaCausa provável
Test Connection falha com erro de handshakeA chamada sts:AssumeRoleWithWebIdentity foi rejeitada. Verifique se o ARN do principal federado da trust policy referencia oidc-provider/<your-platform-host> (host sem https:// ou http://, sem barra final), se a condição de audience é exatamente sts.amazonaws.com, se a condição sub corresponde ao UUID da sua organização CrewAI e se a URL de discovery OIDC da plataforma é acessível a partir da AWS pela internet pública.
InvalidIdentityToken: Couldn't retrieve verification key from your identity providerO AWS STS não consegue acessar o host da sua CrewAI Platform para buscar o JWKS. Confirme que o host é acessível pela internet a partir da AWS, que a URL de discovery OIDC retorna 200 e que o endpoint JWKS é acessível.
AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentityTrust policy incompatível. Reconfira o Passo 3: o ARN do principal federado deve incluir oidc-provider/<your-platform-host> (host sem https:// ou http://, sem barra final), a condição de audience deve ser exatamente sts.amazonaws.com e a condição sub deve ser igual a organization:<YOUR_CREWAI_ORG_UUID>.
Autocomplete de Secret Name mostra AccessDenied: secretsmanager:ListSecretsO role está sem secretsmanager:ListSecrets com Resource: "*". Adicione a declaração SecretsManagerListForUI do Passo 4.
Kickoff falha ao resolver um segredo mesmo que o Test Connection passeO vínculo WI está saudável, mas o IAM escopado por recurso está ausente no segredo que falha. Audite as permissões secretsmanager:GetSecretValue e kms:Decrypt do role para o ARN específico desse segredo e chave KMS.
RegionDisabledException / nenhum segredo encontradoA região na Workload Identity Config não corresponde a onde o segredo vive. Reconfira o Passo 6.
Valor rotacionado não é pego no próximo kickoffConfirme que a env var na automação está referenciando uma credencial baseada em Workload Identity (não uma credencial de chaves estáticas). O caminho estático incorpora valores à imagem do deploy.

​
Próximos Passos